block ciphers: improve CTR nonce warning

include/mbedtls/aes.h

@@ -300,7 +300,24 @@ int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
  *             must use the context initialized with mbedtls_aes_setkey_enc()
  *             for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
  *
- * \warning    You must keep the maximum use of your counter in mind.
+ * \warning    You must never reuse a nonce value with the same key. Doing so
+ *             would void the encryption for the two messages encrypted with
+ *             the same nonce and key.
+ *
+ *             There are two common strategies for managing nonces with CTR:
+ *
+ *             1. Use a counter starting at 0 or a random value. With this
+ *             strategy, this function will increment the counter for you, so
+ *             you only need to preserve the \p nonce_counter buffer between
+ *             calls. With this strategy, you must not encrypt more than
+ *             2**128 blocks of data.
+ *             2. Use a randomly-generated \p nonce_counter for each call.
+ *             With this strategy, you need to ensure the nonce is generated
+ *             in an unbiased way and you must not encrypt more than 2**64
+ *             block of data.
+ *
+ *             Note that for both stategies, the limit is in number of blocks
+ *             and that an AES block is 16 bytes.
  *
  * \param ctx              The AES context to use for encryption or decryption.
  * \param length           The length of the input data.

include/mbedtls/aria.h

@@ -242,7 +242,24 @@ int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
  *             must use the context initialized with mbedtls_aes_setkey_enc()
  *             for both #MBEDTLS_ARIA_ENCRYPT and #MBEDTLS_ARIA_DECRYPT.
  *
- * \warning    You must keep the maximum use of your counter in mind.
+ * \warning    You must never reuse a nonce value with the same key. Doing so
+ *             would void the encryption for the two messages encrypted with
+ *             the same nonce and key.
+ *
+ *             There are two common strategies for managing nonces with CTR:
+ *
+ *             1. Use a counter starting at 0 or a random value. With this
+ *             strategy, this function will increment the counter for you, so
+ *             you only need to preserve the \p nonce_counter buffer between
+ *             calls. With this strategy, you must not encrypt more than
+ *             2**128 blocks of data.
+ *             2. Use a randomly-generated \p nonce_counter for each call.
+ *             With this strategy, you need to ensure the nonce is generated
+ *             in an unbiased way and you must not encrypt more than 2**64
+ *             block of data.
+ *
+ *             Note that for both stategies, the limit is in number of blocks
+ *             and that an ARIA block is 16 bytes.
  *
  * \param ctx              The ARIA context to use for encryption or decryption.
  * \param length           The length of the input data.

include/mbedtls/blowfish.h

@@ -170,7 +170,24 @@ int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx,
 /**
  * \brief               Blowfish-CTR buffer encryption/decryption
  *
- * Warning: You have to keep the maximum use of your counter in mind!
+ * \warning    You must never reuse a nonce value with the same key. Doing so
+ *             would void the encryption for the two messages encrypted with
+ *             the same nonce and key.
+ *
+ *             There are two common strategies for managing nonces with CTR:
+ *
+ *             1. Use a counter starting at 0 or a random value. With this
+ *             strategy, this function will increment the counter for you, so
+ *             you only need to preserve the \p nonce_counter buffer between
+ *             calls. With this strategy, you must not encrypt more than
+ *             2**64 blocks of data.
+ *             2. Use a randomly-generated \p nonce_counter for each call.
+ *             With this strategy, you need to ensure the nonce is generated
+ *             in an unbiased way and you must not encrypt more than 2**32
+ *             block of data.
+ *
+ *             Note that for both stategies, the limit is in number of blocks
+ *             and that a Blowfish block is 8 bytes.
  *
  * \param ctx           Blowfish context
  * \param length        The length of the data

include/mbedtls/camellia.h

@@ -183,12 +183,29 @@ int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
 /**
  * \brief               CAMELLIA-CTR buffer encryption/decryption
  *
- * Warning: You have to keep the maximum use of your counter in mind!
- *
  * Note: Due to the nature of CTR you should use the same key schedule for
  * both encryption and decryption. So a context initialized with
  * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and MBEDTLS_CAMELLIA_DECRYPT.
  *
+ * \warning    You must never reuse a nonce value with the same key. Doing so
+ *             would void the encryption for the two messages encrypted with
+ *             the same nonce and key.
+ *
+ *             There are two common strategies for managing nonces with CTR:
+ *
+ *             1. Use a counter starting at 0 or a random value. With this
+ *             strategy, this function will increment the counter for you, so
+ *             you only need to preserve the \p nonce_counter buffer between
+ *             calls. With this strategy, you must not encrypt more than
+ *             2**128 blocks of data.
+ *             2. Use a randomly-generated \p nonce_counter for each call.
+ *             With this strategy, you need to ensure the nonce is generated
+ *             in an unbiased way and you must not encrypt more than 2**64
+ *             block of data.
+ *
+ *             Note that for both stategies, the limit is in number of blocks
+ *             and that a CAMELLIA block is 16 bytes.
+ *
  * \param ctx           CAMELLIA context
  * \param length        The length of the data
  * \param nc_off        The offset in the current stream_block (for resuming