From 282bd24a44972ee9bcb3bbdf12887bc619e9ee34 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Fri, 1 Jun 2018 17:55:41 +0200
Subject: [PATCH] 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 | 44 +++++++++++++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 1e5a507a2..414738525 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -106,20 +106,35 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
  *       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,
@@ -142,18 +157,23 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
  *       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, or
- *                 #MBEDTLS_ERR_GCM_AUTH_FAILED if 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,