ctr_drbg.h File Reference

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

#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 )
#define	MBEDTLS_CTR_DRBG_PR_OFF   0
#define	MBEDTLS_CTR_DRBG_PR_ON   1
#define	MBEDTLS_DEPRECATED
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
#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 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. 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. The default value is MBEDTLS_CTR_DRBG_ENTROPY_LEN. More...
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. 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_self_test (int verbose)
	The CTR_DRBG checkup routine. 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)

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

MBEDTLS_CTR_DRBG_BLOCKSIZE

#define MBEDTLS_CTR_DRBG_BLOCKSIZE   16

The block size used by the cipher.

MBEDTLS_CTR_DRBG_ENTROPY_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN   32

Amount of entropy used per seed by default:

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

MBEDTLS_CTR_DRBG_KEYBITS

#define MBEDTLS_CTR_DRBG_KEYBITS   ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

The key size for the DRBG operation, in bits.

MBEDTLS_CTR_DRBG_KEYSIZE

#define MBEDTLS_CTR_DRBG_KEYSIZE   32

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

MBEDTLS_CTR_DRBG_MAX_INPUT

#define MBEDTLS_CTR_DRBG_MAX_INPUT   256

The maximum number of additional input Bytes.

MBEDTLS_CTR_DRBG_MAX_REQUEST

#define MBEDTLS_CTR_DRBG_MAX_REQUEST   1024

The maximum number of requested Bytes per call.

MBEDTLS_CTR_DRBG_MAX_SEED_INPUT

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT   384

The maximum size of seed or reseed buffer.

MBEDTLS_CTR_DRBG_PR_OFF

#define MBEDTLS_CTR_DRBG_PR_OFF   0

Prediction resistance is disabled.

MBEDTLS_CTR_DRBG_PR_ON

#define MBEDTLS_CTR_DRBG_PR_ON   1

Prediction resistance is enabled.

MBEDTLS_CTR_DRBG_RESEED_INTERVAL

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL   10000

The interval before reseed is performed by default.

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

MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED   -0x0034

The entropy source failed.

MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR   -0x003A

Read or write error in file.

MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG   -0x0038

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

MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG   -0x0036

The requested random buffer length is too big.

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

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

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.

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.

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.

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.

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.

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.

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.

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

int mbedtls_ctr_drbg_self_test

(

int

verbose

)

The CTR_DRBG checkup routine.

Returns

0 on success.

1 on failure.

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.

Parameters

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

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

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.