Detailed Description

AESCTRDRBG driver header.

Overview

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

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

Derivation Function

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.

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_generateKey(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;
    int_fast16_t result;
    uint8_t seedBuffer[AESCTRDRBG_SEED_LENGTH_AES_128];
    // Open a TRNG driver instance
    trngHandle = TRNG_open(0, NULL);
    if (trngHandle == NULL) {
        // Failed to open TRNG instance
        while(1);
    }
    // Generate entropy for the seed
    result = TRNG_getRandomBytes(trngHandle, seedBuffer, AESCTRDRBG_SEED_LENGTH_AES_128);
    if (result != TRNG_STATUS_SUCCESS) {
        // Failed to generate entropy
        while(1);
    }
    TRNG_close(trngHandle);
    // Instantiate the AESCTRDRBG parameters and the driver 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) {
        // Failed to open AESCTRDRBG instance
        while(1);
    }

Generating random key with Reseeding

#include <ti/drivers/AESCTRDRBG.h>
#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
...
    #define RANDOM_KEY_LENGTH_BYTES 32
    AESCTRDRBG_Handle handle;
    TRNG_Handle trngHandle;
    CryptoKey randomKey;
    int_fast16_t result;
    uint8_t randomKeyBuffer[RANDOM_KEY_LENGTH_BYTES];
    // Initialise the AESCTRDRBG params and driver instance here
    ...
    // Initialize a blank CryptoKey
    CryptoKeyPlaintext_initBlankKey(&randomKey, randomKeyBuffer, RANDOM_KEY_LENGTH_BYTES);
    // Generate key-material for the CryptoKey
    result = AESCTRDRBG_generateKey(handle, &randomKey);
    // Check return value and reseed if needed. This should happen only after many invocations
    // of AESCTRDRBG_generateKey().
    if (result == AESCTRDRBG_STATUS_RESEED_REQUIRED) {
        TRNG_Handle trngHandle;
        int_fast16_t reseedResult;
        uint8_t reseedBuffer[AESCTRDRBG_SEED_LENGTH_AES_128];
        reseedResult = TRNG_getRandomBytes(trngHandle, reseedBuffer, AESCTRDRBG_SEED_LENGTH_AES_128);
        if (reseedResult != TRNG_STATUS_SUCCESS) {
            // Failed to generate entropy
            while(1);
        }
        TRNG_close(trngHandle);
        // Reseed the DRBG instance
        reseedResult = AESCTRDRBG_reseed(handle, reseedBuffer, NULL, 0);
        if (reseedResult != AESCTRDRBG_STATUS_SUCCESS) {
            // Failed to reseed the DRBG instance
            while(1);
        }
        // If AESCTRDRBG_STATUS_RESEED_REQUIRED was returned from the previous call to
        // AESCTRDRBG_generateKey(), the random key was never generated by that call.
        // So the user must invoke that call again (after reseeding) to get a random key.
        result = AESCTRDRBG_generateKey(handle, &randomKey);
        if (result != AESCTRDRBG_STATUS_SUCCESS) {
            // Failed to generate key-material
            while(1);
        }
    }
    else if (result != AESCTRDRBG_STATUS_SUCCESS) {
        // Failed to generate key-material
        while(1);
    }

Generating random bytes output to an array

#include <ti/drivers/AESCTRDRBG.h>
#include <ti/drivers/TRNG.h>
...
    #define RANDOM_BYTES_SIZE 16
    AESCTRDRBG_Handle handle;
    TRNG_Handle trngHandle;
    int_fast16_t result;
    uint8_t randomBytesBuffer[RANDOM_BYTES_SIZE];
    // Initialise the AESCTRDRBG params and driver instance here
    ...
    // Get random bytes output to the buffer/array
    result = AESCTRDRBG_getRandomBytes(handle, &randomBytesBuffer, RANDOM_BYTES_SIZE);
    // Check and reseed if required. This should happen only after many invocations
    // of AESCTRDRBG_getRandomBytes().
    if (result == AESCTRDRBG_STATUS_RESEED_REQUIRED) {
         // Reseed the DRBG instance using AESCTRDRBG_reseed()
         // and invoke AESCTRDRBG_getRandomBytes() similar to the previous example.
    }
    else if (result != AESCTRDRBG_STATUS_SUCCESS) {
        // Failed to generate random bytes
        while(1);
    }

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

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_Params
	AESCTRDRBG Parameters. More...

Macros
#define	AESCTRDRBG_STATUS_RESERVED AES_STATUS_RESERVED

#define	AESCTRDRBG_STATUS_SUCCESS AES_STATUS_SUCCESS
	Successful status code. More...

#define	AESCTRDRBG_STATUS_ERROR AES_STATUS_ERROR
	Generic error status code. More...

#define	AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE
	An error status code returned if the hardware or software resource is currently unavailable. More...

#define	AESCTRDRBG_STATUS_RESEED_REQUIRED (AES_STATUS_DRIVER_SPECIFIC_ERROR - 0)
	The AESCTRDRBG instance must be reseeded. More...

#define	AESCTRDRBG_STATUS_UNINSTANTIATED (AES_STATUS_DRIVER_SPECIFIC_ERROR - 1)
	The AESCTRDRBG instance is uninstantiated. Close and reopen the instance. More...

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

#define	AESCTRDRBG_AES_BLOCK_SIZE_BYTES 16
	The AES block size in bytes. 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...

Macro Definition Documentation

§ AESCTRDRBG_STATUS_RESERVED

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

Successful status code.

Functions return AESCTRDRBG_STATUS_SUCCESS if the function was executed successfully.

§ AESCTRDRBG_STATUS_ERROR

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

§ AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE

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

§ AESCTRDRBG_STATUS_RESEED_REQUIRED

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

§ AESCTRDRBG_STATUS_UNINSTANTIATED

#define AESCTRDRBG_STATUS_UNINSTANTIATED (AES_STATUS_DRIVER_SPECIFIC_ERROR - 1)

The AESCTRDRBG instance is uninstantiated. Close and reopen the instance.

§ AESCTRDRBG_STATUS_UNALIGNED_IO_NOT_SUPPORTED

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

§ AESCTRDRBG_AES_BLOCK_SIZE_BYTES

#define AESCTRDRBG_AES_BLOCK_SIZE_BYTES 16

The AES block size in bytes.

Typedef Documentation

§ AESCTRDRBG_Config

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.

See also: AESCTRDRBG_init()

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

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 instance 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
	)

Generates the requested number of random bytes.

Deprecated:: This function has been replaced by a pair of new functions. See AESCTRDRBG_generateKey() and AESCTRDRBG_getRandomBytes().

Parameters

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

Return values

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.

§ AESCTRDRBG_generateKey()

int_fast16_t AESCTRDRBG_generateKey	(	AESCTRDRBG_Handle	handle,
		CryptoKey *	randomKey
	)

Populates the provided CryptoKey object's plaintext key-material with random bytes.

Note: This function replaces AESCTRDRBG_getBytes(). See AESCTRDRBG_getRandomBytes() to output random bytes to an array instead.

Parameters

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

Return values

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.

§ AESCTRDRBG_getRandomBytes()

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.

Attention: This function should not be confused with the deprecated AESCTRDRBG_getBytes(). AESCTRDRBG_getBytes() output random bytes to a CryptoKey while this new function outputs random bytes to an array.

Note: See AESCTRDRBG_generateKey() to output random bytes to a CryptoKey instead.

Parameters

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

Return values

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.

§ 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_STATUS_UNINSTANTIATED	DRBG uninstantiated. Close and reopen the instance with fresh seed.

§ 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 an 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 key with Reseeding

Generating random bytes output to an array

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_STATUS_UNINSTANTIATED

§ AESCTRDRBG_STATUS_UNALIGNED_IO_NOT_SUPPORTED

§ AESCTRDRBG_AES_BLOCK_SIZE_BYTES

Typedef Documentation

§ AESCTRDRBG_Config

§ 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_generateKey()

§ AESCTRDRBG_getRandomBytes()

§ AESCTRDRBG_reseed()

§ AESCTRDRBG_construct()

Variable Documentation

§ AESCTRDRBG_defaultParams