AESCTRDRBG driver header.
AES_CTR_DRBG 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.
AES_CTR_DRBG 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 AES_CTR_DRBG 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 AES_CTR_DRBG 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 AES_CTR_DRBG 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 AES_CTR_DRBG instance must be reseeded. The time between reseeding is set by the number of random bit sequences generated not by their individual or combined lengths. Each time random bits are requested of the AES_CTR_DRBG 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 AES_CTR_DRBG 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 and never be reused.
NIST specifies the the use of an optional derivation function to reduced enctropy and personalizationg 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/cryptoutils/cryptokey/CryptoKey.h>
Go to the source code of this file.
Data Structures | |
struct | AESCTRDRBG_Config |
AESCTRDRBG Global configuration. More... | |
struct | AESCTRDRBG_Params |
AESCTRDRBG Parameters. More... | |
Macros | |
#define | AESCTRDRBG_STATUS_RESERVED (-32) |
#define | AESCTRDRBG_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | AESCTRDRBG_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESCTRDRBG_STATUS_RESEED_REQUIRED (-3) |
The AESCTRDRBG instance must be reseeded. More... | |
#define | AESCTRDRBG_AES_BLOCK_SIZE_BYTES 16 |
The AES block size in bytes. More... | |
Typedefs | |
typedef enum AESCTRDRBG_ReturnBehavior_ | AESCTRDRBG_ReturnBehavior |
The way in which AESCTRDRBG function calls return after generating the requested entropy. 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 peripheral specified by the AESCTRDRBG_Handle. More... | |
int_fast16_t | AESCTRDRBG_getBytes (AESCTRDRBG_Handle handle, CryptoKey *randomBytes) |
Generate a requested number of random bytes. More... | |
int_fast16_t | AESCTRDRBG_reseed (AESCTRDRBG_Handle handle, const void *seed, const void *additionalData, size_t additionalDataLength) |
Reseed an AESCTRDRBG instance. More... | |
Variables | |
const AESCTRDRBG_Params | AESCTRDRBG_defaultParams |
Default AESCTRDRBG_Params structure. More... | |
#define AESCTRDRBG_STATUS_RESERVED (-32) |
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 (0) |
Successful status code.
Functions return AESCTRDRBG_STATUS_SUCCESS if the function was executed successfully.
#define AESCTRDRBG_STATUS_ERROR (-1) |
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 (-2) |
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 (-3) |
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_AES_BLOCK_SIZE_BYTES 16 |
The AES block size in bytes.
typedef enum AESCTRDRBG_ReturnBehavior_ AESCTRDRBG_ReturnBehavior |
The way in which AESCTRDRBG function calls return after generating the requested entropy.
Not all AESCTRDRBG operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied 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 |
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 behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied 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 peripheral specified by the AESCTRDRBG_Handle.
[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
int_fast16_t AESCTRDRBG_getBytes | ( | AESCTRDRBG_Handle | handle, |
CryptoKey * | randomBytes | ||
) |
Generate a requested number of random bytes.
[in] | handle | An AESCTRDRBG_Handle returned from AESCTRDRBG_open() |
[in,out] | randomBytes | CryptoKey describing how many random bytes are requested and where to put them. |
AESCTRDRBG_STATUS_SUCCESS | Random bytes generated. |
AESCTRDRBG_STATUS_ERROR | Random bytes not generated. |
AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE | The requires hardware was unavailable. |
AESCTRDRBG_STATUS_RESEED_REQUIRED | Reseed counter >= reseed limit. Reseed required. |
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. |
const AESCTRDRBG_Params AESCTRDRBG_defaultParams |
Default AESCTRDRBG_Params structure.