From 80f679b93864274c31e1a06fce734a4f61f9da62 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 1 Jun 2018 17:55:41 +0200 Subject: [PATCH 1/2] Correct and clarify the documentation of GCM whole-message functions Clarify the roles of the buffer parameter and their sizes. Remove a statement about input size restrictions that only applies to mbedtls_gcm_update, not to the whole-message functions. Document the possible error codes. Warn that mbedtls_gcm_crypt_and_tag in decrypt mode does not authenticate the data and recommend using mbedtls_gcm_auth_decrypt instead. --- include/mbedtls/gcm.h | 46 ++++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h index bec557714..a9bc441c6 100644 --- a/include/mbedtls/gcm.h +++ b/include/mbedtls/gcm.h @@ -113,21 +113,35 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, * the same as input buffer. If the buffers overlap, the output * buffer must trail at least 8 Bytes behind the input buffer. * + * \warning When this function performs a decryption, it outputs the + * authentication tag and does not verify that the data is + * authentic. You should use this function to perform encryption + * only. For decryption, use mbedtls_gcm_auth_decrypt() instead. + * * \param ctx The GCM context to use for encryption or decryption. * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or - * #MBEDTLS_GCM_DECRYPT. - * \param length The length of the input data. This must be a multiple of - * 16 except in the last call before mbedtls_gcm_finish(). + * #MBEDTLS_GCM_DECRYPT. Note that during decryption, the + * tag is not verified. You should use this function only + * to encrypt data, and use mbedtls_gcm_auth_decrypt() + * to decrypt. + * \param length The length of the input data, which is equal to the length + * of the output data. * \param iv The initialization vector. * \param iv_len The length of the IV. * \param add The buffer holding the additional data. * \param add_len The length of the additional data. - * \param input The buffer holding the input data. - * \param output The buffer for holding the output data. + * \param input The buffer holding the input data. Its size is \b length. + * \param output The buffer for holding the output data. It must have room + * for \b length bytes. * \param tag_len The length of the tag to generate. * \param tag The buffer for holding the tag. * - * \return \c 0 on success. + * \return \c 0 if the encryption or decryption was performed + * successfully. Note that in #MBEDTLS_GCM_DECRYPT mode, + * this does not indicate that the data is authentic. + * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid. + * \return #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific + * error code if the encryption or decryption failed. */ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, int mode, @@ -150,19 +164,23 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, * must trail at least 8 Bytes behind the input buffer. * * \param ctx The GCM context. - * \param length The length of the input data. This must be a multiple - * of 16 except in the last call before mbedtls_gcm_finish(). + * \param length The length of the ciphertext to decrypt, which is also + * the length of the decrypted plaintext. * \param iv The initialization vector. * \param iv_len The length of the IV. * \param add The buffer holding the additional data. * \param add_len The length of the additional data. - * \param tag The buffer holding the tag. - * \param tag_len The length of the tag. - * \param input The buffer holding the input data. - * \param output The buffer for holding the output data. + * \param tag The buffer holding the tag to verify. + * \param tag_len The length of the tag to verify. + * \param input The buffer holding the ciphertext. Its size is \b length. + * \param output The buffer for holding the decrypted plaintext. It must + * have room for \b length bytes. * - * \return 0 if successful and authenticated. - * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match. + * \return \c 0 if successful and authenticated. + * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match. + * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid. + * \return #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific + * error code if the decryption failed. */ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, size_t length, From 0a0e08a618d5897b2544066e0d937aa710318e43 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Jun 2018 14:46:02 +0200 Subject: [PATCH 2/2] mbedtls_gcm_crypt_and_tag: clarify what each mode does and doesn't do --- include/mbedtls/gcm.h | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h index a9bc441c6..87535ab95 100644 --- a/include/mbedtls/gcm.h +++ b/include/mbedtls/gcm.h @@ -119,11 +119,17 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, * only. For decryption, use mbedtls_gcm_auth_decrypt() instead. * * \param ctx The GCM context to use for encryption or decryption. - * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or - * #MBEDTLS_GCM_DECRYPT. Note that during decryption, the - * tag is not verified. You should use this function only - * to encrypt data, and use mbedtls_gcm_auth_decrypt() - * to decrypt. + * \param mode The operation to perform: + * - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption. + * The ciphertext is written to \p output and the + * authentication tag is written to \p tag. + * - #MBEDTLS_GCM_DECRYPT to perform decryption. + * The plaintext is written to \p output and the + * authentication tag is written to \p tag. + * Note that this mode is not recommended, because it does + * not verify the authenticity of the data. For this reason, + * you should use mbedtls_gcm_auth_decrypt() instead of + * calling this function in decryption mode. * \param length The length of the input data, which is equal to the length * of the output data. * \param iv The initialization vector.