The HMAC_DRBG pseudorandom generator. More...

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

Include dependency graph for hmac_drbg.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_hmac_drbg_context

Macros
#define	MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003

#define	MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005

#define	MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007

#define	MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009

#define	MBEDTLS_HMAC_DRBG_PR_OFF 0

#define	MBEDTLS_HMAC_DRBG_PR_ON 1

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 on the compiler command line.
#define	MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000

#define	MBEDTLS_HMAC_DRBG_MAX_INPUT 256

#define	MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024

#define	MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384

Typedefs
typedef struct mbedtls_hmac_drbg_context	mbedtls_hmac_drbg_context

Functions
void	mbedtls_hmac_drbg_init (mbedtls_hmac_drbg_context *ctx)
	HMAC_DRBG context initialization. More...

int	mbedtls_hmac_drbg_seed (mbedtls_hmac_drbg_context ctx, const mbedtls_md_info_t md_info, int(f_entropy)(void , unsigned char , size_t), void p_entropy, const unsigned char *custom, size_t len)
	HMAC_DRBG initial seeding. More...

int	mbedtls_hmac_drbg_seed_buf (mbedtls_hmac_drbg_context ctx, const mbedtls_md_info_t md_info, const unsigned char *data, size_t data_len)
	Initilisation of simpified HMAC_DRBG (never reseeds). More...

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

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

void	mbedtls_hmac_drbg_set_reseed_interval (mbedtls_hmac_drbg_context *ctx, int interval)
	Set the reseed interval. More...

int	mbedtls_hmac_drbg_update (mbedtls_hmac_drbg_context ctx, const unsigned char additional, size_t add_len)
	This function updates the state of the HMAC_DRBG context. More...

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

int	mbedtls_hmac_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 an HMAC_DRBG instance with additional data and uses it to generate random data. More...

int	mbedtls_hmac_drbg_random (void p_rng, unsigned char output, size_t out_len)
	This function uses HMAC_DRBG to generate random data. More...

void	mbedtls_hmac_drbg_free (mbedtls_hmac_drbg_context *ctx)
	This function resets HMAC_DRBG context to the state immediately after initial call of mbedtls_hmac_drbg_init(). More...

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

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

int	mbedtls_hmac_drbg_self_test (int verbose)
	The HMAC_DRBG Checkup routine. More...

Detailed Description

The HMAC_DRBG pseudorandom generator.

This module implements the HMAC_DRBG pseudorandom generator described in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators.

Definition in file hmac_drbg.h.

Macro Definition Documentation

#define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009

The entropy source failed.

Definition at line 48 of file hmac_drbg.h.

#define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007

Read/write error in file.

Definition at line 46 of file hmac_drbg.h.

#define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005

Input too large (Entropy + additional).

Definition at line 44 of file hmac_drbg.h.

#define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003

Too many random requested in single call.

Definition at line 42 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_MAX_INPUT 256

Maximum number of additional input bytes

Definition at line 63 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024

Maximum number of requested bytes per call

Definition at line 67 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384

Maximum size of (re)seed buffer

Definition at line 71 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_PR_OFF 0

No prediction resistance

Definition at line 76 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_PR_ON 1

Prediction resistance enabled

Definition at line 77 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000

Interval before reseed is performed by default

Definition at line 59 of file hmac_drbg.h.

Typedef Documentation

typedef struct mbedtls_hmac_drbg_context mbedtls_hmac_drbg_context

HMAC_DRBG context.

Function Documentation

void mbedtls_hmac_drbg_free ( mbedtls_hmac_drbg_context * ctx )

This function resets HMAC_DRBG context to the state immediately after initial call of mbedtls_hmac_drbg_init().

Parameters

ctx	The HMAC_DRBG context to free.

void mbedtls_hmac_drbg_init ( mbedtls_hmac_drbg_context * ctx )

HMAC_DRBG context initialization.

This function makes the context ready for mbedtls_hmac_drbg_seed(), mbedtls_hmac_drbg_seed_buf() or mbedtls_hmac_drbg_free().

Note: The reseed interval is MBEDTLS_HMAC_DRBG_RESEED_INTERVAL by default. Override this value by calling mbedtls_hmac_drbg_set_reseed_interval().

Parameters

ctx	HMAC_DRBG context to be initialized.

int mbedtls_hmac_drbg_random	(	void *	p_rng,
		unsigned char *	output,
		size_t	out_len
	)

This function uses HMAC_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 HMAC_DRBG context. This must be a pointer to a mbedtls_hmac_drbg_context structure.
output	The buffer to fill.
out_len	The length of the buffer in bytes. This must be at most MBEDTLS_HMAC_DRBG_MAX_REQUEST.

Returns: 0 if successful.; MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED if a call to the entropy source failed.; MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if out_len > MBEDTLS_HMAC_DRBG_MAX_REQUEST.

int mbedtls_hmac_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 an HMAC_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 HMAC_DRBG context. This must be a pointer to a mbedtls_hmac_drbg_context structure.
output	The buffer to fill.
output_len	The length of the buffer in bytes. This must be at most MBEDTLS_HMAC_DRBG_MAX_REQUEST.
additional	Additional data to update with. If this is `NULL`, there is no additional data and `add_len` should be `0`.
add_len	The length of the additional data. This must be at most MBEDTLS_HMAC_DRBG_MAX_INPUT.

Returns: 0 if successful.; MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED if a call to the entropy source failed.; MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if output_len > MBEDTLS_HMAC_DRBG_MAX_REQUEST.; MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if add_len > MBEDTLS_HMAC_DRBG_MAX_INPUT.

int mbedtls_hmac_drbg_reseed	(	mbedtls_hmac_drbg_context *	ctx,
		const unsigned char *	additional,
		size_t	len
	)

This function reseeds the HMAC_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 HMAC_DRBG context.
additional	Additional data to add to the state. If this is `NULL`, there is no additional data and `len` should be `0`.
len	The length of the additional data. This must be at most MBEDTLS_HMAC_DRBG_MAX_INPUT and also at most MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - `entropy_len` where `entropy_len` is the entropy length (see mbedtls_hmac_drbg_set_entropy_len()).

Returns: 0 if successful.; MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED if a call to the entropy function failed.

int mbedtls_hmac_drbg_seed	(	mbedtls_hmac_drbg_context *	ctx,
		const mbedtls_md_info_t *	md_info,
		int()(void , unsigned char *, size_t)	f_entropy,
		void *	p_entropy,
		const unsigned char *	custom,
		size_t	len
	)

HMAC_DRBG initial seeding.

Set the initial seed and set up the 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).

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

Note

By default, the security strength as defined by NIST is:

128 bits if md_info is SHA-1;
192 bits if md_info is SHA-224;
256 bits if md_info is SHA-256, SHA-384 or SHA-512. Note that SHA-256 is just as efficient as SHA-224. The security strength can be reduced if a smaller entropy length is set with mbedtls_hmac_drbg_set_entropy_len().

The default entropy length is the security strength (converted from bits to bytes). You can override it by calling mbedtls_hmac_drbg_set_entropy_len().

During the initial seeding, this function calls the entropy source to obtain a nonce whose length is half the entropy length.

When Mbed TLS is built with threading support, after this function returns successfully, it is safe to call mbedtls_hmac_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.

Parameters

ctx	HMAC_DRBG context to be seeded.
md_info	MD algorithm to use for HMAC_DRBG.
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 length that is 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_HMAC_DRBG_MAX_INPUT and also at most MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - `entropy_len` * 3 / 2 where `entropy_len` is the entropy length described above.

Returns: 0 if successful.; MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info is invalid.; MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough memory to allocate context data.; MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED if the call to f_entropy failed.

int mbedtls_hmac_drbg_seed_buf	(	mbedtls_hmac_drbg_context *	ctx,
		const mbedtls_md_info_t *	md_info,
		const unsigned char *	data,
		size_t	data_len
	)

Initilisation of simpified HMAC_DRBG (never reseeds).

This function is meant for use in algorithms that need a pseudorandom input such as deterministic ECDSA.

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

Parameters

ctx	HMAC_DRBG context to be initialised.
md_info	MD algorithm to use for HMAC_DRBG.
data	Concatenation of the initial entropy string and the additional data.
data_len	Length of `data` in bytes.

Returns: 0 if successful. or; MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info is invalid.; MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough memory to allocate context data.

int mbedtls_hmac_drbg_self_test ( int verbose )

The HMAC_DRBG Checkup routine.

Returns: 0 if successful.; 1 if the test failed.

void mbedtls_hmac_drbg_set_entropy_len	(	mbedtls_hmac_drbg_context *	ctx,
		size_t	len
	)

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

See the documentation of mbedtls_hmac_drbg_seed() for the default value.

Parameters

ctx	The HMAC_DRBG context.
len	The amount of entropy to grab, in bytes.

void mbedtls_hmac_drbg_set_prediction_resistance	(	mbedtls_hmac_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_hmac_drbg_random_with_add() or mbedtls_hmac_drbg_random(). Only use this if your entropy source has sufficient throughput.

Parameters

ctx	The HMAC_DRBG context.
resistance	MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF.

void mbedtls_hmac_drbg_set_reseed_interval	(	mbedtls_hmac_drbg_context *	ctx,
		int	interval
	)

Set the reseed interval.

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

The default value is MBEDTLS_HMAC_DRBG_RESEED_INTERVAL.

Parameters

ctx	The HMAC_DRBG context.
interval	The reseed interval.

int mbedtls_hmac_drbg_update	(	mbedtls_hmac_drbg_context *	ctx,
		const unsigned char *	additional,
		size_t	add_len
	)

This function updates the state of the HMAC_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 HMAC_DRBG context.
additional	The data to update the state with. If this is `NULL`, there is no additional data.
add_len	Length of `additional` in bytes. Unused if `additional` is `NULL`.

Returns: 0 on success, or an error from the underlying hash calculation.

int mbedtls_hmac_drbg_update_seed_file	(	mbedtls_hmac_drbg_context *	ctx,
		const char *	path
	)

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

Parameters

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

Returns: 0 on success.; MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.; MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.; MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if the existing seed file is too large.

int mbedtls_hmac_drbg_write_seed_file	(	mbedtls_hmac_drbg_context *	ctx,
		const char *	path
	)

This function writes a seed file.

Parameters

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

Returns: 0 on success.; MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.; MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation