MCUX CLNS MCUX Crypto Library Normal Secure |

Functions
mcuxClCss_Rng_Functions
mcuxClCss » mcuxClCss_Rng

Defines all functions of mcuxClCss_Rng. More...

## Functions

MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_DrbgRequest_Async (uint8_t *pOutput, size_t outputLength)
| Writes random data from the CSS DRBG to the given buffer. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_DrbgTestInstantiate_Async (uint8_t const *pEntropy)
| Instantiates the DRBG in test mode. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_DrbgTestExtract_Async (uint8_t *pOutput, size_t outputLength)
| Performs a DRBG extraction. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_DrbgTestAesEcb_Async (uint8_t const *pDataKey, uint8_t *pOutput)
| Encrypts data using the AES-ECB engine of the DRBG. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_DrbgTestAesCtr_Async (uint8_t const *pData, size_t dataLength, uint8_t const *pIvKey, uint8_t *pOutput)
| Encrypts data using the AES-CTR engine of the DRBG. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_Dtrng_ConfigLoad_Async (uint8_t const *pInput)
| Loads a configuration of the CSS DTRNG. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Rng_Dtrng_ConfigEvaluate_Async (uint8_t const *pInput, uint8_t *pOutput)
| Performs characterization of the CSS DTRNG. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Prng_GetRandomWord (uint32_t *pWord)
| Returns one random word from the CSS PRNG. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Prng_GetRandom (uint8_t *pOutput, size_t outputLength)
| Writes random data from the CSS PRNG to the given buffer. More...

## Detailed Description

Defines all functions of mcuxClCss_Rng.

## Function Documentation

## ◆ mcuxClCss_Rng_DrbgRequest_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_DrbgRequest_Async | ( | uint8_t * | pOutput,
|  | size_t | outputLength
| ) |  |

Writes random data from the CSS DRBG to the given buffer.

This function fills a buffer with random values from the DRBG. The DRBG provides 128 bits of security strength.

Before execution, CSS will wait until mcuxClCss_HwState_t.drbgentlvl == MCUXCLCSS_STATUS_DRBGENTLVL_HIGH. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

If the random values from the DRBG are later used as a cryptographic key, the security strength of the cryptographic operation using the generated key should not exceed that of the DRBG.

To name a few examples, this means (as per NIST SP 800-57 Part 1 Rev. 5):

- AES-192 or AES-256 keys generated with this function will provide only 128 bits of security strength
- RSA keys longer than 3072 bits will provide only 128 bits of security strength
- ECC keys longer than 383 bits will provide only 128 bits of security strength

Call mcuxClCss_WaitForOperation to complete the operation.

Parameters

  [out] | pOutput | Pointer to the beginning of the memory area to fill with random data
  [in] | outputLength | Number of requested random bytes

Parameter properties
  `outputLength`
    supported values are MCUXCLCSS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MIN_SIZE bytes up to MCUXCLCSS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MAX_SIZE bytes. The size must be a multiple of 4.

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Rng_DrbgTestInstantiate_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_DrbgTestInstantiate_Async | ( | uint8_t const * | pEntropy | ) |

Instantiates the DRBG in test mode.

This function is a support function for FIPS CAVP testing. This function turns the CSS internal DRBG in test mode by loading known entropy from system memory. Call mcuxClCss_WaitForOperation to complete the operation. Note that this function will alter the CSS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters

  [in] | pEntropy | Pointer to the input entropy data

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Rng_DrbgTestExtract_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_DrbgTestExtract_Async | ( | uint8_t * | pOutput,
|  | size_t | outputLength
| ) |  |

Performs a DRBG extraction.

This function is a support function for FIPS CAVP testing. This function mimics the behavior of mcuxClCss_Rng_DrbgRequest_Async and fills a buffer with random data when DRBG is in test mode. Call mcuxClCss_WaitForOperation to complete the operation. Note that this function will alter the CSS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Attention
  mcuxClCss_Rng_DrbgTestInstantiate_Async must be called prior to this function.

Parameters

  [out] | pOutput | Pointer to the output random number
  [in] | outputLength | Length of the random number

Parameter properties
  `outputLength`
    supported values are MCUXCLCSS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MIN_SIZE bytes up to MCUXCLCSS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MAX_SIZE bytes. The size must be a multiple of 4.

Returns
  An error code (see MCUXCLCSS_STATUS_)

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Rng_DrbgTestAesEcb_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_DrbgTestAesEcb_Async | ( | uint8_t const * | pDataKey,
|  | uint8_t * | pOutput
| ) |  |

Encrypts data using the AES-ECB engine of the DRBG.

This function is a support function for FIPS CAVP testing. This function performs an AES-ECB encryption on system data to evaluate the encryption engine of the DRBG. Call mcuxClCss_WaitForOperation to complete the operation. Note that this function will alter the CSS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters

  [in] | pDataKey | Pointer to the data and key
  [out] | pOutput | Pointer to the encrypted output

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Rng_DrbgTestAesCtr_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_DrbgTestAesCtr_Async | ( | uint8_t const * | pData,
|  | size_t | dataLength,
|  | uint8_t const * | pIvKey,
|  | uint8_t * | pOutput
| ) |  |

Encrypts data using the AES-CTR engine of the DRBG.

This function is a support function for FIPS CAVP testing. This function performs an AES-CTR encryption on system data to evaluate the encryption engine of the DRBG in test mode. Call mcuxClCss_WaitForOperation to complete the operation. Note that this function will alter the CSS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters

  [in] | pData | Pointer to the data to be encrypted
  [in] | dataLength | Length of the data to be encrypted
  [in] | pIvKey | Pointer to the IV and key
  [out] | pOutput | Pointer to the encrypted output

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Rng_Dtrng_ConfigLoad_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_Dtrng_ConfigLoad_Async | ( | uint8_t const * | pInput | ) |

Loads a configuration of the CSS DTRNG.

This function overwrites the default DTRNG configuration in order to optimize or fine tune the DTRNG entropy gathering process. Call mcuxClCss_WaitForOperation to complete the operation. Note that the TRNG configuration set by this function is non-persistent and any reset of the Css (e.g. a power-cycle or calling mcuxClCss_Reset_Async) will resets the DTRNG configuration to its default value.

Parameters

  [in] | pInput | The pointer to DTRNG initialization data

Parameter properties
  `pInput`
    The size is MCUXCLCSS_RNG_DTRNG_CONFIG_SIZE bytes.

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Rng_Dtrng_ConfigEvaluate_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Rng_Dtrng_ConfigEvaluate_Async | ( | uint8_t const * | pInput,
|  | uint8_t * | pOutput
| ) |  |

Performs characterization of the CSS DTRNG.

This function evaluates a DTRNG configuration for device specific characterization. The configuration used for characterization has to be placed in system memory. Call mcuxClCss_WaitForOperation to complete the operation.

Attention
  If this function is called once, all other CSS commands except mcuxClCss_Rng_Dtrng_ConfigEvaluate_Async are blocked until any reset of the Css (e.g. a power-cycle or calling mcuxClCss_Reset_Async) is triggered.

Parameters

  [in] | pInput | The pointer to DTRNG initialization data
  [out] | pOutput | The pointer to the evaluation result

Parameter properties
  `pInput`
    The size is MCUXCLCSS_RNG_DTRNG_EVAL_CONFIG_SIZE bytes.
  `pOutput`
    The size is MCUXCLCSS_RNG_DTRNG_EVAL_RESULT_SIZE bytes.

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

## ◆ mcuxClCss_Prng_GetRandomWord()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Prng_GetRandomWord | ( | uint32_t * | pWord | ) |

Returns one random word from the CSS PRNG.

This function returns one low-quality random CPU word gathered from the PRNG.

Attention
  PRNG has to be initialized prior to the first time calling this function.

Parameters

  [out] | pWord | The pointer to the random word

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_OK | on successful request
  MCUXCLCSS_STATUS_HW_PRNG | in case of insufficient entropy

Examples
  rng_prng_get_random.c.

## ◆ mcuxClCss_Prng_GetRandom()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Prng_GetRandom | ( | uint8_t * | pOutput,
|  | size_t | outputLength
| ) |  |

Writes random data from the CSS PRNG to the given buffer.

This function fills a buffer with low-quality random values gathered from the PRNG.

Attention
  PRNG has to be initialized prior to the first time calling this function.

Parameters

  [out] | pOutput | Pointer to the beginning of the memory area to fill with random data from PRNG
  [in] | outputLength | Size of `pOutput` in bytes

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_OK | on successful request
  MCUXCLCSS_STATUS_HW_PRNG | in case of insufficient entropy

Examples
  rng_prng_get_random.c, and tls_master_key_session_keys.c.