Detailed Description

AESCTRDRBG driver header.

Warning: This is a beta API. It may change in future releases.

Overview

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

Security Strength

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.

Reseeding

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.

Derivation Function

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.

Usage

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.

Synopsis

#include <ti/drivers/AESCTRDRBG.h>
AESCTRDRBG_init();
// Instantiate the AESCTRDRBG instance
AESCTRDRBG_Params_init(&params);
params.keyLength = AESCTRDRBG_AES_KEY_LENGTH_128;
params.reseedInterval = 0xFFFFFFFF;
params.seed = seedBuffer;
handle = AESCTRDRBG_open(0, &params);
result = AESCTRDRBG_getBytes(handle, &resultKey);
reseedResult = AESCTRDRBG_reseed(handle, reseedBuffer, NULL, 0);
AESCTRDRBG_close(handle);

Examples

Instantiating an AESCTRDRBG Instance with TRNG

#include <ti/drivers/AESCTRDRBG.h>
#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
...
    AESCTRDRBG_Handle handle;
    AESCTRDRBG_Params params;
    TRNG_Handle trngHandle;
    CryptoKey seedKey;
    int_fast16_t result;
    uint8_t seedBuffer[AESCTRDRBG_SEED_LENGTH_AES_128];
    // Generate the seed
    trngHandle = TRNG_open(0, NULL);
    if (trngHandle == NULL) {
        // Handle error
        while(1);
    }
    CryptoKeyPlaintext_initBlankKey(&seedKey, seedBuffer, AESCTRDRBG_SEED_LENGTH_AES_128);
    result = TRNG_generateEntropy(trngHandle, &seedKey);
    if (result != TRNG_STATUS_SUCCESS) {
        // Handle error
        while(1);
    }
    TRNG_close(trngHandle);
    // Instantiate the AESCTRDRBG instance
    AESCTRDRBG_Params_init(&params);
    params.keyLength = AESCTRDRBG_AES_KEY_LENGTH_128;
    params.reseedInterval = 0xFFFFFFFF;
    params.seed = seedBuffer;
    handle = AESCTRDRBG_open(0, &params);
    if (handle == NULL) {
        // Handle error
        while(1);
    }

Generating Random Data with Reseeding

#include <ti/drivers/AESCTRDRBG.h>
#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
...
    #define ENTROPY_REQUEST_LENGTH 256
    AESCTRDRBG_Handle handle;
    TRNG_Handle trngHandle;
    CryptoKey entropyKey;
    int_fast16_t result;
    uint8_t entropyBuffer[ENTROPY_REQUEST_LENGTH];
    // Initialise the AESCTRDRBG instance here
    ...
    // Start generating random numbers
    CryptoKeyPlaintext_initBlankKey(&entropyKey, entropyBuffer, ENTROPY_REQUEST_LENGTH);
    result = AESCTRDRBG_getBytes(handle, &resultKey);
    // Check return value and reseed if needed. This should happen only after many invocations
    // of AESCTRDRBG_getBytes().
    if (result == AESCTRDRBG_STATUS_RESEED_REQUIRED) {
        TRNG_Handle trngHandle;
        CryptoKey seedKey;
        int_fast16_t reseedResult;
        uint8_t reseedBuffer[AESCTRDRBG_SEED_LENGTH_AES_128];
        CryptoKeyPlaintext_initBlankKey(&seedKey, reseedBuffer, AESCTRDRBG_SEED_LENGTH_AES_128);
        reseedResult = TRNG_generateEntropy(trngHandle, &seedKey);
        if (reseedResult != TRNG_STATUS_SUCCESS) {
            // Handle error
            while(1);
        }
        TRNG_close(trngHandle);
        reseedResult = AESCTRDRBG_reseed(handle, reseedBuffer, NULL, 0);
        if (reseedResult != AESCTRDRBG_STATUS_SUCCESS) {
            // Handle error
            while(1);
        }
    }
    else if (result != AESCTRDRBG_STATUS_SUCCESS) {
        // Handle error
        while(1);
    }

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/AESCTR.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>

Include dependency graph for AESCTRDRBG.h:

This graph shows which files directly or indirectly include this file:

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 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...

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...

Macro Definition Documentation

§ AESCTRDRBG_STATUS_RESERVED

#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 AESCTRDRBGXYZ_STATUS_ERROR0    AESCTRDRBG_STATUS_RESERVED - 0
#define AESCTRDRBGXYZ_STATUS_ERROR1    AESCTRDRBG_STATUS_RESERVED - 1
#define AESCTRDRBGXYZ_STATUS_ERROR2    AESCTRDRBG_STATUS_RESERVED - 2

§ AESCTRDRBG_STATUS_SUCCESS

#define AESCTRDRBG_STATUS_SUCCESS (0)

Successful status code.

Functions return AESCTRDRBG_STATUS_SUCCESS if the function was executed successfully.

§ AESCTRDRBG_STATUS_ERROR

#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.

§ AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE

#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.

§ AESCTRDRBG_STATUS_RESEED_REQUIRED

#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.

§ AESCTRDRBG_AES_BLOCK_SIZE_BYTES

#define AESCTRDRBG_AES_BLOCK_SIZE_BYTES 16

The AES block size in bytes.

Typedef Documentation

§ AESCTRDRBG_Handle

typedef AESCTRDRBG_Config* AESCTRDRBG_Handle

A handle that is returned from an AESCTRDRBG_open() call.

Enumeration Type Documentation

§ AESCTRDRBG_AES_KEY_LENGTH

enum AESCTRDRBG_AES_KEY_LENGTH

Length in bytes of the internal AES key used by an instance.

Enumerator
AESCTRDRBG_AES_KEY_LENGTH_128
AESCTRDRBG_AES_KEY_LENGTH_256

§ AESCTRDRBG_SEED_LENGTH

enum AESCTRDRBG_SEED_LENGTH

Length in bytes of seed used to instantiate or reseed instance.

Enumerator
AESCTRDRBG_SEED_LENGTH_AES_128
AESCTRDRBG_SEED_LENGTH_AES_256

§ AESCTRDRBG_ReturnBehavior

enum 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

Enumerator
AESCTRDRBG_RETURN_BEHAVIOR_BLOCKING	The function call will block while AESCTRDRBG operation goes on in the background. AESCTRDRBG operation results are available after the function returns.The function call will continuously poll a flag while AESCTRDRBG operation goes on in the background. AESCTRDRBG operation results are available after the function returns.
AESCTRDRBG_RETURN_BEHAVIOR_POLLING

Function Documentation

§ AESCTRDRBG_init()

void AESCTRDRBG_init ( void )

This function initializes the AESCTRDRBG driver.

Precondition: The AESCTRDRBG_Config structure must exist and be persistent before this function can be called. This function must also be called before any other AESCTRDRBG driver APIs. This function call does not modify any peripheral registers.

§ AESCTRDRBG_Params_init()

void AESCTRDRBG_Params_init ( AESCTRDRBG_Params * params )

Function to initialize the AESCTRDRBG_Params struct to its defaults.

Parameters

[out] params Pointer to AESCTRDRBG_Params structure for initialization

§ AESCTRDRBG_open()

AESCTRDRBG_Handle AESCTRDRBG_open	(	uint_least8_t	index,
		const AESCTRDRBG_Params *	params
	)

This function opens a given AESCTRDRBG instance.

Precondition: AESCTRDRBG controller has been initialized using AESCTRDRBG_init()

Parameters

[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.

Returns: An AESCTRDRBG_Handle on success or a NULL on an error or if it has been opened already.

See also: AESCTRDRBG_init(); AESCTRDRBG_close()

§ AESCTRDRBG_close()

void AESCTRDRBG_close ( AESCTRDRBG_Handle handle )

Function to close an AESCTRDRBG peripheral specified by the AESCTRDRBG_Handle.

Precondition: AESCTRDRBG_open() has to be called first.

Parameters

[in] handle An AESCTRDRBG_Handle returned from AESCTRDRBG_open()

See also: AESCTRDRBG_open()

§ AESCTRDRBG_getBytes()

int_fast16_t AESCTRDRBG_getBytes	(	AESCTRDRBG_Handle	handle,
		CryptoKey *	randomBytes
	)

Generate a requested number of random bytes.

Parameters

[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.

Return values

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.

§ AESCTRDRBG_reseed()

int_fast16_t AESCTRDRBG_reseed	(	AESCTRDRBG_Handle	handle,
		const void *	seed,
		const void *	additionalData,
		size_t	additionalDataLength
	)

Reseed an AESCTRDRBG instance.

Parameters

[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.

Return values

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_construct()

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.

Parameters

config	AESCTRDRBG_Config describing the location of the object and hwAttrs.
params	AESCTRDRBG_Params to configure the driver instance.

Returns: Returns a AESCTRDRBG_Handle on success or NULL on failure.

Precondition: The object struct config points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.

Variable Documentation

§ AESCTRDRBG_defaultParams

const AESCTRDRBG_Params AESCTRDRBG_defaultParams

Default AESCTRDRBG_Params structure.

See also: AESCTRDRBG_Params_init()

Detailed Description

Overview

Security Strength

Reseeding

Derivation Function

Usage

Synopsis

Examples

Instantiating an AESCTRDRBG Instance with TRNG

Generating Random Data with Reseeding

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ AESCTRDRBG_STATUS_RESERVED

§ AESCTRDRBG_STATUS_SUCCESS

§ AESCTRDRBG_STATUS_ERROR

§ AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE

§ AESCTRDRBG_STATUS_RESEED_REQUIRED

§ AESCTRDRBG_AES_BLOCK_SIZE_BYTES

Typedef Documentation

§ AESCTRDRBG_Handle

Enumeration Type Documentation

§ AESCTRDRBG_AES_KEY_LENGTH

§ AESCTRDRBG_SEED_LENGTH

§ AESCTRDRBG_ReturnBehavior

Function Documentation

§ AESCTRDRBG_init()

§ AESCTRDRBG_Params_init()

§ AESCTRDRBG_open()

§ AESCTRDRBG_close()

§ AESCTRDRBG_getBytes()

§ AESCTRDRBG_reseed()

§ AESCTRDRBG_construct()

Variable Documentation

§ AESCTRDRBG_defaultParams