ctr_drbg.h File Reference

CTR_DRBG based on AES-256 (NIST SP 800-90) More...

`#include "aes.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
| CTR_DRBG context structure. More...

## Macros

#define | MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034
| The entropy source failed. More...
#define | MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036
| Too many random requested in single call. More...
#define | MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038
| Input too large (Entropy + additional). More...
#define | MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A
| Read/write error in file. More...
#define | MBEDTLS_CTR_DRBG_BLOCKSIZE 16
| Block size used by the cipher. More...
#define | MBEDTLS_CTR_DRBG_KEYSIZE 32
| Key size used by the cipher. More...
#define | MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
#define | MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
| The seed length (counter + AES key) More...
#define | MBEDTLS_CTR_DRBG_PR_OFF 0
| No prediction resistance. More...
#define | MBEDTLS_CTR_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_CTR_DRBG_ENTROPY_LEN 32
| Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) More...
#define | MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
| Interval before reseed is performed by default. More...
#define | MBEDTLS_CTR_DRBG_MAX_INPUT 256
| Maximum number of additional input bytes. More...
#define | MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
| Maximum number of requested bytes per call. More...
#define | MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
| Maximum size of (re)seed buffer. More...

## Functions

void | mbedtls_ctr_drbg_init (mbedtls_ctr_drbg_context *ctx)
| CTR_DRBG context initialization Makes the context ready for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free(). More...
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)
| CTR_DRBG initial seeding Seed and setup entropy source for future reseeds. More...
void | mbedtls_ctr_drbg_free (mbedtls_ctr_drbg_context *ctx)
| Clear CTR_CRBG context data. More...
void | mbedtls_ctr_drbg_set_prediction_resistance (mbedtls_ctr_drbg_context *ctx, int resistance)
| Enable / disable prediction resistance (Default: Off) More...
void | mbedtls_ctr_drbg_set_entropy_len (mbedtls_ctr_drbg_context *ctx, size_t len)
| Set the amount of entropy grabbed on each (re)seed (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN) More...
void | mbedtls_ctr_drbg_set_reseed_interval (mbedtls_ctr_drbg_context *ctx, int interval)
| Set the reseed interval (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL) More...
int | mbedtls_ctr_drbg_reseed (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t len)
| CTR_DRBG reseeding (extracts data from entropy source) More...
void | mbedtls_ctr_drbg_update (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t add_len)
| CTR_DRBG update state. More...
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)
| CTR_DRBG generate random with additional update input. More...
int | mbedtls_ctr_drbg_random (void *p_rng, unsigned char *output, size_t output_len)
| CTR_DRBG generate random. More...
int | mbedtls_ctr_drbg_write_seed_file (mbedtls_ctr_drbg_context *ctx, const char *path)
| Write a seed file. More...
int | mbedtls_ctr_drbg_update_seed_file (mbedtls_ctr_drbg_context *ctx, const char *path)
| Read and update a seed file. More...
int | mbedtls_ctr_drbg_self_test (int verbose)
| Checkup routine. More...
int | mbedtls_ctr_drbg_seed_entropy_len (mbedtls_ctr_drbg_context *, int(*)(void *, unsigned char *, size_t), void *, const unsigned char *, size_t, size_t)

## Detailed Description

CTR_DRBG based on AES-256 (NIST SP 800-90)

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

## Macro Definition Documentation

#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16

Block size used by the cipher.

Definition at line 37 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32

Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256)

Definition at line 55 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

Definition at line 39 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_KEYSIZE 32

Key size used by the cipher.

Definition at line 38 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_INPUT 256

Maximum number of additional input bytes.

Definition at line 64 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024

Maximum number of requested bytes per call.

Definition at line 68 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

Maximum size of (re)seed buffer.

Definition at line 72 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_PR_OFF 0

No prediction resistance.

Definition at line 77 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_PR_ON 1

Prediction resistance enabled.

Definition at line 78 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000

Interval before reseed is performed by default.

Definition at line 60 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

The seed length (counter + AES key)

Definition at line 40 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

The entropy source failed.

Definition at line 32 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A

Read/write error in file.

Definition at line 35 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038

Input too large (Entropy + additional).

Definition at line 34 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036

Too many random requested in single call.

Definition at line 33 of file ctr_drbg.h.

## Function Documentation

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

Clear CTR_CRBG context data.

Parameters

  ctx | CTR_DRBG context to clear

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

CTR_DRBG context initialization Makes the context ready for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free().

Parameters

  ctx | CTR_DRBG context to be initialized

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

CTR_DRBG generate random.

Note: Automatically reseeds if reseed_counter is reached.

Parameters

  p_rng | CTR_DRBG context
  output | Buffer to fill
  output_len | Length of the buffer

Returns
  0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

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

CTR_DRBG generate random with additional update input.

Note: Automatically reseeds if reseed_counter is reached.

Parameters

  p_rng | CTR_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

Returns
  0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

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

CTR_DRBG reseeding (extracts data from entropy source)

Parameters

  ctx | CTR_DRBG context
  additional | Additional data to add to state (Can be NULL)
  len | Length of additional data

Returns
  0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

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

CTR_DRBG initial seeding Seed and setup entropy source for future reseeds.

Note: Personalization data can be provided in addition to the more generic entropy source to make this instantiation as unique as possible.

Parameters

  ctx | CTR_DRBG context to be seeded
  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

Returns
  0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

int mbedtls_ctr_drbg_seed_entropy_len | ( | mbedtls_ctr_drbg_context * | ,
|  | int(*)(void *, unsigned char *, size_t) | ,
|  | void * | ,
|  | const unsigned char * | ,
|  | size_t | ,
|  | size_t |
| ) |  |

int mbedtls_ctr_drbg_self_test | ( | int | verbose | ) |

Checkup routine.

Returns
  0 if successful, or 1 if the test failed

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

Set the amount of entropy grabbed on each (re)seed (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN)

Parameters

  ctx | CTR_DRBG context
  len | Amount of entropy to grab

void mbedtls_ctr_drbg_set_prediction_resistance | ( | mbedtls_ctr_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 | CTR_DRBG context
  resistance | MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF

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

Set the reseed interval (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL)

Parameters

  ctx | CTR_DRBG context
  interval | Reseed interval

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

CTR_DRBG update state.

Parameters

  ctx | CTR_DRBG context
  additional | Additional data to update state with
  add_len | Length of additional data

Note
  If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used, the remaining ones are silently discarded.

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

Read and update a seed file.

Seed is added to this instance

Parameters

  ctx | CTR_DRBG context
  path | Name of the file

Returns
  0 if successful, MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

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

Write a seed file.

Parameters

  ctx | CTR_DRBG context
  path | Name of the file

Returns
  0 if successful, MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED