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.
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 58b9a65..05a2aba 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -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,8 +195,35 @@
* \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
@@ -234,6 +274,13 @@
* 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.