From 6fdf0b3a47d53dc58343a136a33ba097a99ef1e8 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Wed, 25 Sep 2019 20:22:40 +0200
Subject: [PATCH] CTR_DRBG: improve the discussion of entropy length vs
 strength

---
 include/mbedtls/ctr_drbg.h | 33 ++++++++++++++++++++++++---------
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 1a9f5e80f..8d8882ac4 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -24,10 +24,6 @@
  *   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 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.
  */
 /*
  *  Copyright (C) 2006-2019, Arm Limited (or its affiliates), All Rights Reserved
@@ -278,11 +274,30 @@ void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
  *                      #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.
+ *                      (\p len bytes = \p len * 8 bits)
+ *                      must be at least the security strength.
+ *                      Furthermore, if the entropy input is used to provide
+ *                      the nonce, the entropy length must be 1.5 times
+ *                      the security strength.
+ *                      Per NIST SP 800-57A table 2, the achievable security
+ *                      strength is 128 bits if using AES-128 and
+ *                      256 bits if using AES-256.
+ *                      Therefore, to provide full security,
+ *                      the entropy input must be at least:
+ *                      - 24 bytes if using AES-128 and the \p custom
+ *                        argument to mbedtls_ctr_drbg_seed() may repeat
+ *                        (for example because it is empty, or more generally
+ *                        constant);
+ *                      - 48 bytes if using AES-256 and the \p custom
+ *                        argument to mbedtls_ctr_drbg_seed() may repeat
+ *                        (for example because it is empty, or more generally
+ *                        constant);
+ *                      - 16 bytes if using AES-128 and the \p custom
+ *                        argument to mbedtls_ctr_drbg_seed() includes
+ *                        a nonce;
+ *                      - 32 bytes if using AES-256 and the \p custom
+ *                        argument to mbedtls_ctr_drbg_seed() includes
+ *                        a nonce.
  *
  * \param ctx           The CTR_DRBG context.
  * \param len           The amount of entropy to grab, in bytes.