mbed TLS v2.23.0: hmac_drbg.h File Reference

mbed TLS v2.23.0

Data Structures | Macros
hmac_drbg.h File Reference

The HMAC_DRBG pseudorandom generator. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/md.h"`
Include dependency graph for hmac_drbg.h:

Go to the source code of this file.

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

## 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
#define | MBEDTLS_HMAC_DRBG_PR_OFF 0
#define | MBEDTLS_HMAC_DRBG_PR_ON 1
#define | MBEDTLS_DEPRECATED
typedef struct mbedtls_hmac_drbg_context | mbedtls_hmac_drbg_context
void | mbedtls_hmac_drbg_init (mbedtls_hmac_drbg_context *ctx)
| HMAC_DRBG context initialization. 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. 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)
| This function turns prediction resistance on or off. The default value is off. More...
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 seed or reseed. More...
void | mbedtls_hmac_drbg_set_reseed_interval (mbedtls_hmac_drbg_context *ctx, int interval)
| Set the reseed interval. More...
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. More...
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. 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)
| This function updates an HMAC_DRBG instance with additional data and uses it to generate random data. More...
int | mbedtls_hmac_drbg_random (void *p_rng, unsigned char *output, size_t out_len)
| This function uses HMAC_DRBG to generate random data. More...
void | mbedtls_hmac_drbg_free (mbedtls_hmac_drbg_context *ctx)
| Free an HMAC_DRBG context. More...
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. More...
int | mbedtls_hmac_drbg_write_seed_file (mbedtls_hmac_drbg_context *ctx, const char *path)
| This function writes a seed file. More...
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. More...
int | mbedtls_hmac_drbg_self_test (int verbose)
| The HMAC_DRBG Checkup routine. More...

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

## Macro Definition Documentation

## ◆ MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

Definition at line 350 of file hmac_drbg.h.

## ◆ MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009

The entropy source failed.

Definition at line 50 of file hmac_drbg.h.

## ◆ MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007

Read/write error in file.

Definition at line 49 of file hmac_drbg.h.

## ◆ MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005

Input too large (Entropy + additional).

Definition at line 48 of file hmac_drbg.h.

## ◆ MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003

Too many random requested in single call.

Definition at line 47 of file hmac_drbg.h.

## ◆ MBEDTLS_HMAC_DRBG_MAX_INPUT

#define MBEDTLS_HMAC_DRBG_MAX_INPUT 256

Maximum number of additional input bytes

Definition at line 65 of file hmac_drbg.h.

## ◆ MBEDTLS_HMAC_DRBG_MAX_REQUEST

#define MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024

Maximum number of requested bytes per call

Definition at line 69 of file hmac_drbg.h.

## ◆ MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT

#define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384

Maximum size of (re)seed buffer

Definition at line 73 of file hmac_drbg.h.

## ◆ MBEDTLS_HMAC_DRBG_PR_OFF

#define MBEDTLS_HMAC_DRBG_PR_OFF 0

No prediction resistance

Definition at line 78 of file hmac_drbg.h.

## ◆ MBEDTLS_HMAC_DRBG_PR_ON

#define MBEDTLS_HMAC_DRBG_PR_ON 1

Prediction resistance enabled

Definition at line 79 of file hmac_drbg.h.

## ◆ MBEDTLS_HMAC_DRBG_RESEED_INTERVAL

#define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000

Interval before reseed is performed by default

Definition at line 61 of file hmac_drbg.h.

## Typedef Documentation

## ◆ mbedtls_hmac_drbg_context

typedef struct mbedtls_hmac_drbg_context mbedtls_hmac_drbg_context

HMAC_DRBG context.

## Function Documentation

## ◆ mbedtls_hmac_drbg_free()

void mbedtls_hmac_drbg_free | ( | mbedtls_hmac_drbg_context * | ctx | ) |

Free an HMAC_DRBG context.

Parameters

  ctx | The HMAC_DRBG context to free.

## ◆ mbedtls_hmac_drbg_init()

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.

## ◆ mbedtls_hmac_drbg_random()

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.

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

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.

## ◆ mbedtls_hmac_drbg_reseed()

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.

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

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().
  The default entropy length is the security strength (converted from bits to bytes). You can override it by calling mbedtls_hmac_drbg_set_entropy_len().
  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.

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

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.

## ◆ mbedtls_hmac_drbg_self_test()

int mbedtls_hmac_drbg_self_test | ( | int | verbose | ) |

The HMAC_DRBG Checkup routine.

Returns
  `0` if successful.
  `1` if the test failed.

## ◆ mbedtls_hmac_drbg_set_entropy_len()

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

See the documentation of mbedtls_hmac_drbg_seed() for the default value.

Parameters

  ctx | The HMAC_DRBG context.
  len | The 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
| ) |  |

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.

## ◆ mbedtls_hmac_drbg_set_reseed_interval()

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.

## ◆ mbedtls_hmac_drbg_update()

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.

Deprecated:
  Superseded by mbedtls_hmac_drbg_update_ret() in 2.16.0.

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

## ◆ mbedtls_hmac_drbg_update_ret()

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.

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

## ◆ mbedtls_hmac_drbg_write_seed_file()

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.