|
|
TRNG driver implementation for CC27XX and CC35XX device families.
This file should only be included in the board file to fill the TRNG_config struct.
The CC27XX and CC35XX device families have a dedicated hardware engine, the Hardware Security Module (HSM) that contains TRNG capabilities based on sampling multiple free running oscillators (FROs).
The driver submits a get random number token to the HSM. The token will indicate the destination buffer and the request size.
The TRNG driver can be used as a True Random Number Generator (TRNG) or as a Cryptographically Secure Pseudo Random Number Generator (CRNG). CRNG is a deterministic (hence the pseudo) computational method to turn an input (FRO samples) into a sequence of bits that are indistinguishable from ideal randomness, with cryptographic certainty, for a computationally bounded adversary not knowing the input.
By default, the HSM HW is configured and initialized to be in CRNG mode. To switch to TRNG, the user must call TRNGLPF3HSM_switchNrbgMode() API and specify TRNG_MODE_TRNG as the NRBG Mode.
When the HSM EIP-130 HW in CRNG mode, the Mix Cycles value represents the number of clock cycles before the output is sampled. The MixCycles value must be in the range [0...15]. However, in the current implementation the value 0 is interpreted as not configured and therefore will be set to 15 internally, which is also the default value.
When the HSM EIP-130 HW is in TRNG mode, the Samples Per Cycle value represents the number of (XOR-ed) FRO samples XOR-ed together to generate a single 'noise' bit. This value must be set such that the total amount of entropy in 8 'noise' bits equals at least 1 bit. The value to program here depends upon the jitter behavior of the FROs.
!!!!!!!!!!!!! WARNING !!!!!!!!!!!!! The HSM HW engine is configured and initialized with the Samples Per Cycle value set to 19390 and Mix Cycles value set to 15. This value is not available for the customer to configure.
#include <stdint.h>#include <stdbool.h>#include <ti/drivers/Power.h>#include <ti/drivers/TRNG.h>#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>#include <ti/drivers/dpl/HwiP.h>#include <ti/drivers/dpl/SemaphoreP.h>
Go to the source code of this file.
Data Structures | |
| struct | TRNGLPF3HSM_HWAttrs |
| TRNGLPF3HSM Hardware Attributes. More... | |
Macros | |
| #define | TRNG_STATUS_ALREADY_IN_SPECIFIED_NRBG_TYPE ((int_fast16_t)(TRNG_STATUS_RESERVED - 0)) |
| TRNG driver already in specified NRBG type. More... | |
| #define | TRNG_STATUS_INVALID_INPUT_SIZE ((int_fast16_t)(TRNG_STATUS_RESERVED - 1)) |
| Input size is not a multiple of a 32-bit block. More... | |
| #define | TRNG_STATUS_INVALID_KEY_ENCODING ((int_fast16_t)(TRNG_STATUS_RESERVED - 2)) |
| Invalid Input Key encoding. More... | |
Enumerations | |
| enum | TRNGLFP3HSM_NRBGMode { TRNG_MODE_CRNG = 1, TRNG_MODE_TRNG = 2 } |
| Enum for the NRBG engine type. More... | |
Functions | |
| int_fast16_t | TRNGLPF3HSM_reseedHSM (TRNG_Handle handle) |
| Reseed the HSM IP DRBG engine. More... | |
| int_fast16_t | TRNGLPF3HSM_reseedHSMAsync () |
| Reseed the HSM IP DRBG engine. More... | |
| int_fast16_t | TRNGLPF3HSM_switchNrbgMode (TRNG_Handle handle, TRNGLFP3HSM_NRBGMode nrbgMode) |
| Switches the TRNG driver NRBG Mode between CRNG-based or TRNG-based. More... | |
| #define TRNG_STATUS_ALREADY_IN_SPECIFIED_NRBG_TYPE ((int_fast16_t)(TRNG_STATUS_RESERVED - 0)) |
TRNG driver already in specified NRBG type.
TRNGLPF3HSM_switchNrbg() API will return TRNG_STATUS_ALREADY_IN_SPECIFIED_NRBG_TYPE if the user specifies an NRBG mode and the HSM is in that mode already
| #define TRNG_STATUS_INVALID_INPUT_SIZE ((int_fast16_t)(TRNG_STATUS_RESERVED - 1)) |
Input size is not a multiple of a 32-bit block.
This is an known HSM limitation. Please provide a 32-bit (4 Bytes) aligned input size.
| #define TRNG_STATUS_INVALID_KEY_ENCODING ((int_fast16_t)(TRNG_STATUS_RESERVED - 2)) |
Invalid Input Key encoding.
User needs to either use CryptoKey_BLANK_PLAINTEXT_HSM or CryptoKey_BLANK_PLAINTEXT
| enum TRNGLFP3HSM_NRBGMode |
| int_fast16_t TRNGLPF3HSM_reseedHSM | ( | TRNG_Handle | handle | ) |
Reseed the HSM IP DRBG engine.
Although the HSM IP auto-reseeds internally after a pre-defined level set in the OTP (256 * 64KB) entropy have been fetched, this API is provided to the user to call whenever they want to force a reseed.
This API can only be called in polling and blocking modes only.
| TRNG_STATUS_SUCCESS | Reseeding was successful. |
| TRNG_STATUS_ERROR | Reseeding was not successful. |
| TRNG_STATUS_RESOURCE_UNAVAILABLE | The required hardware was unavailable. |
| int_fast16_t TRNGLPF3HSM_reseedHSMAsync | ( | ) |
Reseed the HSM IP DRBG engine.
Although the HSM IP auto-reseeds internally after a pre-defined level set in the OTP (256 * 64KB) entropy have been fetched, this API is provided to the user to call whenever they want to force a reseed.
This operation is done asynchronously which means the call returns as soon as the request is deposited to the HSM engine and does not notify the user when the operation is complete.
Whilst the operation is running, the underlying HSM access semaphore is taken and no other operations or threads can leverage the HSM IP. The #XXXXX_STATUS_RESOURCE_UNAVAILABLE error code will be returned.
| TRNG_STATUS_SUCCESS | Reseeding was successful. |
| TRNG_STATUS_ERROR | Reseeding was not successful. |
| TRNG_STATUS_RESOURCE_UNAVAILABLE | The required hardware was unavailable. |
| int_fast16_t TRNGLPF3HSM_switchNrbgMode | ( | TRNG_Handle | handle, |
| TRNGLFP3HSM_NRBGMode | nrbgMode | ||
| ) |
Switches the TRNG driver NRBG Mode between CRNG-based or TRNG-based.
This operation will always run in polling or blocking modes only.
| handle | A TRNGLPF3HSM handle returned from TRNGLPF3HSM_open |
| nrbgMode | Either TRNG_MODE_CRNG or TRNG_MODE_TRNG |