ReactOS 0.4.16-dev-306-g647d351
|
This file contains definitions and functions for the CTR_DRBG pseudorandom generator. More...
Go to the source code of this file.
Classes | |
struct | mbedtls_ctr_drbg_context |
The CTR_DRBG context structure. 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 using the compiler command line. | |
#define | MBEDTLS_CTR_DRBG_ENTROPY_LEN 32 |
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 |
#define | MBEDTLS_CTR_DRBG_PR_OFF 0 |
#define | MBEDTLS_CTR_DRBG_PR_ON 1 |
#define | MBEDTLS_DEPRECATED |
typedef struct mbedtls_ctr_drbg_context | mbedtls_ctr_drbg_context |
The CTR_DRBG context structure. | |
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. | |
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_seed_entropy_len (mbedtls_ctr_drbg_context *, int(*)(void *, unsigned char *, size_t), void *, const unsigned char *, size_t, size_t) |
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:
custom
parameter to mbedtls_ctr_drbg_seed().MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
enabled) 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:
48
if the module MBEDTLS_SHA512_C
is enabled and the symbol MBEDTLS_ENTROPY_FORCE_SHA256
is disabled at compile time. This is the default configuration of the library.32
if the module MBEDTLS_SHA512_C
is disabled at compile time.32
if MBEDTLS_ENTROPY_FORCE_SHA256
is enabled at compile time. Definition in file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 |
The block size used by the cipher.
Definition at line 104 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32 |
The amount of entropy used per seed by default, in bytes.
This is 32 bytes because the entropy module uses SHA-256 (the SHA512 module is disabled or MBEDTLS_ENTROPY_FORCE_SHA256
is enabled).
Definition at line 156 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) |
The key size for the DRBG operation, in bits.
Definition at line 122 of file ctr_drbg.h.
#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 119 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_MAX_INPUT 256 |
The maximum number of additional input Bytes.
Definition at line 167 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024 |
The maximum number of requested Bytes per call.
Definition at line 172 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384 |
The maximum size of seed or reseed buffer in bytes.
Definition at line 177 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_PR_OFF 0 |
Prediction resistance is disabled.
Definition at line 183 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_PR_ON 1 |
Prediction resistance is enabled.
Definition at line 185 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000 |
The interval before reseed is performed by default.
Definition at line 162 of file ctr_drbg.h.
#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) |
The seed length, calculated as (counter + AES key).
Definition at line 123 of file ctr_drbg.h.
#define MBEDTLS_DEPRECATED |
Definition at line 508 of file ctr_drbg.h.
#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 |
The entropy source failed.
Definition at line 99 of file ctr_drbg.h.
#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A |
Read or write error in file.
Definition at line 102 of file ctr_drbg.h.
#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 |
The input (entropy + additional data) is too large.
Definition at line 101 of file ctr_drbg.h.
#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 |
The requested random buffer length is too big.
Definition at line 100 of file ctr_drbg.h.
The CTR_DRBG context structure.
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().
ctx | The CTR_DRBG context to clear. |
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().
ctx | The CTR_DRBG context to initialize. |
This function uses CTR_DRBG to generate random data.
This function automatically reseeds if the reseed counter is exceeded or prediction resistance is enabled.
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. |
0
on success. 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.
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. |
0
on success. 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.
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. |
0
on success. 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().
You can provide a personalization string in addition to the entropy source, to make this instantiation as unique as possible.
f_entropy
and the custom
string. The origin of the nonce depends on the value of the entropy length relative to the security strength.f_entropy
.custom
. In this case, for compliance with SP 800-90A, you must pass a unique value of custom
at each invocation. See SP 800-90A §8.6.7 for more details. custom
that is a nonce: this value must never be repeated in subsequent runs of the same application or on a different device. 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 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 |
0
on success. 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 | |||
) |
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.
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.MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
is enabled) len
must be at least 16 (in bytes) to achieve a 128-bit strength.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. |
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.
ctx | The 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 | ||
) |
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.
ctx | The CTR_DRBG context. |
interval | The reseed interval. |
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.
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 Bytes are silently discarded.ctx | The CTR_DRBG context. |
additional | The data to update the state with. |
add_len | Length of additional data. |
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.
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. |
0
on success. add_len
is more than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.