This file contains definitions and functions for the CTR_DRBG pseudorandom generator. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/aes.h"
#include "mbedtls/threading.h"

Include dependency graph for ctr_drbg.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_ctr_drbg_context
	The CTR_DRBG context structure. More...

Macros
#define	MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

#define	MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036

#define	MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038

#define	MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A

#define	MBEDTLS_CTR_DRBG_BLOCKSIZE 16

#define	MBEDTLS_CTR_DRBG_KEYSIZE 16

#define	MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

#define	MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

#define	MBEDTLS_CTR_DRBG_PR_OFF 0

#define	MBEDTLS_CTR_DRBG_PR_ON 1

#define	MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0

SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in mbedtls_config.h or define them using the compiler command line.
#define	MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
	The amount of entropy used per seed by default, in bytes. More...

#define	MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000

#define	MBEDTLS_CTR_DRBG_MAX_INPUT 256

#define	MBEDTLS_CTR_DRBG_MAX_REQUEST 1024

#define	MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

Typedefs
typedef struct mbedtls_ctr_drbg_context	mbedtls_ctr_drbg_context
	The CTR_DRBG context structure. More...

Functions
void	mbedtls_ctr_drbg_init (mbedtls_ctr_drbg_context *ctx)
	This function initializes the CTR_DRBG context, and prepares it for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free(). More...

int	mbedtls_ctr_drbg_seed (mbedtls_ctr_drbg_context ctx, int(f_entropy)(void , unsigned char , size_t), void p_entropy, const unsigned char custom, size_t len)
	This function seeds and sets up the CTR_DRBG entropy source for future reseeds. More...

void	mbedtls_ctr_drbg_free (mbedtls_ctr_drbg_context *ctx)
	This function resets CTR_DRBG context to the state immediately after initial call of mbedtls_ctr_drbg_init(). More...

void	mbedtls_ctr_drbg_set_prediction_resistance (mbedtls_ctr_drbg_context *ctx, int resistance)
	This function turns prediction resistance on or off. The default value is off. More...

void	mbedtls_ctr_drbg_set_entropy_len (mbedtls_ctr_drbg_context *ctx, size_t len)
	This function sets the amount of entropy grabbed on each seed or reseed. More...

int	mbedtls_ctr_drbg_set_nonce_len (mbedtls_ctr_drbg_context *ctx, size_t len)
	This function sets the amount of entropy grabbed as a nonce for the initial seeding. More...

void	mbedtls_ctr_drbg_set_reseed_interval (mbedtls_ctr_drbg_context *ctx, int interval)
	This function sets the reseed interval. More...

int	mbedtls_ctr_drbg_reseed (mbedtls_ctr_drbg_context ctx, const unsigned char additional, size_t len)
	This function reseeds the CTR_DRBG context, that is extracts data from the entropy source. More...

int	mbedtls_ctr_drbg_update (mbedtls_ctr_drbg_context ctx, const unsigned char additional, size_t add_len)
	This function updates the state of the CTR_DRBG context. More...

int	mbedtls_ctr_drbg_random_with_add (void p_rng, unsigned char output, size_t output_len, const unsigned char *additional, size_t add_len)
	This function updates a CTR_DRBG instance with additional data and uses it to generate random data. More...

int	mbedtls_ctr_drbg_random (void p_rng, unsigned char output, size_t output_len)
	This function uses CTR_DRBG to generate random data. More...

int	mbedtls_ctr_drbg_write_seed_file (mbedtls_ctr_drbg_context ctx, const char path)
	This function writes a seed file. More...

int	mbedtls_ctr_drbg_update_seed_file (mbedtls_ctr_drbg_context ctx, const char path)
	This function reads and updates a seed file. The seed is added to this instance. More...

int	mbedtls_ctr_drbg_self_test (int verbose)
	The CTR_DRBG checkup routine. More...

Detailed Description

This file contains definitions and functions for the CTR_DRBG pseudorandom generator.

CTR_DRBG is a standardized way of building a PRNG from a block-cipher in counter mode operation, as defined in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators.

The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128 (if MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time) as the underlying block cipher, with a derivation function.

The security strength as defined in NIST SP 800-90A is 128 bits when AES-128 is used (MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled) and 256 bits otherwise, provided that MBEDTLS_CTR_DRBG_ENTROPY_LEN is kept at its default value (and not overridden in mbedtls_config.h) and that the DRBG instance is set up with default parameters. See the documentation of mbedtls_ctr_drbg_seed() for more information.

Definition in file ctr_drbg.h.

Macro Definition Documentation

#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16

The block size used by the cipher.

Definition at line 62 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32

The amount of entropy used per seed by default, in bytes.

This is 32 bytes because the entropy module uses SHA-256 (the SHA512 module is disabled or MBEDTLS_ENTROPY_FORCE_SHA256 is enabled).

Definition at line 114 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0

The default length of the nonce read from the entropy source.

This is 0 because a single read from the entropy source is sufficient to include a nonce. See the documentation of mbedtls_ctr_drbg_seed() for more information.

Definition at line 156 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

The key size for the DRBG operation, in bits.

Definition at line 80 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_KEYSIZE 16

The key size in bytes used by the cipher.

Compile-time choice: 16 bytes (128 bits) because MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled.

Definition at line 65 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_INPUT 256

The maximum number of additional input Bytes.

Definition at line 124 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024

The maximum number of requested Bytes per call.

Definition at line 129 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

The maximum size of seed or reseed buffer in bytes.

Definition at line 134 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_PR_OFF 0

Prediction resistance is disabled.

Definition at line 140 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_PR_ON 1

Prediction resistance is enabled.

Definition at line 142 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000

The interval before reseed is performed by default.

Definition at line 119 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

The seed length, calculated as (counter + AES key).

Definition at line 81 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

The entropy source failed.

Definition at line 54 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A

Read or write error in file.

Definition at line 60 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038

The input (entropy + additional data) is too large.

Definition at line 58 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036

The requested random buffer length is too big.

Definition at line 56 of file ctr_drbg.h.

Typedef Documentation

typedef struct mbedtls_ctr_drbg_context mbedtls_ctr_drbg_context

The CTR_DRBG context structure.

Function Documentation

void mbedtls_ctr_drbg_free ( mbedtls_ctr_drbg_context * ctx )

This function resets CTR_DRBG context to the state immediately after initial call of mbedtls_ctr_drbg_init().

Parameters

ctx	The CTR_DRBG context to clear.

void mbedtls_ctr_drbg_init ( mbedtls_ctr_drbg_context * ctx )

This function initializes the CTR_DRBG context, and prepares it for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free().

Note: The reseed interval is MBEDTLS_CTR_DRBG_RESEED_INTERVAL by default. You can override it by calling mbedtls_ctr_drbg_set_reseed_interval().

Parameters

ctx	The CTR_DRBG context to initialize.

int mbedtls_ctr_drbg_random	(	void *	p_rng,
		unsigned char *	output,
		size_t	output_len
	)

This function uses CTR_DRBG to generate random data.

This function automatically reseeds if the reseed counter is exceeded or prediction resistance is enabled.

Note: When Mbed TLS is built with threading support, it is safe to call mbedtls_ctr_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.

Parameters

p_rng	The CTR_DRBG context. This must be a pointer to a mbedtls_ctr_drbg_context structure.
output	The buffer to fill.
output_len	The length of the buffer in bytes.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.

int mbedtls_ctr_drbg_random_with_add	(	void *	p_rng,
		unsigned char *	output,
		size_t	output_len,
		const unsigned char *	additional,
		size_t	add_len
	)

This function updates a CTR_DRBG instance with additional data and uses it to generate random data.

This function automatically reseeds if the reseed counter is exceeded or prediction resistance is enabled.

Note: This function is not thread-safe. It is not safe to call this function if another thread might be concurrently obtaining random numbers from the same context or updating or reseeding the same context.

Parameters

p_rng	The CTR_DRBG context. This must be a pointer to a mbedtls_ctr_drbg_context structure.
output	The buffer to fill.
output_len	The length of the buffer in bytes.
additional	Additional data to update. Can be `NULL`, in which case the additional data is empty regardless of the value of `add_len`.
add_len	The length of the additional data if `additional` is not `NULL`. This must be less than MBEDTLS_CTR_DRBG_MAX_INPUT and less than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - `entropy_len` where `entropy_len` is the entropy length configured for the context.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.

int mbedtls_ctr_drbg_reseed	(	mbedtls_ctr_drbg_context *	ctx,
		const unsigned char *	additional,
		size_t	len
	)

This function reseeds the CTR_DRBG context, that is extracts data from the entropy source.

Note: This function is not thread-safe. It is not safe to call this function if another thread might be concurrently obtaining random numbers from the same context or updating or reseeding the same context.

Parameters

ctx	The CTR_DRBG context.
additional	Additional data to add to the state. Can be `NULL`.
len	The length of the additional data. This must be less than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - `entropy_len` where `entropy_len` is the entropy length configured for the context.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.

int mbedtls_ctr_drbg_seed	(	mbedtls_ctr_drbg_context *	ctx,
		int()(void , unsigned char *, size_t)	f_entropy,
		void *	p_entropy,
		const unsigned char *	custom,
		size_t	len
	)

This function seeds and sets up the CTR_DRBG entropy source for future reseeds.

A typical choice for the f_entropy and p_entropy parameters is to use the entropy module:

f_entropy is mbedtls_entropy_func();
p_entropy is an instance of mbedtls_entropy_context initialized with mbedtls_entropy_init() (which registers the platform's default entropy sources).

The entropy length is MBEDTLS_CTR_DRBG_ENTROPY_LEN by default. You can override it by calling mbedtls_ctr_drbg_set_entropy_len().

The entropy nonce length is:

0 if the entropy length is at least 3/2 times the entropy length, which guarantees that the security strength is the maximum permitted by the key size and entropy length according to NIST SP 800-90A §10.2.1;
Half the entropy length otherwise. You can override it by calling mbedtls_ctr_drbg_set_nonce_len(). With the default entropy length, the entropy nonce length is MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN.

You can provide a nonce and personalization string in addition to the entropy source, to make this instantiation as unique as possible. See SP 800-90A §8.6.7 for more details about nonces.

The seed_material value passed to the derivation function in the CTR_DRBG Instantiate Process described in NIST SP 800-90A §10.2.1.3.2 is the concatenation of the following strings:

A string obtained by calling f_entropy function for the entropy length.
If mbedtls_ctr_drbg_set_nonce_len() has been called, a string obtained by calling f_entropy function for the specified length.
Note
When Mbed TLS is built with threading support, after this function returns successfully, it is safe to call mbedtls_ctr_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.
The custom string.

Note

To achieve the nominal security strength permitted by CTR_DRBG, the entropy length must be:

at least 16 bytes for a 128-bit strength (maximum achievable strength when using AES-128);
at least 32 bytes for a 256-bit strength (maximum achievable strength when using AES-256).

In addition, if you do not pass a nonce in custom, the sum of the entropy length and the entropy nonce length must be:

at least 24 bytes for a 128-bit strength (maximum achievable strength when using AES-128);
at least 48 bytes for a 256-bit strength (maximum achievable strength when using AES-256).

Parameters

ctx	The CTR_DRBG context to seed. It must have been initialized with mbedtls_ctr_drbg_init(). After a successful call to mbedtls_ctr_drbg_seed(), you may not call mbedtls_ctr_drbg_seed() again on the same context unless you call mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init() again first. After a failed call to mbedtls_ctr_drbg_seed(), you must call mbedtls_ctr_drbg_free().
f_entropy	The entropy callback, taking as arguments the `p_entropy` context, the buffer to fill, and the length of the buffer. `f_entropy` is always called with a buffer size less than or equal to the entropy length.
p_entropy	The entropy context to pass to `f_entropy`.
custom	The personalization string. This can be `NULL`, in which case the personalization string is empty regardless of the value of `len`.
len	The length of the personalization string. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT MBEDTLS_CTR_DRBG_ENTROPY_LEN.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.

int mbedtls_ctr_drbg_self_test ( int verbose )

The CTR_DRBG checkup routine.

Returns: 0 on success.; 1 on failure.

void mbedtls_ctr_drbg_set_entropy_len	(	mbedtls_ctr_drbg_context *	ctx,
		size_t	len
	)

This function sets the amount of entropy grabbed on each seed or reseed.

The default value is MBEDTLS_CTR_DRBG_ENTROPY_LEN.

Note

The security strength of CTR_DRBG is bounded by the entropy length. Thus:

When using AES-256 (MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled, which is the default), len must be at least 32 (in bytes) to achieve a 256-bit strength.
When using AES-128 (MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled) len must be at least 16 (in bytes) to achieve a 128-bit strength.

Parameters

ctx	The CTR_DRBG context.
len	The amount of entropy to grab, in bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT and at most the maximum length accepted by the entropy function that is set in the context.

int mbedtls_ctr_drbg_set_nonce_len	(	mbedtls_ctr_drbg_context *	ctx,
		size_t	len
	)

This function sets the amount of entropy grabbed as a nonce for the initial seeding.

Call this function before calling mbedtls_ctr_drbg_seed() to read a nonce from the entropy source during the initial seeding.

Parameters

ctx	The CTR_DRBG context.
len	The amount of entropy to grab for the nonce, in bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT and at most the maximum length accepted by the entropy function that is set in the context.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if len is more than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED if the initial seeding has already taken place.

void mbedtls_ctr_drbg_set_prediction_resistance	(	mbedtls_ctr_drbg_context *	ctx,
		int	resistance
	)

This function turns prediction resistance on or off. The default value is off.

Note: If enabled, entropy is gathered at the beginning of every call to mbedtls_ctr_drbg_random_with_add() or mbedtls_ctr_drbg_random(). Only use this if your entropy source has sufficient throughput.

Parameters

ctx	The CTR_DRBG context.
resistance	MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF.

void mbedtls_ctr_drbg_set_reseed_interval	(	mbedtls_ctr_drbg_context *	ctx,
		int	interval
	)

This function sets the reseed interval.

The reseed interval is the number of calls to mbedtls_ctr_drbg_random() or mbedtls_ctr_drbg_random_with_add() after which the entropy function is called again.

The default value is MBEDTLS_CTR_DRBG_RESEED_INTERVAL.

Parameters

ctx	The CTR_DRBG context.
interval	The reseed interval.

int mbedtls_ctr_drbg_update	(	mbedtls_ctr_drbg_context *	ctx,
		const unsigned char *	additional,
		size_t	add_len
	)

This function updates the state of the CTR_DRBG context.

Note: This function is not thread-safe. It is not safe to call this function if another thread might be concurrently obtaining random numbers from the same context or updating or reseeding the same context.

Parameters

ctx	The CTR_DRBG context.
additional	The data to update the state with. This must not be `NULL` unless `add_len` is `0`.
add_len	Length of `additional` in bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if add_len is more than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.; An error from the underlying AES cipher on failure.

int mbedtls_ctr_drbg_update_seed_file	(	mbedtls_ctr_drbg_context *	ctx,
		const char *	path
	)

This function reads and updates a seed file. The seed is added to this instance.

Parameters

ctx	The CTR_DRBG context.
path	The name of the file.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.; MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing seed file is too large.

int mbedtls_ctr_drbg_write_seed_file	(	mbedtls_ctr_drbg_context *	ctx,
		const char *	path
	)

This function writes a seed file.

Parameters

ctx	The CTR_DRBG context.
path	The name of the file.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation