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.

include/mbedtls/ctr_drbg.h

@@ -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
+ * A typical choice for the \p f_entropy and \p p_entropy parameters is
- *       entropy source, to make this instantiation as unique as possible.
+ * 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.