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

Macros
#define	MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034
	The entropy source failed. More...

#define	MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036
	The requested random buffer length is too big. More...

#define	MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038
	The input (entropy + additional data) is too large. More...

#define	MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A
	Read or write error in file. More...

#define	MBEDTLS_CTR_DRBG_BLOCKSIZE 16
	The block size used by the cipher. More...

#define	MBEDTLS_CTR_DRBG_KEYSIZE 32
	The key size in bytes used by the cipher. More...

#define	MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
	The key size for the DRBG operation, in bits. More...

#define	MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
	The seed length, calculated as (counter + AES key). More...

#define	MBEDTLS_CTR_DRBG_PR_OFF 0
	Prediction resistance is disabled. More...

#define	MBEDTLS_CTR_DRBG_PR_ON 1
	Prediction resistance is enabled. More...

#define	MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN ( MBEDTLS_CTR_DRBG_ENTROPY_LEN + 1 ) / 2
	The default length of the nonce read from the entropy source. More...

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

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

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

#define	MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
	The interval before reseed is performed by default. More...

#define	MBEDTLS_CTR_DRBG_MAX_INPUT 256
	The maximum number of additional input Bytes. More...

#define	MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
	The maximum number of requested Bytes per call. More...

#define	MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
	The maximum size of seed or reseed buffer in bytes. More...

Detailed Description

Macro Definition Documentation

◆ MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

The entropy source failed.

Definition at line 63 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 64 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 65 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 66 of file ctr_drbg.h.

◆ MBEDTLS_CTR_DRBG_BLOCKSIZE

#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16

The block size used by the cipher.

Definition at line 68 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 83 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 86 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 87 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 120 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 126 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 131 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 136 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 141 of file ctr_drbg.h.

◆ MBEDTLS_CTR_DRBG_PR_OFF

#define MBEDTLS_CTR_DRBG_PR_OFF 0

Prediction resistance is disabled.

Definition at line 147 of file ctr_drbg.h.

◆ MBEDTLS_CTR_DRBG_PR_ON

#define MBEDTLS_CTR_DRBG_PR_ON 1

Prediction resistance is enabled.

Definition at line 149 of file ctr_drbg.h.

◆ MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN ( MBEDTLS_CTR_DRBG_ENTROPY_LEN + 1 ) / 2

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

This is half of the default entropy length because a single read from the entropy source does not provide enough material to form a nonce. See the documentation of mbedtls_ctr_drbg_seed() for more information.

Definition at line 170 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_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_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().

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.
A string obtained by calling f_entropy function for the entropy nonce length. If the entropy nonce length is 0, this function does not make a second call to f_entropy.
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.
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.

◆ 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_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_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 and at most the maximum length accepted by the entropy function that is set in the context.

◆ mbedtls_ctr_drbg_set_nonce_len()

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.

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

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

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.

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

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_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_update()

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.

Data Structures

Macros

Typedefs

Functions

SECTION: Module settings

Detailed Description

Macro Definition Documentation

◆ MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

◆ MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

◆ MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

◆ MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR

◆ MBEDTLS_CTR_DRBG_BLOCKSIZE

◆ MBEDTLS_CTR_DRBG_KEYSIZE

◆ MBEDTLS_CTR_DRBG_KEYBITS

◆ MBEDTLS_CTR_DRBG_SEEDLEN

◆ MBEDTLS_CTR_DRBG_ENTROPY_LEN

◆ MBEDTLS_CTR_DRBG_RESEED_INTERVAL

◆ MBEDTLS_CTR_DRBG_MAX_INPUT

◆ MBEDTLS_CTR_DRBG_MAX_REQUEST

◆ MBEDTLS_CTR_DRBG_MAX_SEED_INPUT

◆ MBEDTLS_CTR_DRBG_PR_OFF

◆ MBEDTLS_CTR_DRBG_PR_ON

◆ MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN

Typedef Documentation

◆ mbedtls_ctr_drbg_context

Function Documentation

◆ mbedtls_ctr_drbg_init()

◆ mbedtls_ctr_drbg_seed()

◆ mbedtls_ctr_drbg_free()

◆ mbedtls_ctr_drbg_set_prediction_resistance()

◆ mbedtls_ctr_drbg_set_entropy_len()

◆ mbedtls_ctr_drbg_set_nonce_len()

◆ mbedtls_ctr_drbg_set_reseed_interval()

◆ mbedtls_ctr_drbg_reseed()

◆ mbedtls_ctr_drbg_update_ret()

◆ mbedtls_ctr_drbg_random_with_add()

◆ mbedtls_ctr_drbg_random()

◆ mbedtls_ctr_drbg_update()