AESCTRDRBG driver header.
AESCTRDRBG is a cryptographically secure deterministic random bit generator that is used to efficiently generate random numbers for use in keying material or other security related purposes. It is based on the AES block cipher operating in Counter (CTR) mode and is defined by NIST SP 800-90A.
AESCTRDRBG derives a sequence of pseudo-random numbers based on an initial secret seed and additional, non-secret personalization data provided during instantiation. A sequence of random bits generated by AESCTRDRBG will have an equivalent entropy content of MIN(sequenceLength, security strength). The security strength is based on the seed length and the AES key length used in the AESCTRDRBG instance.
AES-128 | AES-192 | AES-256 | |
---|---|---|---|
Security Strength (bits) | 128 | 192 | 256 |
Seed Length (bits) | 192 | 320 | 384 |
Personalization String Length (bits) | <= 192 | <= 320 | <= 384 |
Max Requests Between Reseeds | 2^48 | 2^48 | 2^48 |
Max Request Length (bits) | 2^19 | 2^19 | 2^19 |
The seed must be sourced from a cryptographically secure source such as a True Random Number Generator and contain seed length bits of entropy. Since the seed length is always larger than the security strength for any one AES key length, the output of one AESCTRDRBG instance may not be used to seed another instance of the same or higher security strength.
Because of the way AES CTR operates, there are a limited number of output bitstreams that may be generated before the AESCTRDRBG instance must be reseeded. The reseeding interval is set by the number of random bit sequences generated and not by their individual or combined lengths. Each time random bits are requested of the AESCTRDRBG instance by the application, the reseed counter is incremented by one regardless of how many bits at a time are requested. When this counter reaches the configured reseed limit, the AESCTRDRBG instance will return AESCTRDRBG_STATUS_RESEED_REQUIRED until it is reseeded.
The maximum permitted number of requests between reseeds is 2^48. The default counter is only 2^32 long for ease of implementation. A more conservative reseed limit may be configured by the application for increased security.
A previously used seed may never be reused to reseed an AESCTRDRBG instance. The seed used to instantiate or reseed an instance must be generated by an approved entropy source.
NIST specifies the the use of an optional derivation function to reduced entropy and personalization string lengths longer than the seed length down to the seed length. This feature is not presently supported.
This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/AESCTR.h>
#include <ti/drivers/AESCommon.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Go to the source code of this file.
Data Structures | |
struct | AESCTRDRBG_Params |
AESCTRDRBG Parameters. More... | |
Typedefs | |
typedef AESCommon_Config | AESCTRDRBG_Config |
AESCTRDRBG Global configuration. More... | |
typedef AESCTRDRBG_Config * | AESCTRDRBG_Handle |
A handle that is returned from an AESCTRDRBG_open() call. More... | |
Enumerations | |
enum | AESCTRDRBG_AES_KEY_LENGTH { AESCTRDRBG_AES_KEY_LENGTH_128 = 16, AESCTRDRBG_AES_KEY_LENGTH_256 = 32 } |
Length in bytes of the internal AES key used by an instance. More... | |
enum | AESCTRDRBG_SEED_LENGTH { AESCTRDRBG_SEED_LENGTH_AES_128 = AESCTRDRBG_AES_KEY_LENGTH_128 + 16, AESCTRDRBG_SEED_LENGTH_AES_256 = AESCTRDRBG_AES_KEY_LENGTH_256 + 16 } |
Length in bytes of seed used to instantiate or reseed instance. More... | |
enum | AESCTRDRBG_ReturnBehavior { AESCTRDRBG_RETURN_BEHAVIOR_BLOCKING = AESCTR_RETURN_BEHAVIOR_BLOCKING, AESCTRDRBG_RETURN_BEHAVIOR_POLLING = AESCTR_RETURN_BEHAVIOR_POLLING } |
The way in which AESCTRDRBG function calls return after generating the requested entropy. More... | |
Functions | |
void | AESCTRDRBG_init (void) |
This function initializes the AESCTRDRBG driver. More... | |
void | AESCTRDRBG_Params_init (AESCTRDRBG_Params *params) |
Function to initialize the AESCTRDRBG_Params struct to its defaults. More... | |
AESCTRDRBG_Handle | AESCTRDRBG_open (uint_least8_t index, const AESCTRDRBG_Params *params) |
This function opens a given AESCTRDRBG instance. More... | |
void | AESCTRDRBG_close (AESCTRDRBG_Handle handle) |
Function to close an AESCTRDRBG instance specified by the AESCTRDRBG_Handle. More... | |
int_fast16_t | AESCTRDRBG_getBytes (AESCTRDRBG_Handle handle, CryptoKey *randomBytes) |
Generates the requested number of random bytes. More... | |
int_fast16_t | AESCTRDRBG_generateKey (AESCTRDRBG_Handle handle, CryptoKey *randomKey) |
Populates the provided CryptoKey object's plaintext key-material with random bytes. More... | |
int_fast16_t | AESCTRDRBG_getRandomBytes (AESCTRDRBG_Handle handle, void *randomBytes, size_t randomBytesSize) |
Generates the requested number of random bytes and outputs to the given array. More... | |
int_fast16_t | AESCTRDRBG_reseed (AESCTRDRBG_Handle handle, const void *seed, const void *additionalData, size_t additionalDataLength) |
Reseed an AESCTRDRBG instance. More... | |
AESCTRDRBG_Handle | AESCTRDRBG_construct (AESCTRDRBG_Config *config, const AESCTRDRBG_Params *params) |
Constructs a new AESCTRDRBG object. More... | |
Variables | |
const AESCTRDRBG_Params | AESCTRDRBG_defaultParams |
Default AESCTRDRBG_Params structure. More... | |
#define AESCTRDRBG_STATUS_RESERVED AES_STATUS_RESERVED |
Common AESCTRDRBG status code reservation offset. AESCTRDRBG driver implementations should offset status codes with AESCTRDRBG_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define AESCTRDRBG_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code.
Functions return AESCTRDRBG_STATUS_SUCCESS if the function was executed successfully.
#define AESCTRDRBG_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code.
Functions return AESCTRDRBG_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.
#define AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable.
AESCTRDRBG driver implementations may have hardware or software limitations on how many clients can simultaneously perform operations. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.
#define AESCTRDRBG_STATUS_RESEED_REQUIRED (AES_STATUS_DRIVER_SPECIFIC_ERROR - 0) |
The AESCTRDRBG instance must be reseeded.
An AESCTRDRBG instance may only service a limited number of bit generation requests before reseeding with more entropy is required.
#define AESCTRDRBG_STATUS_UNINSTANTIATED (AES_STATUS_DRIVER_SPECIFIC_ERROR - 1) |
The AESCTRDRBG instance is uninstantiated. Close and reopen the instance.
#define AESCTRDRBG_STATUS_UNALIGNED_IO_NOT_SUPPORTED (AES_STATUS_DRIVER_SPECIFIC_ERROR - 2) |
The operation does not support non-word-aligned input and/or output.
AESCTR driver implementations used by AESCTRDRBG may have restrictions on the alignment of input/output data due to performance limitations of the hardware.
#define AESCTRDRBG_STATUS_KEYSTORE_ERROR (AES_STATUS_KEYSTORE_GENERIC_ERROR) |
Importing generated key into KeyStore failed.
Functions return AESCTRDRBG_STATUS_KEYSTORE_ERROR if the KeyStore_PSA_importKey() did not return KEYSTORE_PSA_STATUS_SUCCESS
#define AESCTRDRBG_AES_BLOCK_SIZE_BYTES 16 |
The AES block size in bytes.
typedef AESCommon_Config AESCTRDRBG_Config |
AESCTRDRBG Global configuration.
The AESCTRDRBG_Config structure contains a set of pointers used to characterize the AESCTRDRBG driver implementation.
This structure needs to be defined before calling AESCTRDRBG_init() and it must not be changed thereafter.
typedef AESCTRDRBG_Config* AESCTRDRBG_Handle |
A handle that is returned from an AESCTRDRBG_open() call.
The way in which AESCTRDRBG function calls return after generating the requested entropy.
Not all AESCTRDRBG operations exhibit the specified return behavior. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specified return behavior is not implementation dependent. Specifically, a software-backed implementation run on the same CPU as the application will emulate the return behavior while not actually offloading the computation to the background thread.
AESCTRDRBG functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCTRDRBG_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCTRDRBG_RETURN_BEHAVIOR_POLLING | X | X | X |
void AESCTRDRBG_init | ( | void | ) |
This function initializes the AESCTRDRBG driver.
void AESCTRDRBG_Params_init | ( | AESCTRDRBG_Params * | params | ) |
Function to initialize the AESCTRDRBG_Params struct to its defaults.
[out] | params | Pointer to AESCTRDRBG_Params structure for initialization |
AESCTRDRBG_Handle AESCTRDRBG_open | ( | uint_least8_t | index, |
const AESCTRDRBG_Params * | params | ||
) |
This function opens a given AESCTRDRBG instance.
[in] | index | Logical peripheral number for the AESCTRDRBG indexed into the AESCTRDRBG_Config table |
[in] | params | Pointer to an parameter block, if NULL it will use default values. |
void AESCTRDRBG_close | ( | AESCTRDRBG_Handle | handle | ) |
Function to close an AESCTRDRBG instance specified by the AESCTRDRBG_Handle.
[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
int_fast16_t AESCTRDRBG_getBytes | ( | AESCTRDRBG_Handle | handle, |
CryptoKey * | randomBytes | ||
) |
Generates the requested number of random bytes.
[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
[in,out] | randomBytes | Pointer to a CryptoKey object that should be already initialized to hold a plaintext key, provided with the length and the address of the plaintext key-material where the generated random bytes will be populated. Some implementations may require key-material to be word-aligned. |
AESCTRDRBG_STATUS_SUCCESS | Random bytes generated. |
AESCTRDRBG_STATUS_ERROR | Generic driver error. Random bytes not generated. |
AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE | The required hardware was unavailable. Random bytes not generated. |
AESCTRDRBG_STATUS_RESEED_REQUIRED | Reseed counter >= reseed limit. Reseed required. Random bytes not generated. |
AESCTRDRBG_STATUS_UNINSTANTIATED | DRBG uninstantiated. Close and reopen the instance with fresh seed. Random bytes not generated. |
AESCTRDRBG_STATUS_UNALIGNED_IO_NOT_SUPPORTED | Pointer to randomBytes key material must be word-aligned. |
int_fast16_t AESCTRDRBG_generateKey | ( | AESCTRDRBG_Handle | handle, |
CryptoKey * | randomKey | ||
) |
Populates the provided CryptoKey
object's plaintext key-material with random bytes.
[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
[in,out] | randomKey | Pointer to a CryptoKey object that should be already initialized to hold a plaintext key, provided with the length and the address of the plaintext key-material where the generated random bytes will be populated. Some implementations may require key-material to be word-aligned. |
AESCTRDRBG_STATUS_SUCCESS | Key-material generated. |
AESCTRDRBG_STATUS_ERROR | Generic driver error. Key-material not generated. |
AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE | The required hardware was unavailable. Key-material not generated. |
AESCTRDRBG_STATUS_RESEED_REQUIRED | Reseed counter >= reseed limit. Reseed required. Key-material not generated. |
AESCTRDRBG_STATUS_UNINSTANTIATED | DRBG uninstantiated. Close and reopen the instance with fresh seed. Key-material not generated. |
AESCTRDRBG_STATUS_UNALIGNED_IO_NOT_SUPPORTED | Pointer to randomKey key material must be word-aligned. |
int_fast16_t AESCTRDRBG_getRandomBytes | ( | AESCTRDRBG_Handle | handle, |
void * | randomBytes, | ||
size_t | randomBytesSize | ||
) |
Generates the requested number of random bytes and outputs to the given array.
CryptoKey
while this new function outputs random bytes to an array.CryptoKey
instead.[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
[out] | randomBytes | A pointer to an array that stores the random bytes output by this function. Some implementations may require this array to be word-aligned. |
[in] | randomBytesSize | The size in bytes of the random data required. |
AESCTRDRBG_STATUS_SUCCESS | Random bytes generated. |
AESCTRDRBG_STATUS_ERROR | Generic driver error. Random bytes not generated. |
AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE | The required hardware was unavailable. Random bytes not generated. |
AESCTRDRBG_STATUS_RESEED_REQUIRED | Reseed counter >= reseed limit. Reseed required. Random bytes not generated. |
AESCTRDRBG_STATUS_UNINSTANTIATED | DRBG uninstantiated. Close and reopen the instance with fresh seed. Random bytes not generated. |
AESCTRDRBG_STATUS_UNALIGNED_IO_NOT_SUPPORTED | Pointer to randomBytes array must be word-aligned. |
int_fast16_t AESCTRDRBG_reseed | ( | AESCTRDRBG_Handle | handle, |
const void * | seed, | ||
const void * | additionalData, | ||
size_t | additionalDataLength | ||
) |
Reseed an AESCTRDRBG instance.
[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
[in] | seed | Entropy to mix into the AESCTRDRBG instance state |
[in] | additionalData | Optional non-secret additional data to mix into the instance state. |
[in] | additionalDataLength | Length of the optional additional data. 0 <= additionalDataLength <= seed length of the instance. |
AESCTRDRBG_STATUS_SUCCESS | Reseed successful. Reseed counter reset. |
AESCTRDRBG_STATUS_ERROR | Reseed not successful. Reseed counter not reset. |
AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE | The requires hardware was unavailable. |
AESCTRDRBG_STATUS_UNINSTANTIATED | DRBG uninstantiated. Close and reopen the instance with fresh seed. |
AESCTRDRBG_Handle AESCTRDRBG_construct | ( | AESCTRDRBG_Config * | config, |
const AESCTRDRBG_Params * | params | ||
) |
Constructs a new AESCTRDRBG object.
Unlike AESCTRDRBG_open(), AESCTRDRBG_construct() does not require the hwAttrs and object to be allocated in a AESCTRDRBG_Config array that is indexed into. Instead, the AESCTRDRBG_Config, hwAttrs, and object can be allocated at any location. This allows for relatively simple run-time allocation of temporary driver instances on the stack or the heap. The drawback is that this makes it more difficult to write device-agnostic code. If you use an ifdef with DeviceFamily, you can choose the correct object and hwAttrs to allocate. That compilation unit will be tied to the device it was compiled for at this point. To change devices, recompilation of the application with a different DeviceFamily setting is necessary.
config | AESCTRDRBG_Config describing the location of the object and hwAttrs. |
params | AESCTRDRBG_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const AESCTRDRBG_Params AESCTRDRBG_defaultParams |
Default AESCTRDRBG_Params structure.