hmac_drbg.h File Reference

HMAC_DRBG (NIST SP 800-90A) More...

#include "md.h"

Include dependency graph for hmac_drbg.h:

This graph shows which files directly or indirectly include this file:

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
#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 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

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). (For use with deterministic ECDSA.) 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...

Detailed Description

HMAC_DRBG (NIST SP 800-90A)

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

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)

Macro Definition Documentation

MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED   -0x0009

The entropy source failed.

MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR   -0x0007

Read/write error in file.

MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG   -0x0005

Input too large (Entropy + additional).

MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG   -0x0003

Too many random requested in single call.

MBEDTLS_HMAC_DRBG_MAX_INPUT

#define MBEDTLS_HMAC_DRBG_MAX_INPUT   256

Maximum number of additional input bytes

MBEDTLS_HMAC_DRBG_MAX_REQUEST

#define MBEDTLS_HMAC_DRBG_MAX_REQUEST   1024

Maximum number of requested bytes per call

MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT

#define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT   384

Maximum size of (re)seed buffer

MBEDTLS_HMAC_DRBG_PR_OFF

#define MBEDTLS_HMAC_DRBG_PR_OFF   0

No prediction resistance

MBEDTLS_HMAC_DRBG_PR_ON

#define MBEDTLS_HMAC_DRBG_PR_ON   1

Prediction resistance enabled

MBEDTLS_HMAC_DRBG_RESEED_INTERVAL

#define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL   10000

Interval before reseed is performed by default

Function Documentation

mbedtls_hmac_drbg_free()

void mbedtls_hmac_drbg_free

(

mbedtls_hmac_drbg_context *

ctx

)

Free an HMAC_DRBG context.

Parameters

ctx	HMAC_DRBG context to free.

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_hmac_drbg_init()

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

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_hmac_drbg_random()

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

Here is the call graph for this function:

Here is the caller graph for this function:

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
	)

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.

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_hmac_drbg_reseed()

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_hmac_drbg_set_entropy_len()

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

mbedtls_hmac_drbg_set_prediction_resistance()

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

Here is the caller graph for this function:

mbedtls_hmac_drbg_set_reseed_interval()

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

mbedtls_hmac_drbg_update()

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.

Here is the call graph for this function:

Here is the caller graph for this function: