Loading...
Searching...
No Matches
ctr_drbg.h File Reference

This file contains definitions and functions for the CTR_DRBG pseudorandom generator. More...

`#include "mbedtls/private_access.h"`
`#include "mbedtls/build_info.h"`
`#include "mbedtls/aes.h"`
`#include "entropy.h"`
`#include "mbedtls/threading.h"`
Include dependency graph for ctr_drbg.h:

Go to the source code of this file.

## Data Structures

struct | mbedtls_ctr_drbg_context
| The CTR_DRBG context structure. More...

## Macros

#define | MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034
#define | MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036
#define | MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038
#define | MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A
#define | MBEDTLS_CTR_DRBG_BLOCKSIZE 16
#define | MBEDTLS_CTR_DRBG_KEYSIZE 32
#define | MBEDTLS_CTR_DRBG_KEYBITS (MBEDTLS_CTR_DRBG_KEYSIZE * 8)
#define | MBEDTLS_CTR_DRBG_SEEDLEN (MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE)
#define | MBEDTLS_CTR_DRBG_PR_OFF 0
#define | MBEDTLS_CTR_DRBG_PR_ON 1
#define | MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0
SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in mbedtls_config.h or define them using the compiler command line.
#define | MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
| The amount of entropy used per seed by default, in bytes.
#define | MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
#define | MBEDTLS_CTR_DRBG_MAX_INPUT 256
#define | MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
#define | MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

## Typedefs

typedef struct mbedtls_ctr_drbg_context | mbedtls_ctr_drbg_context
| The CTR_DRBG context structure.

## Functions

void | mbedtls_ctr_drbg_init (mbedtls_ctr_drbg_context *ctx)
| This function initializes the CTR_DRBG context, and prepares it for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free().
int | mbedtls_ctr_drbg_seed (mbedtls_ctr_drbg_context *ctx, int(*f_entropy)(void *, unsigned char *, size_t), void *p_entropy, const unsigned char *custom, size_t len)
| This function seeds and sets up the CTR_DRBG entropy source for future reseeds.
void | mbedtls_ctr_drbg_free (mbedtls_ctr_drbg_context *ctx)
| This function resets CTR_DRBG context to the state immediately after initial call of mbedtls_ctr_drbg_init().
void | mbedtls_ctr_drbg_set_prediction_resistance (mbedtls_ctr_drbg_context *ctx, int resistance)
| This function turns prediction resistance on or off. The default value is off.
void | mbedtls_ctr_drbg_set_entropy_len (mbedtls_ctr_drbg_context *ctx, size_t len)
| This function sets the amount of entropy grabbed on each seed or reseed.
int | mbedtls_ctr_drbg_set_nonce_len (mbedtls_ctr_drbg_context *ctx, size_t len)
| This function sets the amount of entropy grabbed as a nonce for the initial seeding.
void | mbedtls_ctr_drbg_set_reseed_interval (mbedtls_ctr_drbg_context *ctx, int interval)
| This function sets the reseed interval.
int | mbedtls_ctr_drbg_reseed (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t len)
| This function reseeds the CTR_DRBG context, that is extracts data from the entropy source.
int | mbedtls_ctr_drbg_update (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t add_len)
| This function updates the state of the CTR_DRBG context.
int | mbedtls_ctr_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 a CTR_DRBG instance with additional data and uses it to generate random data.
int | mbedtls_ctr_drbg_random (void *p_rng, unsigned char *output, size_t output_len)
| This function uses CTR_DRBG to generate random data.
int | mbedtls_ctr_drbg_write_seed_file (mbedtls_ctr_drbg_context *ctx, const char *path)
| This function writes a seed file.
int | mbedtls_ctr_drbg_update_seed_file (mbedtls_ctr_drbg_context *ctx, const char *path)
| This function reads and updates a seed file. The seed is added to this instance.
int | mbedtls_ctr_drbg_self_test (int verbose)
| The CTR_DRBG checkup routine.

## Detailed Description

This file contains definitions and functions for the CTR_DRBG pseudorandom generator.

CTR_DRBG is a standardized way of building a PRNG from a block-cipher in counter mode operation, as defined in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators.

The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128 (if `MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` is enabled at compile time) as the underlying block cipher, with a derivation function.

The security strength as defined in NIST SP 800-90A is 128 bits when AES-128 is used (`MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` enabled) and 256 bits otherwise, provided that MBEDTLS_CTR_DRBG_ENTROPY_LEN is kept at its default value (and not overridden in mbedtls_config.h) and that the DRBG instance is set up with default parameters. See the documentation of mbedtls_ctr_drbg_seed() for more information.

Definition in file ctr_drbg.h.

## Macro Definition Documentation

## MBEDTLS_CTR_DRBG_BLOCKSIZE

#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16

The block size used by the cipher.

Definition at line 73 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_ENTROPY_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48

The amount of entropy used per seed by default, in bytes.

This is 48 bytes because the entropy module uses SHA-512.

Definition at line 111 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0

The default length of the nonce read from the entropy source.

This is `0` because a single read from the entropy source is sufficient to include a nonce. See the documentation of mbedtls_ctr_drbg_seed() for more information.

Definition at line 164 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_KEYBITS

#define MBEDTLS_CTR_DRBG_KEYBITS (MBEDTLS_CTR_DRBG_KEYSIZE * 8)

The key size for the DRBG operation, in bits.

Definition at line 91 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_KEYSIZE

#define MBEDTLS_CTR_DRBG_KEYSIZE 32

The key size in bytes used by the cipher.

Compile-time choice: 32 bytes (256 bits) because `MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` is disabled.

Definition at line 88 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_MAX_INPUT

#define MBEDTLS_CTR_DRBG_MAX_INPUT 256

The maximum number of additional input Bytes.

Definition at line 133 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_MAX_REQUEST

#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024

The maximum number of requested Bytes per call.

Definition at line 138 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_MAX_SEED_INPUT

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

The maximum size of seed or reseed buffer in bytes.

Definition at line 143 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_PR_OFF

#define MBEDTLS_CTR_DRBG_PR_OFF 0

Prediction resistance is disabled.

Definition at line 149 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_PR_ON

#define MBEDTLS_CTR_DRBG_PR_ON 1

Prediction resistance is enabled.

Definition at line 151 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_RESEED_INTERVAL

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000

The interval before reseed is performed by default.

Definition at line 128 of file ctr_drbg.h.

## MBEDTLS_CTR_DRBG_SEEDLEN

#define MBEDTLS_CTR_DRBG_SEEDLEN (MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE)

The seed length, calculated as (counter + AES key).

Definition at line 92 of file ctr_drbg.h.

## MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

The entropy source failed.

Definition at line 65 of file ctr_drbg.h.

## MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A

Read or write error in file.

Definition at line 71 of file ctr_drbg.h.

## MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038

The input (entropy + additional data) is too large.

Definition at line 69 of file ctr_drbg.h.

## MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036

The requested random buffer length is too big.

Definition at line 67 of file ctr_drbg.h.

## Typedef Documentation

## mbedtls_ctr_drbg_context

typedef struct mbedtls_ctr_drbg_context mbedtls_ctr_drbg_context

The CTR_DRBG context structure.

## Function Documentation

## mbedtls_ctr_drbg_free()

void mbedtls_ctr_drbg_free | ( | mbedtls_ctr_drbg_context * | ctx | ) |

This function resets CTR_DRBG context to the state immediately after initial call of mbedtls_ctr_drbg_init().

Parameters

  ctx | The CTR_DRBG context to clear.

## mbedtls_ctr_drbg_init()

void mbedtls_ctr_drbg_init | ( | mbedtls_ctr_drbg_context * | ctx | ) |

This function initializes the CTR_DRBG context, and prepares it for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free().

Note
  The reseed interval is MBEDTLS_CTR_DRBG_RESEED_INTERVAL by default. You can override it by calling mbedtls_ctr_drbg_set_reseed_interval().

Parameters

  ctx | The CTR_DRBG context to initialize.

## mbedtls_ctr_drbg_random()

int mbedtls_ctr_drbg_random | ( | void * | p_rng,
|  | unsigned char * | output,
|  | size_t | output_len
| ) |  |

This function uses CTR_DRBG to generate random data.

This function automatically reseeds if the reseed counter is exceeded or prediction resistance is enabled.

Note
  When Mbed TLS is built with threading support, it is safe to call mbedtls_ctr_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.

Parameters

  p_rng | The CTR_DRBG context. This must be a pointer to a mbedtls_ctr_drbg_context structure.
  output | The buffer to fill.
  output_len | The length of the buffer in bytes.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.

## mbedtls_ctr_drbg_random_with_add()

int mbedtls_ctr_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 a CTR_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.

Note
  This function is not thread-safe. It is not safe to call this function if another thread might be concurrently obtaining random numbers from the same context or updating or reseeding the same context.

Parameters

  p_rng | The CTR_DRBG context. This must be a pointer to a mbedtls_ctr_drbg_context structure.
  output | The buffer to fill.
  output_len | The length of the buffer in bytes.
  additional | Additional data to update. Can be `NULL`, in which case the additional data is empty regardless of the value of `add_len`.
  add_len | The length of the additional data if `additional` is not `NULL`. This must be less than MBEDTLS_CTR_DRBG_MAX_INPUT and less than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - `entropy_len` where `entropy_len` is the entropy length configured for the context.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.

## mbedtls_ctr_drbg_reseed()

int mbedtls_ctr_drbg_reseed | ( | mbedtls_ctr_drbg_context * | ctx,
|  | const unsigned char * | additional,
|  | size_t | len
| ) |  |

This function reseeds the CTR_DRBG context, that is extracts data from the entropy source.

Note
  This function is not thread-safe. It is not safe to call this function if another thread might be concurrently obtaining random numbers from the same context or updating or reseeding the same context.

Parameters

  ctx | The CTR_DRBG context.
  additional | Additional data to add to the state. Can be `NULL`.
  len | The length of the additional data. This must be less than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - `entropy_len` where `entropy_len` is the entropy length configured for the context.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.

## mbedtls_ctr_drbg_seed()

int mbedtls_ctr_drbg_seed | ( | mbedtls_ctr_drbg_context * | ctx,
|  | int(*)(void *, unsigned char *, size_t) | f_entropy,
|  | void * | p_entropy,
|  | const unsigned char * | custom,
|  | size_t | len
| ) |  |

This function seeds and sets up the CTR_DRBG 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).

The entropy length is MBEDTLS_CTR_DRBG_ENTROPY_LEN by default. You can override it by calling mbedtls_ctr_drbg_set_entropy_len().

The entropy nonce length is:

- `0` if the entropy length is at least 3/2 times the entropy length, which guarantees that the security strength is the maximum permitted by the key size and entropy length according to NIST SP 800-90A §10.2.1;
- Half the entropy length otherwise. You can override it by calling mbedtls_ctr_drbg_set_nonce_len(). With the default entropy length, the entropy nonce length is MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN.

You can provide a nonce and personalization string in addition to the entropy source, to make this instantiation as unique as possible. See SP 800-90A §8.6.7 for more details about nonces.

The seed_material value passed to the derivation function in the CTR_DRBG Instantiate Process described in NIST SP 800-90A §10.2.1.3.2 is the concatenation of the following strings:

- A string obtained by calling `f_entropy` function for the entropy length.
- If mbedtls_ctr_drbg_set_nonce_len() has been called, a string obtained by calling `f_entropy` function for the specified length.
  Note
    When Mbed TLS is built with threading support, after this function returns successfully, it is safe to call mbedtls_ctr_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.
- The `custom` string.

Note
  To achieve the nominal security strength permitted by CTR_DRBG, the entropy length must be:
  - at least 16 bytes for a 128-bit strength (maximum achievable strength when using AES-128);
  - at least 32 bytes for a 256-bit strength (maximum achievable strength when using AES-256).

In addition, if you do not pass a nonce in `custom`, the sum of the entropy length and the entropy nonce length must be:

- at least 24 bytes for a 128-bit strength (maximum achievable strength when using AES-128);
- at least 48 bytes for a 256-bit strength (maximum achievable strength when using AES-256).

Parameters

  ctx | The CTR_DRBG context to seed. It must have been initialized with mbedtls_ctr_drbg_init(). After a successful call to mbedtls_ctr_drbg_seed(), you may not call mbedtls_ctr_drbg_seed() again on the same context unless you call mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init() again first. After a failed call to mbedtls_ctr_drbg_seed(), you must call mbedtls_ctr_drbg_free().
  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 buffer size 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_CTR_DRBG_MAX_SEED_INPUT
  - MBEDTLS_CTR_DRBG_ENTROPY_LEN.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.

## mbedtls_ctr_drbg_self_test()

int mbedtls_ctr_drbg_self_test | ( | int | verbose | ) |

The CTR_DRBG checkup routine.

Returns
  `0` on success.
  `1` on failure.

## mbedtls_ctr_drbg_set_entropy_len()

void mbedtls_ctr_drbg_set_entropy_len | ( | mbedtls_ctr_drbg_context * | ctx,
|  | size_t | len
| ) |  |

This function sets the amount of entropy grabbed on each seed or reseed.

The default value is MBEDTLS_CTR_DRBG_ENTROPY_LEN.

Note
  The security strength of CTR_DRBG is bounded by the entropy length. Thus:
  - When using AES-256 (`MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` is disabled, which is the default), `len` must be at least 32 (in bytes) to achieve a 256-bit strength.
  - When using AES-128 (`MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` is enabled) `len` must be at least 16 (in bytes) to achieve a 128-bit strength.

Parameters

  ctx | The CTR_DRBG context.
  len | The amount of entropy to grab, in bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT and at most the maximum length accepted by the entropy function that is set in the context.

## mbedtls_ctr_drbg_set_nonce_len()

int mbedtls_ctr_drbg_set_nonce_len | ( | mbedtls_ctr_drbg_context * | ctx,
|  | size_t | len
| ) |  |

This function sets the amount of entropy grabbed as a nonce for the initial seeding.

Call this function before calling mbedtls_ctr_drbg_seed() to read a nonce from the entropy source during the initial seeding.

Parameters

  ctx | The CTR_DRBG context.
  len | The amount of entropy to grab for the nonce, in bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT and at most the maximum length accepted by the entropy function that is set in the context.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if `len` is more than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED if the initial seeding has already taken place.

## mbedtls_ctr_drbg_set_prediction_resistance()

void mbedtls_ctr_drbg_set_prediction_resistance | ( | mbedtls_ctr_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_ctr_drbg_random_with_add() or mbedtls_ctr_drbg_random(). Only use this if your entropy source has sufficient throughput.

Parameters

  ctx | The CTR_DRBG context.
  resistance | MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF.

## mbedtls_ctr_drbg_set_reseed_interval()

void mbedtls_ctr_drbg_set_reseed_interval | ( | mbedtls_ctr_drbg_context * | ctx,
|  | int | interval
| ) |  |

This function sets the reseed interval.

The reseed interval is the number of calls to mbedtls_ctr_drbg_random() or mbedtls_ctr_drbg_random_with_add() after which the entropy function is called again.

The default value is MBEDTLS_CTR_DRBG_RESEED_INTERVAL.

Parameters

  ctx | The CTR_DRBG context.
  interval | The reseed interval.

## mbedtls_ctr_drbg_update()

int mbedtls_ctr_drbg_update | ( | mbedtls_ctr_drbg_context * | ctx,
|  | const unsigned char * | additional,
|  | size_t | add_len
| ) |  |

This function updates the state of the CTR_DRBG context.

Note
  This function is not thread-safe. It is not safe to call this function if another thread might be concurrently obtaining random numbers from the same context or updating or reseeding the same context.

Parameters

  ctx | The CTR_DRBG context.
  additional | The data to update the state with. This must not be `NULL` unless `add_len` is `0`.
  add_len | Length of `additional` in bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if `add_len` is more than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
  An error from the underlying AES cipher on failure.

## mbedtls_ctr_drbg_update_seed_file()

int mbedtls_ctr_drbg_update_seed_file | ( | mbedtls_ctr_drbg_context * | ctx,
|  | const char * | path
| ) |  |

This function reads and updates a seed file. The seed is added to this instance.

Parameters

  ctx | The CTR_DRBG context.
  path | The name of the file.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.
  MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing seed file is too large.

## mbedtls_ctr_drbg_write_seed_file()

int mbedtls_ctr_drbg_write_seed_file | ( | mbedtls_ctr_drbg_context * | ctx,
|  | const char * | path
| ) |  |

This function writes a seed file.

Parameters

  ctx | The CTR_DRBG context.
  path | The name of the file.

Returns
  `0` on success.
  MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
  MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.