Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
hmac_drbg.h File Reference
The HMAC_DRBG pseudorandom generator. More...
Go to the source code of this file.
Data Structures | |
| struct | mbedtls_hmac_drbg_context |
| HMAC_DRBG context. More... | |
Typedefs | |
| typedef struct mbedtls_hmac_drbg_context | mbedtls_hmac_drbg_context |
| HMAC_DRBG context. | |
Functions | |
| void | mbedtls_hmac_drbg_init (mbedtls_hmac_drbg_context *ctx) |
| HMAC_DRBG context initialization. | |
| 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. | |
| 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). | |
| void | mbedtls_hmac_drbg_set_prediction_resistance (mbedtls_hmac_drbg_context *ctx, int resistance) |
| This function turns prediction resistance on or off. | |
| 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 reseed. | |
| void | mbedtls_hmac_drbg_set_reseed_interval (mbedtls_hmac_drbg_context *ctx, int interval) |
| Set the reseed interval. | |
| 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. | |
| 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. | |
| 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. | |
| int | mbedtls_hmac_drbg_random (void *p_rng, unsigned char *output, size_t out_len) |
| This function uses HMAC_DRBG to generate random data. | |
| void | mbedtls_hmac_drbg_free (mbedtls_hmac_drbg_context *ctx) |
| Free an HMAC_DRBG context. | |
| 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. | |
| int | mbedtls_hmac_drbg_write_seed_file (mbedtls_hmac_drbg_context *ctx, const char *path) |
| This function writes a 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. | |
| int | mbedtls_hmac_drbg_self_test (int verbose) |
| The HMAC_DRBG Checkup routine. | |
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.
Typedef Documentation
| typedef struct mbedtls_hmac_drbg_context mbedtls_hmac_drbg_context |
HMAC_DRBG context.
Function Documentation
| void mbedtls_hmac_drbg_free | ( | mbedtls_hmac_drbg_context * | ctx ) |
Free an HMAC_DRBG context.
- Parameters:
-
ctx The HMAC_DRBG context to free.
Definition at line 419 of file hmac_drbg.c.
| 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.
Definition at line 57 of file hmac_drbg.c.
| 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:
0if 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.
Definition at line 396 of file hmac_drbg.c.
| 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 andadd_lenshould be0.add_len The length of the additional data. This must be at most MBEDTLS_HMAC_DRBG_MAX_INPUT.
- Returns:
0if 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.
Definition at line 325 of file hmac_drbg.c.
| 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 andlenshould be0.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_lenwhereentropy_lenis the entropy length (see mbedtls_hmac_drbg_set_entropy_len()).
- Returns:
0if successful.- MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED if a call to the entropy function failed.
Definition at line 235 of file hmac_drbg.c.
| 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_entropyis mbedtls_entropy_func();p_entropyis 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_infois SHA-1; - 192 bits if
md_infois SHA-224; - 256 bits if
md_infois 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() afterwards.
- 128 bits if
- The entropy length for the initial seeding is the security strength (converted from bits to bytes). You can set a different entropy length for subsequent seeding by calling mbedtls_hmac_drbg_set_entropy_len() after this function.
- 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_entropycontext, the buffer to fill, and the length of the buffer.f_entropyis 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 oflen.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 whereentropy_lenis the entropy length described above.
- Returns:
0if successful.-
MBEDTLS_ERR_MD_BAD_INPUT_DATA if
md_infois 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_entropyfailed.
Definition at line 247 of file hmac_drbg.c.
| 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 datain bytes.
- Returns:
0if successful. or-
MBEDTLS_ERR_MD_BAD_INPUT_DATA if
md_infois invalid. - MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough memory to allocate context data.
Definition at line 126 of file hmac_drbg.c.
| int mbedtls_hmac_drbg_self_test | ( | int | verbose ) |
The HMAC_DRBG Checkup routine.
- Returns:
0if successful.-
1if the test failed.
Definition at line 562 of file hmac_drbg.c.
| 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 reseed.
The default value is set by mbedtls_hmac_drbg_seed().
- Note:
- mbedtls_hmac_drbg_seed() always sets the entropy length to the default value based on the chosen MD algorithm, so this function only has an effect if it is called after mbedtls_hmac_drbg_seed().
- Parameters:
-
ctx The HMAC_DRBG context. len The amount of entropy to grab, in bytes.
Definition at line 308 of file hmac_drbg.c.
| 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.
Definition at line 299 of file hmac_drbg.c.
| 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.
Definition at line 316 of file hmac_drbg.c.
| 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.
- 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 additionalin bytes. Unused ifadditionalisNULL.
Definition at line 115 of file hmac_drbg.c.
| 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 additionalin bytes. Unused ifadditionalisNULL.
- Returns:
0on success, or an error from the underlying hash calculation.
Definition at line 69 of file hmac_drbg.c.
| 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:
0on 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.
Definition at line 459 of file hmac_drbg.c.
| 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:
0on success.- MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.
- MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.
Definition at line 432 of file hmac_drbg.c.
Generated on Tue Jul 12 2022 13:55:12 by
1.7.2