You use the entropy module to inject random data to non-volatile storage on a target device. The injected data enables the application or operating system on the target to seed Deterministic Random Bit Generator (DRBG) instances or gather entropy. The PAL Crypto module's library updates the non-volatile entropy, when needed, using read and write callbacks that you must provide.
Note: If the target has a True Random Number Generator (TRNG), you do not have to port the Entropy module. However, you can use this module to provide additional security.
pal_plat_entropy.h header declares the application-level entropy functions, which you must implement. The crypto-level functions that you must implement are described below.
Prerequisites for this porting stage
The following are prerequisites for testing the entropy module:
- The PAL Crypto module is required so that the entropy may be used for its actual purpose.
- If you use the PAL SST module, you must port the module so that entropy may be deleted for testing purposes.
- If you do not use the PAL SST module, you must port the PAL Internal Flash module so that entropy may be deleted for testing purposes.
After successfully porting the Entropy module and its testing prerequisites, the Entropy tests should pass. See the Tests section for more information.
This section covers non-trivial functionality that the target needs for a successful port.
Porting for various use cases
Below is a detailed explanation of which module functions you must port for each use case.
Non-volatile entropy is not expected
If you have hardware TRNG and, therefore, do not expect to inject external non-volatile entropy, you can implement the
pal_plat_entropy.h interface by returning the
Using Device Management Client's crypto library
If the target uses Device Management Client's crypto library (a reference implementation of the PAL Crypto module using the Mbed TLS library), see the Mbed TLS documentation, which describes how to port the non-volatile seed feature to your platform.
Using your own crypto library
We do not yet support the entropy feature for the use case in which you implement the PAL Crypto module and use your own crypto library instead of using Device Management Client's crypto library.
PAL provides reference implementations for the following targets and operating systems:
Mbed OS 5.11 and newer
A reference implementation of inject entropy using the
mbedtls_psa_inject_entropy Platform Security Architecture (PSA) API. The implementation is located at
Note: For this implementation you must use the PAL Secure Storage reference implementation for mbed-os.
In Linux, there is an optional
ENTROPYSOURCE system environment variable, which defines the source entropy file path. You must set this environment variable before running the target binary.
Set the Entropy source:
Note: The Linux-platform-dependent default is fetched if
ENTROPYSOURCE is absent or not defined.
Device Management Client secure storage (used on Mbed OS 5.10 and older/Linux platforms)
A platform-agnostic reference implementation of inject entropy. The implementation is located at
Note: This implementation uses Device Management Client's secure storage for which the PAL Secure Storage module is not required.