This file contains CTR_DRBG definitions and functions. More...

#include "mbedtls/config.h"
#include "mbedtls/aes.h"

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 used by the cipher (compile-time choice: 256 bits). 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_DEPRECATED

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 clears CTR_CRBG context data. 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...

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

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

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)

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
	Amount of entropy used per seed by default: 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. More...

Detailed Description

This file contains CTR_DRBG definitions and functions.

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 as the underlying block cipher.

Warning: Using 128-bit keys for CTR_DRBG limits the security of generated keys and operations that use random values generated to 128-bit security.

Macro Definition Documentation

#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16

The block size used by the cipher.

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32

Amount of entropy used per seed by default:

48 with SHA-512.
32 with SHA-256.

#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

The key size for the DRBG operation, in bits.

#define MBEDTLS_CTR_DRBG_KEYSIZE 32

The key size used by the cipher (compile-time choice: 256 bits).

#define MBEDTLS_CTR_DRBG_MAX_INPUT 256

The maximum number of additional input Bytes.

#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024

The maximum number of requested Bytes per call.

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

The maximum size of seed or reseed buffer.

#define MBEDTLS_CTR_DRBG_PR_OFF 0

Prediction resistance is disabled.

#define MBEDTLS_CTR_DRBG_PR_ON 1

Prediction resistance is enabled.

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000

The interval before reseed is performed by default.

#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

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

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

The entropy source failed.

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A

Read or write error in file.

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038

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

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036

The requested random buffer length is too big.

Function Documentation

void mbedtls_ctr_drbg_free ( mbedtls_ctr_drbg_context * ctx )

This function clears CTR_CRBG context data.

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

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.

Note: The function automatically reseeds if the reseed counter is exceeded.

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.

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.

Note: The function automatically reseeds if the reseed counter is exceeded.

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.
additional	Additional data to update. Can be NULL.
add_len	The length of the additional data.

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.

Parameters

ctx	The CTR_DRBG context.
additional	Additional data to add to the state. Can be NULL.
len	The length of the additional data.

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.

Note: Personalization data can be provided in addition to the more generic entropy source, to make this instantiation as unique as possible.

Parameters

ctx	The CTR_DRBG context to seed.
f_entropy	The entropy callback, taking as arguments the `p_entropy` context, the buffer to fill, and the length of the buffer.
p_entropy	The entropy context.
custom	Personalization data, that is device-specific identifiers. Can be NULL.
len	The length of the personalization data.

Returns: 0 on success.; MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED 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.

Parameters

ctx	The CTR_DRBG context.
len	The amount of entropy to grab.

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(). 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 default value is MBEDTLS_CTR_DRBG_RESEED_INTERVAL.

Parameters

ctx	The CTR_DRBG context.
interval	The reseed interval.

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.

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

Data Structures

Macros

Functions

SECTION: Module settings

Detailed Description

Macro Definition Documentation

Function Documentation