Entropy

Module scope

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.

The 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

If you do not use Device Management Client's secure storage, you must port the PAL Internal Flash module so that you can delete entropy for testing purposes.

Porting result

After successfully porting the Entropy module and its testing prerequisites, the Entropy tests should pass. See the Tests section for more information.

Porting notes

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 PAL_ERR_NOT_SUPPORTED error.

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.

Reference implementations

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 Source/Port/Reference-Impl/OS_Specific/mbedOS/Entropy/pal_plat_entropy_mbed.c.

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 Source/Port/Reference-Impl/Generic/Entropy/pal_plat_entropy_sotp.c.