ctr_drbg.h File Reference

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

#include "config.h"
#include "aes.h"

Include dependency graph for ctr_drbg.h:

Go to the source code of this file.

Classes
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   32
#define	MBEDTLS_CTR_DRBG_KEYBITS   ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
#define	MBEDTLS_CTR_DRBG_SEEDLEN   ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in 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.
#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
#define	MBEDTLS_CTR_DRBG_PR_OFF   0
#define	MBEDTLS_CTR_DRBG_PR_ON   1
#define	MBEDTLS_DEPRECATED
typedef struct mbedtls_ctr_drbg_context	mbedtls_ctr_drbg_context
	The CTR_DRBG context structure.
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().
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.
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().
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.
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.
void	mbedtls_ctr_drbg_set_reseed_interval (mbedtls_ctr_drbg_context *ctx, int interval)
	This function sets the reseed interval.
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.
int	mbedtls_ctr_drbg_update_ret (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t add_len)
	This function updates the state of the CTR_DRBG context.
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.
int	mbedtls_ctr_drbg_random (void *p_rng, unsigned char *output, size_t output_len)
	This function uses CTR_DRBG to generate random data.
MBEDTLS_DEPRECATED void	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.
int	mbedtls_ctr_drbg_seed_entropy_len (mbedtls_ctr_drbg_context *, int(*)(void *, unsigned char *, size_t), void *, const unsigned char *, size_t, size_t)

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 initial seeding grabs MBEDTLS_CTR_DRBG_ENTROPY_LEN bytes of entropy. See the documentation of mbedtls_ctr_drbg_seed() for more details.

Based on NIST SP 800-90A §10.2.1 table 3 and NIST SP 800-57 part 1 table 2, here are the security strengths achieved in typical configuration:

• 256 bits under the default configuration of the library, with AES-256 and with MBEDTLS_CTR_DRBG_ENTROPY_LEN set to 48 or more.
• 256 bits if AES-256 is used, MBEDTLS_CTR_DRBG_ENTROPY_LEN is set to 32 or more, and the DRBG is initialized with an explicit nonce in the custom parameter to mbedtls_ctr_drbg_seed().
• 128 bits if AES-256 is used but MBEDTLS_CTR_DRBG_ENTROPY_LEN is between 24 and 47 and the DRBG is not initialized with an explicit nonce (see mbedtls_ctr_drbg_seed()).
• 128 bits if AES-128 is used (MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled) and MBEDTLS_CTR_DRBG_ENTROPY_LEN is set to 24 or more (which is always the case unless it is explicitly set to a different value in config.h).

Note that the value of MBEDTLS_CTR_DRBG_ENTROPY_LEN defaults to:

• 48 if the module MBEDTLS_SHA512_C is enabled and the symbol MBEDTLS_ENTROPY_FORCE_SHA256 is disabled at compile time. This is the default configuration of the library.
• 32 if the module MBEDTLS_SHA512_C is disabled at compile time.
• 32 if MBEDTLS_ENTROPY_FORCE_SHA256 is enabled at compile time.

Definition in file ctr_drbg.h.

Macro Definition Documentation

MBEDTLS_CTR_DRBG_BLOCKSIZE

#define MBEDTLS_CTR_DRBG_BLOCKSIZE   16

The block size used by the cipher.

Definition at line 104 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_ENTROPY_LEN

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

Warning

To achieve a 256-bit security strength, you must pass a nonce to mbedtls_ctr_drbg_seed().

Definition at line 156 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_KEYBITS

#define MBEDTLS_CTR_DRBG_KEYBITS   ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

The key size for the DRBG operation, in bits.

Definition at line 122 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_KEYSIZE

#define MBEDTLS_CTR_DRBG_KEYSIZE   32

The key size in bytes used by the cipher.

Compile-time choice: 32 bytes (256 bits) because MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.

Definition at line 119 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_MAX_INPUT

#define MBEDTLS_CTR_DRBG_MAX_INPUT   256

The maximum number of additional input Bytes.

Definition at line 167 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_MAX_REQUEST

#define MBEDTLS_CTR_DRBG_MAX_REQUEST   1024

The maximum number of requested Bytes per call.

Definition at line 172 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_MAX_SEED_INPUT

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT   384

The maximum size of seed or reseed buffer in bytes.

Definition at line 177 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_PR_OFF

#define MBEDTLS_CTR_DRBG_PR_OFF   0

Prediction resistance is disabled.

Definition at line 183 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_PR_ON

#define MBEDTLS_CTR_DRBG_PR_ON   1

Prediction resistance is enabled.

Definition at line 185 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_RESEED_INTERVAL

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL   10000

The interval before reseed is performed by default.

Definition at line 162 of file ctr_drbg.h.

MBEDTLS_CTR_DRBG_SEEDLEN

#define MBEDTLS_CTR_DRBG_SEEDLEN   ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

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

Definition at line 123 of file ctr_drbg.h.

MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

Definition at line 508 of file ctr_drbg.h.

MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED   -0x0034

The entropy source failed.

Definition at line 99 of file ctr_drbg.h.

MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR   -0x003A

Read or write error in file.

Definition at line 102 of file ctr_drbg.h.

MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG   -0x0038

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

Definition at line 101 of file ctr_drbg.h.

MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG   -0x0036

The requested random buffer length is too big.

Definition at line 100 of file ctr_drbg.h.

Typedef Documentation

mbedtls_ctr_drbg_context

typedef struct mbedtls_ctr_drbg_context mbedtls_ctr_drbg_context

The CTR_DRBG context structure.

Function Documentation

mbedtls_ctr_drbg_free()

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.

mbedtls_ctr_drbg_init()

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.

mbedtls_ctr_drbg_random()

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.

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.

mbedtls_ctr_drbg_random_with_add()

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.

mbedtls_ctr_drbg_reseed()

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.

mbedtls_ctr_drbg_seed()

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

You can provide a personalization string in addition to the entropy source, to make this instantiation as unique as possible.

Note

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 string obtained from calling f_entropy and the custom string. The origin of the nonce depends on the value of the entropy length relative to the security strength.

• If the entropy length is at least 1.5 times the security strength then the nonce is taken from the string obtained with f_entropy.
• If the entropy length is less than the security strength, then the nonce is taken from custom. In this case, for compliance with SP 800-90A, you must pass a unique value of custom at each invocation. See SP 800-90A §8.6.7 for more details.

Warning

When MBEDTLS_CTR_DRBG_ENTROPY_LEN is less than MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2, to achieve the maximum security strength permitted by CTR_DRBG, you must pass a value of custom that is a nonce: this value must never be repeated in subsequent runs of the same application or on a different device.

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

mbedtls_ctr_drbg_seed_entropy_len()

int mbedtls_ctr_drbg_seed_entropy_len	(	mbedtls_ctr_drbg_context *	,
		int(*)(void *, unsigned char *, size_t)	,
		void *	,
		const unsigned char *	,
		size_t	,
		size_t
	)

mbedtls_ctr_drbg_set_entropy_len()

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.

mbedtls_ctr_drbg_set_prediction_resistance()

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.

mbedtls_ctr_drbg_set_reseed_interval()

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.

mbedtls_ctr_drbg_update()

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

Deprecated:

Superseded by mbedtls_ctr_drbg_update_ret() in 2.16.0.

Note

If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used. The remaining Bytes are silently discarded.

Parameters

ctx	The CTR_DRBG context.
additional	The data to update the state with.
add_len	Length of additional data.

mbedtls_ctr_drbg_update_ret()

int mbedtls_ctr_drbg_update_ret	(	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.