block ciphers: improve CTR nonce warning
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index 46016dc..27be761 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -300,7 +300,24 @@
* 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.
diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h
index 67c747e..5724308 100644
--- a/include/mbedtls/aria.h
+++ b/include/mbedtls/aria.h
@@ -242,7 +242,24 @@
* 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.
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index c0ef5a0..4b4916e 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -170,7 +170,24 @@
/**
* \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
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index cf07629..1b138fc 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -183,12 +183,29 @@
/**
* \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