AuroraMiddleware/mbedtls
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

CTR_DRBG: Document the security strength and SP 800-90A compliance

Browse Source 
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:
Gilles Peskine 2019-09-24 14:48:53 +02:00
parent 944bc587e8
commit 223deea86b
1 changed files with 53 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
include/mbedtls/ctr_drbg.h
View File

@ -9,9 +9,24 @@
* 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
* to 32 or more, and the DRBG is initialized with an explicit
* nonce in the \c custom parameter 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_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,8 +197,35 @@ 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
* entropy source, to make this instantiation as unique as possible.
* 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
@ -235,6 +277,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.