The HMAC_DRBG pseudorandom generator. More...

Data Structures
struct	mbedtls_hmac_drbg_context
	HMAC_DRBG context. More...
Typedefs
typedef struct mbedtls_hmac_drbg_context	mbedtls_hmac_drbg_context
	HMAC_DRBG context.
Functions
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.
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 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)
	Free an HMAC_DRBG context.
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.
int	mbedtls_hmac_drbg_write_seed_file (mbedtls_hmac_drbg_context ctx, const char path)
	This function writes a seed file.
int	mbedtls_hmac_drbg_update_seed_file (mbedtls_hmac_drbg_context ctx, const char path)
	This function reads and updates a seed file.
int	mbedtls_hmac_drbg_self_test (int verbose)
	The HMAC_DRBG Checkup routine.

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.

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 )

Free an HMAC_DRBG context.

Parameters:

ctx	The HMAC_DRBG context to free.

Definition at line 419 of file hmac_drbg.c.

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

Parameters:

ctx	HMAC_DRBG context to be initialized.

Definition at line 57 of file hmac_drbg.c.

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.

Definition at line 396 of file hmac_drbg.c.

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.

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.

Definition at line 325 of file hmac_drbg.c.

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.

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.

Definition at line 235 of file hmac_drbg.c.

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

The entropy length for the initial seeding is the security strength (converted from bits to bytes). You can set a different entropy length for subsequent seeding by calling mbedtls_hmac_drbg_set_entropy_len() after this function.

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.

Definition at line 247 of file hmac_drbg.c.

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.

Definition at line 126 of file hmac_drbg.c.

int mbedtls_hmac_drbg_self_test ( int verbose )

The HMAC_DRBG Checkup routine.

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

Definition at line 562 of file hmac_drbg.c.

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

The default value is set by mbedtls_hmac_drbg_seed().

Note:: mbedtls_hmac_drbg_seed() always sets the entropy length to the default value based on the chosen MD algorithm, so this function only has an effect if it is called after mbedtls_hmac_drbg_seed().

Parameters:

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

Definition at line 308 of file hmac_drbg.c.

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.

Definition at line 299 of file hmac_drbg.c.

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.

Definition at line 316 of file hmac_drbg.c.

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.

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

Definition at line 115 of file hmac_drbg.c.

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.

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.

Definition at line 69 of file hmac_drbg.c.

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.

Definition at line 459 of file hmac_drbg.c.

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.

Definition at line 432 of file hmac_drbg.c.

Type:	Library
Created:	17 Dec 2019
Imports:	79
Forks:	0
Commits:	2
Dependents:	2
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

hmac_drbg.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

hmac_drbg.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning