mbed TLS v2.2.0
Data Structures | Macros | Functions
hmac_drbg.h File Reference

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)

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
ctxHMAC_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
ctxHMAC_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_rngHMAC_DRBG context
outputBuffer to fill
out_lenLength 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_rngHMAC_DRBG context
outputBuffer to fill
output_lenLength of the buffer
additionalAdditional data to update with (can be NULL)
add_lenLength 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
ctxHMAC_DRBG context
additionalAdditional data to add to state (Can be NULL)
lenLength 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
ctxHMAC_DRBG context to be seeded
md_infoMD algorithm to use for HMAC_DRBG
f_entropyEntropy callback (p_entropy, buffer to fill, buffer length)
p_entropyEntropy context
customPersonalization data (Device specific identifiers) (Can be NULL)
lenLength 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
ctxHMAC_DRBG context to be initialised
md_infoMD algorithm to use for HMAC_DRBG
dataConcatenation of entropy string and additional data
data_lenLength 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
ctxHMAC_DRBG context
lenAmount 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
ctxHMAC_DRBG context
resistanceMBEDTLS_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
ctxHMAC_DRBG context
intervalReseed interval
void mbedtls_hmac_drbg_update ( mbedtls_hmac_drbg_context ctx,
const unsigned char *  additional,
size_t  add_len 
)

HMAC_DRBG update state.

Parameters
ctxHMAC_DRBG context
additionalAdditional data to update state with, or NULL
add_lenLength 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.