mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-12-24 00:45:32 +00:00
CTR_DRBG: Document the security strength and SP 800-90A compliance
Document that a derivation function is used. Document the security strength of the DRBG depending on the compile-time configuration and how it is set up. In particular, document how the nonce specified in SP 800-90A is set. Mention how to link the ctr_drbg module with the entropy module.
This commit is contained in:
parent
c1c9292d2f
commit
e3dc5942c5
|
@ -9,9 +9,22 @@
|
|||
* Bit Generators</em>.
|
||||
*
|
||||
* The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128
|
||||
* as the underlying block cipher.
|
||||
* as the underlying block cipher, with a derivation function. The security
|
||||
* strength is:
|
||||
* - 256 bits under the default configuration of the library, with AES-256
|
||||
* (`MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` not set) 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
|
||||
* - 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_KEY` set)
|
||||
* 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`).
|
||||
*
|
||||
* \warning Using 128-bit keys for CTR_DRBG limits the security of generated
|
||||
* \warning Using 128-bit keys for CTR_DRBG or using SHA-256 as the entropy
|
||||
* compression function limits the security of generated
|
||||
* keys and operations that use random values generated to 128-bit security.
|
||||
*/
|
||||
/*
|
||||
|
@ -182,9 +195,36 @@ void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
|
|||
* \brief This function seeds and sets up the CTR_DRBG
|
||||
* entropy source for future reseeds.
|
||||
*
|
||||
* \note Personalization data can be provided in addition to the more generic
|
||||
* A typical choice for the \p f_entropy and \p p_entropy parameters is
|
||||
* to use the entropy module:
|
||||
* - \p f_entropy is mbedtls_entropy_func();
|
||||
* - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
|
||||
* with mbedtls_entropy_init() (which registers the platform's default
|
||||
* entropy sources).
|
||||
*
|
||||
* Personalization data can be provided in addition to the more generic
|
||||
* 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 \p f_entropy and the \p custom string.
|
||||
* The origin of the nonce depends on the value of
|
||||
* the entropy length relative to the security strength.
|
||||
* See the documentation of
|
||||
* mbedtls_ctr_drbg_set_entropy_len() for information
|
||||
* about the entropy length.
|
||||
* - If the entropy length is at least 1.5 times the
|
||||
* security strength then the nonce is taken from the
|
||||
* string obtained with \p f_entropy.
|
||||
* - If the entropy length is less than the security
|
||||
* strength, then the nonce is taken from \p custom.
|
||||
* In this case, for compliance with SP 800-90A,
|
||||
* you must pass a unique value of \p custom at
|
||||
* each invocation. See SP 800-90A §8.6.7 for more
|
||||
* details.
|
||||
*
|
||||
* \param ctx The CTR_DRBG context to seed.
|
||||
* \param f_entropy The entropy callback, taking as arguments the
|
||||
* \p p_entropy context, the buffer to fill, and the
|
||||
|
@ -234,6 +274,13 @@ void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
|
|||
* seed or reseed. The default value is
|
||||
* #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
|
||||
*
|
||||
* \note For compliance with NIST SP 800-90A, the entropy length
|
||||
* must be at least 1.5 times security strength, since
|
||||
* the entropy source is used both as the entropy input
|
||||
* and to provide the initial nonce:
|
||||
* - 24 bytes if using AES-128;
|
||||
* - 48 bytes if using AES-256.
|
||||
*
|
||||
* \param ctx The CTR_DRBG context.
|
||||
* \param len The amount of entropy to grab, in bytes.
|
||||
* This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
|
||||
|
|
Loading…
Reference in a new issue