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
ctr_drbg.h File Reference
This file contains definitions and functions for the CTR_DRBG pseudorandom generator. More...
Go to the source code of this file.
Data Structures | |
| struct | mbedtls_ctr_drbg_context |
| The CTR_DRBG context structure. More... | |
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 clears CTR_CRBG context data. | |
| void | mbedtls_ctr_drbg_set_prediction_resistance (mbedtls_ctr_drbg_context *ctx, int resistance) |
| This function turns prediction resistance on or 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 subsequent reseed. | |
| 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_ret (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. | |
| MBEDTLS_DEPRECATED void | 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_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. | |
| 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 initial seeding grabs MBEDTLS_CTR_DRBG_ENTROPY_LEN bytes of entropy. See the documentation of mbedtls_ctr_drbg_seed() for more details.
Based on NIST SP 800-90A §10.2.1 table 3 and NIST SP 800-57 part 1 table 2, here are the security strengths achieved in typical configuration:
- 256 bits under the default configuration of the library, with AES-256 and with MBEDTLS_CTR_DRBG_ENTROPY_LEN set to 48 or more.
- 256 bits if AES-256 is used, MBEDTLS_CTR_DRBG_ENTROPY_LEN is set to 32 or more, and the DRBG is initialized with an explicit nonce in the
customparameter to mbedtls_ctr_drbg_seed(). - 128 bits if AES-256 is used but MBEDTLS_CTR_DRBG_ENTROPY_LEN is between 24 and 47 and the DRBG is not initialized with an explicit nonce (see mbedtls_ctr_drbg_seed()).
- 128 bits if AES-128 is used (
MBEDTLS_CTR_DRBG_USE_128_BIT_KEYenabled) and MBEDTLS_CTR_DRBG_ENTROPY_LEN is set to 24 or more (which is always the case unless it is explicitly set to a different value in config.h).
Note that the value of MBEDTLS_CTR_DRBG_ENTROPY_LEN defaults to:
48if the moduleMBEDTLS_SHA512_Cis enabled and the symbolMBEDTLS_ENTROPY_FORCE_SHA256is disabled at compile time. This is the default configuration of the library.32if the moduleMBEDTLS_SHA512_Cis disabled at compile time.32ifMBEDTLS_ENTROPY_FORCE_SHA256is enabled at compile time.
Definition in file ctr_drbg.h.
Typedef Documentation
| typedef struct mbedtls_ctr_drbg_context mbedtls_ctr_drbg_context |
The CTR_DRBG context structure.
Function Documentation
| void mbedtls_ctr_drbg_free | ( | mbedtls_ctr_drbg_context * | ctx ) |
This function clears CTR_CRBG context data.
- Parameters:
-
ctx The CTR_DRBG context to clear.
Definition at line 129 of file ctr_drbg.c.
| 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().
- Parameters:
-
ctx The CTR_DRBG context to initialize.
Definition at line 56 of file ctr_drbg.c.
| 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.
- 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:
0on success.- MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Definition at line 544 of file ctr_drbg.c.
| 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.
- 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 ofadd_len.add_len The length of the additional data if additionalis notNULL. This must be less than MBEDTLS_CTR_DRBG_MAX_INPUT and less than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT -entropy_lenwhereentropy_lenis the entropy length configured for the context.
- Returns:
0on success.- MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Definition at line 467 of file ctr_drbg.c.
| 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.
- 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_lenwhereentropy_lenis the entropy length configured for the context.
- Returns:
0on success.- MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Definition at line 397 of file ctr_drbg.c.
| 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_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).
f_entropy is always called with a buffer size equal to the entropy length. The entropy length is initially MBEDTLS_CTR_DRBG_ENTROPY_LEN and this value is always used for the initial seeding. You can change the entropy length for subsequent seeding by calling mbedtls_ctr_drbg_set_entropy_len() after this function.
You can provide a personalization string in addition to the entropy source, to make this instantiation as unique as possible.
- Note:
- 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 string obtained from calling
f_entropyand thecustomstring. The origin of the nonce depends on the value of the entropy length relative to the security strength.- If the entropy length is at least 1.5 times the security strength then the nonce is taken from the string obtained with
f_entropy. - If the entropy length is less than the security strength, then the nonce is taken from
custom. In this case, for compliance with SP 800-90A, you must pass a unique value ofcustomat each invocation. See SP 800-90A §8.6.7 for more details.
- If the entropy length is at least 1.5 times the security strength then the nonce is taken from the string obtained with
- Warning:
- When MBEDTLS_CTR_DRBG_ENTROPY_LEN is less than MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2, to achieve the maximum security strength permitted by CTR_DRBG, you must pass a value of
customthat is a nonce: this value must never be repeated in subsequent runs of the same application or on a different device.
- Parameters:
-
ctx The CTR_DRBG context to seed. f_entropy The entropy callback, taking as arguments the p_entropycontext, the buffer to fill, and the length of the buffer.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_CTR_DRBG_MAX_SEED_INPUT - MBEDTLS_CTR_DRBG_ENTROPY_LEN.
- Returns:
0on success.- MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Definition at line 118 of file ctr_drbg.c.
| int mbedtls_ctr_drbg_self_test | ( | int | verbose ) |
The CTR_DRBG checkup routine.
- Returns:
0on success.-
1on failure.
Definition at line 697 of file ctr_drbg.c.
| 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 subsequent reseed.
The default value is MBEDTLS_CTR_DRBG_ENTROPY_LEN.
- Note:
- mbedtls_ctr_drbg_seed() always sets the entropy length to MBEDTLS_CTR_DRBG_ENTROPY_LEN, so this function only has an effect when it is called after mbedtls_ctr_drbg_seed().
-
The security strength of CTR_DRBG is bounded by the entropy length. Thus:
- When using AES-256 (
MBEDTLS_CTR_DRBG_USE_128_BIT_KEYis disabled, which is the default),lenmust be at least 32 (in bytes) to achieve a 256-bit strength. - When using AES-128 (
MBEDTLS_CTR_DRBG_USE_128_BIT_KEYis enabled)lenmust be at least 16 (in bytes) to achieve a 128-bit strength.
- When using AES-256 (
- 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.
Definition at line 147 of file ctr_drbg.c.
| 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.
Definition at line 141 of file ctr_drbg.c.
| 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.
Definition at line 153 of file ctr_drbg.c.
| MBEDTLS_DEPRECATED void 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:
- If
add_lenis greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used. The remaining Bytes are silently discarded.
- Parameters:
-
ctx The CTR_DRBG context. additional The data to update the state with. add_len Length of additionaldata.
Definition at line 373 of file ctr_drbg.c.
| int mbedtls_ctr_drbg_update_ret | ( | mbedtls_ctr_drbg_context * | ctx, |
| const unsigned char * | additional, | ||
| size_t | add_len | ||
| ) |
This function updates the state of the CTR_DRBG context.
- Parameters:
-
ctx The CTR_DRBG context. additional The data to update the state with. This must not be NULLunlessadd_lenis0.add_len Length of additionalin bytes. This must be at most MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
- Returns:
0on success.-
MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
add_lenis more than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. - An error from the underlying AES cipher on failure.
Definition at line 352 of file ctr_drbg.c.
| 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:
0on 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.
Definition at line 597 of file ctr_drbg.c.
| 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:
0on success.- MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
- MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed failure.
Definition at line 566 of file ctr_drbg.c.
Generated on Tue Jul 12 2022 13:55:06 by
1.7.2