pal_plat_entropy.h File Reference

PAL entropy - platform. This file contains entropy injection as part of the platform layer. More...

#include "pal.h"
#include "pal_entropy.h"
#include <stdint.h>

Go to the source code of this file.

Macros
#define	PAL_PLAT_MAX_ENTROPY_SIZE   48
	The maximum entropy size that may be injected to non-volatile memory. More...

Functions
palStatus_t	pal_plat_osEntropyInject (const uint8_t *entropyBuf, size_t bufSizeBytes)
	Inject entropy to non-volatile memory, so that the random number generator may use it. More...
palStatus_t	pal_plat_osEntropyRead (const char *entropyFileName, uint8_t *randomBufOut, size_t bufSizeBytes, size_t *actualRandomSizeBytesOut)
	Read entropy from non-volatile memory. More...

Detailed Description

PAL entropy - platform. This file contains entropy injection as part of the platform layer.

Macro Definition Documentation

#define PAL_PLAT_MAX_ENTROPY_SIZE   48

The maximum entropy size that may be injected to non-volatile memory.

Function Documentation

palStatus_t pal_plat_osEntropyInject	(	const uint8_t *	entropyBuf,
		size_t	bufSizeBytes
	)

Inject entropy to non-volatile memory, so that the random number generator may use it.

In addition to OS functions, the module implementing pal_plat_drbg.h will hold a deterministic random bit generator (DRBG) instance that works with the entropy injected by this function.

Note: This API call must be placed prior to any function that may attempt to generate a random number, both by the OS or PAL platform DRBG. After this API call, pal_plat_osRandomBuffer_blocking() calls from pal_plat_drbg.h will succeed.

Parameters

entropyBuf	- pointer to buffer containing the entropy.
bufSizeBytes	- size of entropyBuf in bytes.

Returns

PAL_SUCCESS - if operation is successful.

PAL_ERR_NOT_SUPPORTED - code compiled in a way that does not expect entropy to be injected. TRNG must be available to inject entropy.

PAL_ERR_INVALID_ARGUMENT - bufSizeBytes too small.

PAL_ERR_ENTROPY_EXISTS - Entropy already injected.

PAL_ERR_GENERIC_FAILURE - Another cause of error.

palStatus_t pal_plat_osEntropyRead	(	const char *	entropyFileName,
		uint8_t *	randomBufOut,
		size_t	bufSizeBytes,
		size_t *	actualRandomSizeBytesOut
	)

Read entropy from non-volatile memory.

The function firstly reads the file name associated with ENTROPYSOURCE variable if exist in the target system environment, if not, it will explicitly take the entropyFileName given by the caller.

Parameters

entropyFileName	- the default file name to read the entropy from in case system environment ENTROPYSOURCE is absent.
randomBufOut	- pointer to buffer which the entropy source will be written to.
bufSizeBytes	- size of randomBufOut in bytes.
actualRandomSizeBytesOut	- the actual size in bytes written to randomBufOut.

Returns

PAL_SUCCESS - if operation is successful.

PAL_ERR_RTOS_TRNG_FAILED - the entropy source is empty.

PAL_ERR_FS_NO_FILE - The entropy source does not exist.

PAL_ERR_RTOS_TRNG_PARTIAL_DATA - bufSizeBytes too small or too big.