HAL RNG How to Use

group RNG_How_To_Use

The RNG main features:

The true random number generator (RNG) is a NIST SP 800-90B compliant entropy source that delivers 32-bit random numbers. It has an AMBA AHB slave peripheral, accessible through 32-bit word single accesses only. It can be disabled to reduce power consumption, or enabled with an automatic low power mode (default configuration). The RNG has been pre-certified to NIST SP800-90B, and it has also been tested with the German BSI statistical tests of AIS-31 (T0 to T8).

How to use the HAL RNG driver

The HAL RNG driver can be used as follows:

• Initialize the RNG handle by calling the HAL_RNG_Init() API. This performs these operations:

  • Associate the instance with the handle.

  • Enable the RNG clock interface when the USE_HAL_RNG_CLK_ENABLE_MODEL compilation flag is set to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM in the stm32c5xx_hal_conf.h module.

  • Initialize the handle state to HAL_RNG_STATE_IDLE.

• Configure the RNG peripheral with one of the following configurations:

  • Custom configuration:

    • Declare a hal_rng_config_t structure.

    • Fill all parameters of the declared configuration structure.

    • Call HAL_RNG_SetConfig() with the filled configuration structure.

Candidate NIST compliant configuration:

• Call HAL_RNG_SetCandidateNISTConfig().

Candidate German BSI compliant configuration:

• Call HAL_RNG_SetCandidateGermanBSIConfig().

Additional health test configuration:

• Call HAL_RNG_SetHealthFactorConfig().

Call HAL_RNG_LockConfig() to protect the peripheral from configuration changes. When locked, do not apply any new configuration. Apply configuration only after a system reset or an RNG peripheral reset through RCC.

• When needed, perform unitary reconfiguration through:

  • HAL_RNG_EnableClockErrorDetection() and HAL_RNG_DisableClockErrorDetection() to enable (respectively disable) the clock error detection feature.

  • HAL_RNG_EnableAutoReset() and HAL_RNG_DisableAutoReset() to enable (respectively disable) the automatic reset after a seed error.

  • HAL_RNG_SetClockDivider() to set a new kernel clock divider.

• The RNG can generate random numbers in two different modes:

  • Polling mode:

    1. Call HAL_RNG_GenerateRandomNumber() and specify:

       • The number of words to be generated.

       • The application buffer where the data will be stored.

The maximum timeout for random number words to be generated.

1. When a seed error occurs, call HAL_RNG_RecoverSeedError(). (Recovery is not guaranteed through this function due to hardware constraints.)

Interrupt mode operation:

1. Call HAL_RNG_GenerateRandomNumber_IT() and specify:

   • The number of words to be generated.

   • The application buffer where the data will be stored.

2. Call HAL_RNG_IRQHandler() to handle RNG interrupts and store the generated number words in the specified user buffer.

3. When all random numbers specified by the user are generated, HAL_RNG_GenerationCpltCallback() executes.

4. When a seed error occurs during the generation process, HAL_RNG_ErrorCallback() executes. Call HAL_RNG_RecoverSeedError().

To deinitialize the RNG peripheral, call HAL_RNG_DeInit().

• Retrieve HAL RNG information:

  • Use HAL_RNG_GetState() to return the RNG state.

  • Use HAL_RNG_GetConfig() to get the RNG configuration.

  • Use HAL_RNG_IsEnabledClockErrorDetection() to check whether the clock error detection feature is enabled.

  • Use HAL_RNG_IsEnabledAutoReset() to check whether the auto reset feature is enabled.

  • Use HAL_RNG_GetClockDivider() to get the clock divider configuration.

  • Set the compilation flag USE_HAL_RNG_GET_LAST_ERRORS to 1U in the stm32c5xx_hal_conf.h module to retrieve the last error code detected by the HAL RNG driver through the HAL_RNG_GetLastErrorCodes API.

• Register callbacks:

  • When the compilation flag USE_HAL_RNG_REGISTER_CALLBACKS is set to 1 in the stm32c5xx_hal_conf.h, it allows dynamic configuration of the driver callbacks instead of using the default ones.

  • Call HAL_RNG_RegisterGenerationCpltCallback() for end-of-generation random number events.

  • Call HAL_RNG_RegisterErrorCallback() for random number generation error events.