hmac_drbg.h File Reference

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

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

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

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