Detailed Description

HMAC_DRBG (NIST SP 800-90A)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file hmac_drbg.h.

#include "md.h"

Include dependency graph for hmac_drbg.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_hmac_drbg_context
	HMAC_DRBG context. More...

Macros
#define	MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003
	Too many random requested in single call. More...

#define	MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005
	Input too large (Entropy + additional). More...

#define	MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007
	Read/write error in file. More...

#define	MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009
	The entropy source failed. More...

#define	MBEDTLS_HMAC_DRBG_PR_OFF 0
	No prediction resistance. More...

#define	MBEDTLS_HMAC_DRBG_PR_ON 1
	Prediction resistance enabled. More...

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
	Interval before reseed is performed by default. More...

#define	MBEDTLS_HMAC_DRBG_MAX_INPUT 256
	Maximum number of additional input bytes. More...

#define	MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024
	Maximum number of requested bytes per call. More...

#define	MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384
	Maximum size of (re)seed buffer. More...

Functions
void	mbedtls_hmac_drbg_init (mbedtls_hmac_drbg_context *ctx)
	HMAC_DRBG context initialization Makes the context ready for mbedtls_hmac_drbg_seed(), mbedtls_hmac_drbg_seed_buf() or mbedtls_hmac_drbg_free(). 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 Seed and setup entropy source for future reseeds. 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)
	Enable / disable prediction resistance (Default: Off) More...

void	mbedtls_hmac_drbg_set_entropy_len (mbedtls_hmac_drbg_context *ctx, size_t len)
	Set the amount of entropy grabbed on each reseed (Default: given by the security strength, which depends on the hash used, see `mbedtls_hmac_drbg_init()` ) More...

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

void	mbedtls_hmac_drbg_update (mbedtls_hmac_drbg_context ctx, const unsigned char additional, size_t add_len)
	HMAC_DRBG update state. More...

int	mbedtls_hmac_drbg_reseed (mbedtls_hmac_drbg_context ctx, const unsigned char additional, size_t len)
	HMAC_DRBG reseeding (extracts data from 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)
	HMAC_DRBG generate random with additional update input. More...

int	mbedtls_hmac_drbg_random (void p_rng, unsigned char output, size_t out_len)
	HMAC_DRBG generate random. More...

void	mbedtls_hmac_drbg_free (mbedtls_hmac_drbg_context *ctx)
	Free an HMAC_DRBG context. More...

Macro Definition Documentation

#define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009

The entropy source failed.

Definition at line 38 of file hmac_drbg.h.

#define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007

Read/write error in file.

Definition at line 37 of file hmac_drbg.h.

#define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005

Input too large (Entropy + additional).

Definition at line 36 of file hmac_drbg.h.

#define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003

Too many random requested in single call.

Definition at line 35 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_MAX_INPUT 256

Maximum number of additional input bytes.

Definition at line 53 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024

Maximum number of requested bytes per call.

Definition at line 57 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384

Maximum size of (re)seed buffer.

Definition at line 61 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_PR_OFF 0

No prediction resistance.

Definition at line 66 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_PR_ON 1

Prediction resistance enabled.

Definition at line 67 of file hmac_drbg.h.

#define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000

Interval before reseed is performed by default.

Definition at line 49 of file hmac_drbg.h.

Function Documentation

void mbedtls_hmac_drbg_free ( mbedtls_hmac_drbg_context * ctx )

Free an HMAC_DRBG context.

Parameters

ctx	HMAC_DRBG context to free.

void mbedtls_hmac_drbg_init ( mbedtls_hmac_drbg_context * ctx )

HMAC_DRBG context initialization 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

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

HMAC_DRBG generate random.

Note: Automatically reseeds if reseed_counter is reached or PR is enabled.

Parameters

p_rng	HMAC_DRBG context
output	Buffer to fill
out_len	Length of the buffer

Returns: 0 if successful, or MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG

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
	)

HMAC_DRBG generate random with additional update input.

Note: Automatically reseeds if reseed_counter is reached or PR is enabled.

Parameters

p_rng	HMAC_DRBG context
output	Buffer to fill
output_len	Length of the buffer
additional	Additional data to update with (can be NULL)
add_len	Length of additional data (can be 0)

Returns: 0 if successful, or MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG.

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

HMAC_DRBG reseeding (extracts data from entropy source)

Parameters

ctx	HMAC_DRBG context
additional	Additional data to add to state (Can be NULL)
len	Length of additional data

Returns: 0 if successful, or MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_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 Seed and setup entropy source for future reseeds.

Parameters

ctx	HMAC_DRBG context to be seeded
md_info	MD algorithm to use for HMAC_DRBG
f_entropy	Entropy callback (p_entropy, buffer to fill, buffer length)
p_entropy	Entropy context
custom	Personalization data (Device specific identifiers) (Can be NULL)
len	Length of personalization data

Note: The "security strength" as defined by NIST is set to: 128 bits if md_alg is SHA-1, 192 bits if md_alg is SHA-224, 256 bits if md_alg is SHA-256 or higher. Note that SHA-256 is just as efficient as SHA-224.

Returns: 0 if successful, or MBEDTLS_ERR_MD_BAD_INPUT_DATA, or MBEDTLS_ERR_MD_ALLOC_FAILED, or MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_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).

(For use with deterministic ECDSA.)

Parameters

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

Returns: 0 if successful, or MBEDTLS_ERR_MD_BAD_INPUT_DATA, or MBEDTLS_ERR_MD_ALLOC_FAILED.

void mbedtls_hmac_drbg_set_entropy_len	(	mbedtls_hmac_drbg_context *	ctx,
		size_t	len
	)

Set the amount of entropy grabbed on each reseed (Default: given by the security strength, which depends on the hash used, see mbedtls_hmac_drbg_init() )

Parameters

ctx	HMAC_DRBG context
len	Amount of entropy to grab, in bytes

void mbedtls_hmac_drbg_set_prediction_resistance	(	mbedtls_hmac_drbg_context *	ctx,
		int	resistance
	)

Enable / disable prediction resistance (Default: Off)

Note: If enabled, entropy is used for ctx->entropy_len before each call! Only use this if you have ample supply of good entropy!

Parameters

ctx	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 (Default: MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)

Parameters

ctx	HMAC_DRBG context
interval	Reseed interval

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

HMAC_DRBG update state.

Parameters

ctx	HMAC_DRBG context
additional	Additional data to update state with, or NULL
add_len	Length of additional data, or 0

Note: Additional data is optional, pass NULL and 0 as second third argument if no additional data is being used.

Detailed Description

Data Structures

Macros

Functions

Macro Definition Documentation

Function Documentation