From dd5b67b4f4c0ce60e391f7ccf8a385143f5a4e7c Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 3 Oct 2019 14:20:46 +0200
Subject: [PATCH] CTR_DRBG: more consistent formatting and wording

In particular, don't use #MBEDTLS_xxx on macros that are undefined in
some configurations, since this would be typeset with a literal '#'.
---
 include/mbedtls/ctr_drbg.h | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index e62f115c1..c06241afa 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -12,26 +12,26 @@
  * The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128
  * as the underlying block cipher, with a derivation function. The security
  * strength is:
+ * (if \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time)
  * - 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.
+ *   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)
+ * - 128 bits if AES-128 is used (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled)
  *   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`).
+ *   in config.h).
  *
  * Note that the value of #MBEDTLS_CTR_DRBG_ENTROPY_LEN defaults to:
- * - \c 48 if the module #MBEDTLS_SHA512_C is enabled and the symbol
- *   #MBEDTLS_ENTROPY_FORCE_SHA256 is not enabled at compile time.
+ * - \c 48 if the module \c MBEDTLS_SHA512_C is enabled and the symbol
+ *   \c MBEDTLS_ENTROPY_FORCE_SHA256 is disabled at compile time.
  *   This is the default configuration of the library.
- * - \c 32 if the module #MBEDTLS_SHA512_C is disabled at compile time.
- * - \c 32 if #MBEDTLS_ENTROPY_FORCE_SHA256 is enabled at compile time.
+ * - \c 32 if the module \c MBEDTLS_SHA512_C is disabled at compile time.
+ * - \c 32 if \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled at compile time.
  */
 /*
  *  Copyright (C) 2006-2019, Arm Limited (or its affiliates), All Rights Reserved
@@ -79,14 +79,14 @@
 /**< The key size in bytes used by the cipher.
  *
  * Compile-time choice: 16 bytes (128 bits)
- * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is set.
+ * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled.
  */
 #else
 #define MBEDTLS_CTR_DRBG_KEYSIZE            32
 /**< The key size in bytes used by the cipher.
  *
  * Compile-time choice: 32 bytes (256 bits)
- * because `MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` is not set.
+ * because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.
  */
 #endif
 
@@ -107,10 +107,10 @@
 /** The amount of entropy used per seed by default.
  *
  * This is 48 bytes because the entropy module uses SHA-512
- * #MBEDTLS_ENTROPY_FORCE_SHA256 is not set).
  *
  * \note See mbedtls_ctr_drbg_set_entropy_len() regarding what values are
  *       acceptable.
+ * (\c MBEDTLS_ENTROPY_FORCE_SHA256 is disabled).
  */
 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        48
 #else