diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h index 46016dcb7..27be76168 100644 --- a/include/mbedtls/aes.h +++ b/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. diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h index 67c747ef7..572430860 100644 --- a/include/mbedtls/aria.h +++ b/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. diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h index c0ef5a04c..4b4916e03 100644 --- a/include/mbedtls/blowfish.h +++ b/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 diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h index cf07629d9..1b138fc9e 100644 --- a/include/mbedtls/camellia.h +++ b/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