hmac_drbg.h File Reference

The HMAC_DRBG pseudorandom generator. More...

#include "config.h"
#include "md.h"

Include dependency graph for hmac_drbg.h:

Go to the source code of this file.

Classes
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

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 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
#define	MBEDTLS_HMAC_DRBG_PR_OFF   0
#define	MBEDTLS_HMAC_DRBG_PR_ON   1
#define	MBEDTLS_DEPRECATED
typedef struct mbedtls_hmac_drbg_context	mbedtls_hmac_drbg_context
void	mbedtls_hmac_drbg_init (mbedtls_hmac_drbg_context *ctx)
	HMAC_DRBG context initialization.
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.
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).
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.
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.
void	mbedtls_hmac_drbg_set_reseed_interval (mbedtls_hmac_drbg_context *ctx, int interval)
	Set the reseed interval.
int	mbedtls_hmac_drbg_update_ret (mbedtls_hmac_drbg_context *ctx, const unsigned char *additional, size_t add_len)
	This function updates the state of the HMAC_DRBG context.
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.
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.
int	mbedtls_hmac_drbg_random (void *p_rng, unsigned char *output, size_t out_len)
	This function uses HMAC_DRBG to generate random data.
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().
MBEDTLS_DEPRECATED void	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.

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

MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

Definition at line 431 of file hmac_drbg.h.

MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED   -0x0009

The entropy source failed.

Definition at line 74 of file hmac_drbg.h.

MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR   -0x0007

Read/write error in file.

Definition at line 73 of file hmac_drbg.h.

MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG   -0x0005

Input too large (Entropy + additional).

Definition at line 72 of file hmac_drbg.h.

MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG   -0x0003

Too many random requested in single call.

Definition at line 71 of file hmac_drbg.h.

MBEDTLS_HMAC_DRBG_MAX_INPUT

#define MBEDTLS_HMAC_DRBG_MAX_INPUT   256

Maximum number of additional input bytes

Definition at line 89 of file hmac_drbg.h.

MBEDTLS_HMAC_DRBG_MAX_REQUEST

#define MBEDTLS_HMAC_DRBG_MAX_REQUEST   1024

Maximum number of requested bytes per call

Definition at line 93 of file hmac_drbg.h.

MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT

#define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT   384

Maximum size of (re)seed buffer

Definition at line 97 of file hmac_drbg.h.

MBEDTLS_HMAC_DRBG_PR_OFF

#define MBEDTLS_HMAC_DRBG_PR_OFF   0

No prediction resistance

Definition at line 102 of file hmac_drbg.h.

MBEDTLS_HMAC_DRBG_PR_ON

#define MBEDTLS_HMAC_DRBG_PR_ON   1

Prediction resistance enabled

Definition at line 103 of file hmac_drbg.h.

MBEDTLS_HMAC_DRBG_RESEED_INTERVAL

#define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL   10000

Interval before reseed is performed by default

Definition at line 85 of file hmac_drbg.h.

Typedef Documentation

mbedtls_hmac_drbg_context

typedef struct mbedtls_hmac_drbg_context mbedtls_hmac_drbg_context

HMAC_DRBG context.

Function Documentation

mbedtls_hmac_drbg_free()

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.

mbedtls_hmac_drbg_init()

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.

mbedtls_hmac_drbg_random()

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.

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.

mbedtls_hmac_drbg_random_with_add()

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.

mbedtls_hmac_drbg_reseed()

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.

mbedtls_hmac_drbg_seed()

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.

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.

mbedtls_hmac_drbg_seed_buf()

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.

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.

mbedtls_hmac_drbg_set_entropy_len()

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.

mbedtls_hmac_drbg_set_prediction_resistance()

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.

mbedtls_hmac_drbg_set_reseed_interval()

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.

mbedtls_hmac_drbg_update()

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

Deprecated:

Superseded by mbedtls_hmac_drbg_update_ret() in 2.16.0.

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.

mbedtls_hmac_drbg_update_ret()

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