hmac_drbg.h
mbedtls/config.h
mbedtls/md.h
mbedtls/threading.h
mbedtls/check_config.h
mbedtls/config.h
hmac_drbg.h
mbedtls/md.h
mbedtls/platform_time.h
mbedtls/platform_util.h
mbedtls/threading.h
limits.h
pthread.h
stddef.h
stdlib.h
time.h
mbedtls_hmac_drbg_context
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.

MBEDTLS_HMAC_DRBG_RESEED_INTERVAL
10000

Interval before reseed is performed by default

MBEDTLS_HMAC_DRBG_MAX_INPUT
256

Maximum number of additional input bytes

MBEDTLS_HMAC_DRBG_MAX_REQUEST
1024

Maximum number of requested bytes per call

MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT
384

Maximum size of (re)seed buffer

MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG
-0x0003

Too many random requested in single call.

MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG
-0x0005

Input too large (Entropy + additional).

MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR
-0x0007

Read/write error in file.

MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
-0x0009

The entropy source failed.

MBEDTLS_HMAC_DRBG_PR_OFF
0

No prediction resistance

MBEDTLS_HMAC_DRBG_PR_ON
1

Prediction resistance enabled

MBEDTLS_DEPRECATED
__attribute__((deprecated))
struct mbedtls_hmac_drbg_context typedef struct mbedtls_hmac_drbg_context mbedtls_hmac_drbg_context mbedtls_hmac_drbg_context

HMAC_DRBG context.

void void mbedtls_hmac_drbg_init (mbedtls_hmac_drbg_context *ctx) 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().

The reseed interval is MBEDTLS_HMAC_DRBG_RESEED_INTERVAL by default. Override this value by calling mbedtls_hmac_drbg_set_reseed_interval().

ctx

HMAC_DRBG context to be initialized.

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

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.

When Mbed TLS is built with threading support, after this function returns successfully, it is safe to call mbedtls_hmac_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.

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.

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

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

Initialisation of simplified HMAC_DRBG (never reseeds).

This function is meant for use in algorithms that need a pseudorandom input such as deterministic ECDSA.

When Mbed TLS is built with threading support, after this function returns successfully, it is safe to call mbedtls_hmac_drbg_random() from multiple threads. Other operations, including reseeding, are not thread-safe.

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.

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

void void mbedtls_hmac_drbg_set_prediction_resistance (mbedtls_hmac_drbg_context *ctx, int resistance) 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.

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.

ctx

The HMAC_DRBG context.

resistance

MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF.

void void mbedtls_hmac_drbg_set_entropy_len (mbedtls_hmac_drbg_context *ctx, size_t len) 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.

ctx

The HMAC_DRBG context.

len

The amount of entropy to grab, in bytes.

void void mbedtls_hmac_drbg_set_reseed_interval (mbedtls_hmac_drbg_context *ctx, int interval) 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.

ctx

The HMAC_DRBG context.

interval

The reseed interval.

int int mbedtls_hmac_drbg_update_ret (mbedtls_hmac_drbg_context *ctx, const unsigned char *additional, size_t add_len) 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.

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.

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

`0` on success, or an error from the underlying hash calculation.

int int mbedtls_hmac_drbg_reseed (mbedtls_hmac_drbg_context *ctx, const unsigned char *additional, size_t len) 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.

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.

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

`0` if successful.

MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED if a call to the entropy function failed.

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

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.

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.

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

int int mbedtls_hmac_drbg_random (void *p_rng, unsigned char *output, size_t out_len) 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.

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.

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.

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

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

This function resets HMAC_DRBG context to the state immediately after initial call of mbedtls_hmac_drbg_init().

ctx

The HMAC_DRBG context to free.

MBEDTLS_DEPRECATED void MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update (mbedtls_hmac_drbg_context *ctx, const unsigned char *additional, size_t add_len) 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.

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

int int mbedtls_hmac_drbg_write_seed_file (mbedtls_hmac_drbg_context *ctx, const char *path) mbedtls_hmac_drbg_write_seed_file mbedtls_hmac_drbg_context * ctx const char * path

This function writes a seed file.

ctx

The HMAC_DRBG context.

path

The name of the file.

`0` on success.

MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.

MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.

int int mbedtls_hmac_drbg_update_seed_file (mbedtls_hmac_drbg_context *ctx, const char *path) 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.

ctx

The HMAC_DRBG context.

path

The name of the file.

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

int int mbedtls_hmac_drbg_self_test (int verbose) mbedtls_hmac_drbg_self_test int verbose

The HMAC_DRBG Checkup routine.

`0` if successful.

`1` if the test failed.

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.

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */
    #ifndefMBEDTLS_HMAC_DRBG_H
    #defineMBEDTLS_HMAC_DRBG_H

    #if!defined(MBEDTLS_CONFIG_FILE)
    #include"mbedtls/config.h"
    #else
    #includeMBEDTLS_CONFIG_FILE
    #endif

    #include"mbedtls/md.h"

    #ifdefined(MBEDTLS_THREADING_C)
    #include"mbedtls/threading.h"
    #endif

    /*
    *Errorcodes
    */
    #defineMBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG-0x0003
    #defineMBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG-0x0005
    #defineMBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR-0x0007
    #defineMBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED-0x0009

    #if!defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
    #defineMBEDTLS_HMAC_DRBG_RESEED_INTERVAL10000
    #endif

    #if!defined(MBEDTLS_HMAC_DRBG_MAX_INPUT)
    #defineMBEDTLS_HMAC_DRBG_MAX_INPUT256
    #endif

    #if!defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST)
    #defineMBEDTLS_HMAC_DRBG_MAX_REQUEST1024
    #endif

    #if!defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT)
    #defineMBEDTLS_HMAC_DRBG_MAX_SEED_INPUT384
    #endif

    #defineMBEDTLS_HMAC_DRBG_PR_OFF0
    #defineMBEDTLS_HMAC_DRBG_PR_ON1
    #ifdef__cplusplus
    extern"C"{
    #endif

    typedefstructmbedtls_hmac_drbg_context{
    /*Workingstate:thekeyKisnotstoredexplicitly,
    *butisimpliedbytheHMACcontext*/
    mbedtls_md_context_tmd_ctx;
    unsignedcharV[MBEDTLS_MD_MAX_SIZE];
    intreseed_counter;
    /*Administrativestate*/
    size_tentropy_len;
    intprediction_resistance;
    intreseed_interval;
    /*Callbacks*/
    int(*f_entropy)(void*,unsignedchar*,size_t);
    void*p_entropy;
    #ifdefined(MBEDTLS_THREADING_C)
    /*Invariant:themutexisinitializedifandonlyif
    *md_ctx->md_info!=NULL.Thismeansthatthemutexisinitialized
    *duringtheinitialseedinginmbedtls_hmac_drbg_seed()or
    *mbedtls_hmac_drbg_seed_buf()andfreedinmbedtls_ctr_drbg_free().
    *
    *Notethatthisinvariantmaychangewithoutnotice.Donotrelyonit
    *anddonotaccessthemutexdirectlyinapplicationcode.
    */
    mbedtls_threading_mutex_tmutex;
    #endif
    }mbedtls_hmac_drbg_context;

    voidmbedtls_hmac_drbg_init(mbedtls_hmac_drbg_context*ctx);

    #ifdefined(MBEDTLS_THREADING_C)
    #endif/*MBEDTLS_THREADING_C*/
    intmbedtls_hmac_drbg_seed(mbedtls_hmac_drbg_context*ctx,
    constmbedtls_md_info_t*md_info,
    int(*f_entropy)(void*,unsignedchar*,size_t),
    void*p_entropy,
    constunsignedchar*custom,
    size_tlen);

    #ifdefined(MBEDTLS_THREADING_C)
    #endif/*MBEDTLS_THREADING_C*/
    intmbedtls_hmac_drbg_seed_buf(mbedtls_hmac_drbg_context*ctx,
    constmbedtls_md_info_t*md_info,
    constunsignedchar*data,size_tdata_len);

    voidmbedtls_hmac_drbg_set_prediction_resistance(mbedtls_hmac_drbg_context*ctx,
    intresistance);

    voidmbedtls_hmac_drbg_set_entropy_len(mbedtls_hmac_drbg_context*ctx,
    size_tlen);

    voidmbedtls_hmac_drbg_set_reseed_interval(mbedtls_hmac_drbg_context*ctx,
    intinterval);

    intmbedtls_hmac_drbg_update_ret(mbedtls_hmac_drbg_context*ctx,
    constunsignedchar*additional,size_tadd_len);

    intmbedtls_hmac_drbg_reseed(mbedtls_hmac_drbg_context*ctx,
    constunsignedchar*additional,size_tlen);

    intmbedtls_hmac_drbg_random_with_add(void*p_rng,
    unsignedchar*output,size_toutput_len,
    constunsignedchar*additional,
    size_tadd_len);

    #ifdefined(MBEDTLS_THREADING_C)
    #endif/*MBEDTLS_THREADING_C*/
    intmbedtls_hmac_drbg_random(void*p_rng,unsignedchar*output,size_tout_len);

    voidmbedtls_hmac_drbg_free(mbedtls_hmac_drbg_context*ctx);

    #if!defined(MBEDTLS_DEPRECATED_REMOVED)
    #ifdefined(MBEDTLS_DEPRECATED_WARNING)
    #defineMBEDTLS_DEPRECATED__attribute__((deprecated))
    #else
    #defineMBEDTLS_DEPRECATED
    #endif
    MBEDTLS_DEPRECATEDvoidmbedtls_hmac_drbg_update(
    mbedtls_hmac_drbg_context*ctx,
    constunsignedchar*additional,size_tadd_len);
    #undefMBEDTLS_DEPRECATED
    #endif/*!MBEDTLS_DEPRECATED_REMOVED*/

    #ifdefined(MBEDTLS_FS_IO)
    intmbedtls_hmac_drbg_write_seed_file(mbedtls_hmac_drbg_context*ctx,constchar*path);

    intmbedtls_hmac_drbg_update_seed_file(mbedtls_hmac_drbg_context*ctx,constchar*path);
    #endif/*MBEDTLS_FS_IO*/

    #ifdefined(MBEDTLS_SELF_TEST)
    intmbedtls_hmac_drbg_self_test(intverbose);
    #endif

    #ifdef__cplusplus
    }
    #endif

    #endif/*hmac_drbg.h*/