Documentation

Mistake on this page? Email us

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

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.

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.

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.

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.

Note: For this implementation you must use the PAL Secure Storage reference implementation for mbed-os.

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.

Note: This implementation uses Device Management Client's secure storage for which the PAL Secure Storage module is not required.