Update gcm.h
Minor documentation improvements:
*Standardized file brief description.
*Separated return statements.
*Reordered tags within documentation blocks so that params and returns are last in block.
*Suggest to specify issue for each return code, where multiple failure return codes are listed.
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 1e5a507..88408c2 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,9 +1,11 @@
/**
* \file gcm.h
*
- * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
- * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
- * (GCM), Natl. Inst. Stand. Technol.</em>
+ * \brief This file contains GCM definitions and functions.
+ *
+ * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
+ * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
+ * (GCM), Natl. Inst. Stand. Technol.</em>
*
* For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
* Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
@@ -91,7 +93,8 @@
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \return \c 0 on success, or a cipher specific error code.
+ * \return \c 0 on success.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
mbedtls_cipher_id_t cipher,
@@ -101,15 +104,16 @@
/**
* \brief This function performs GCM encryption or decryption of a buffer.
*
- * \note For encryption, the output buffer can be the same as the input buffer.
- * For decryption, the output buffer cannot be the same as input buffer.
- * If the buffers overlap, the output buffer must trail at least 8 Bytes
- * behind the input buffer.
+ * \note For encryption, the output buffer can be the same as the
+ * input buffer. For decryption, the output buffer cannot be
+ * the same as input buffer. If the buffers overlap, the output
+ * buffer must trail at least 8 Bytes behind the input buffer.
*
* \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().
+ * \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 iv The initialization vector.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data.
@@ -137,12 +141,13 @@
* \brief This function performs a GCM authenticated decryption of a
* buffer.
*
- * \note For decryption, the output buffer cannot be the same as input buffer.
- * If the buffers overlap, the output buffer must trail at least 8 Bytes
- * behind the input buffer.
+ * \note For decryption, the output buffer cannot be the same as
+ * input buffer. If the buffers overlap, the output buffer
+ * 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 input data. This must be a multiple
+ * of 16 except in the last call before mbedtls_gcm_finish().
* \param iv The initialization vector.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data.
@@ -152,8 +157,8 @@
* \param input The buffer holding the input data.
* \param output The buffer for holding the output data.
*
- * \return 0 if successful and authenticated, or
- * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
+ * \return 0 if successful and authenticated.
+ * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
*/
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length,
@@ -175,10 +180,12 @@
* #MBEDTLS_GCM_DECRYPT.
* \param iv The initialization vector.
* \param iv_len The length of the IV.
- * \param add The buffer holding the additional data, or NULL if \p add_len is 0.
- * \param add_len The length of the additional data. If 0, \p add is NULL.
+ * \param add The buffer holding the additional data, or NULL
+ * if \p add_len is 0.
+ * \param add_len The length of the additional data. If 0,
+ * \p add is NULL.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
int mode,
@@ -195,16 +202,18 @@
* Bytes. Only the last call before calling
* mbedtls_gcm_finish() can be less than 16 Bytes.
*
- * \note For decryption, the output buffer cannot be the same as input buffer.
- * If the buffers overlap, the output buffer must trail at least 8 Bytes
- * behind the input buffer.
+ * \note For decryption, the output buffer cannot be the same as
+ * input buffer. If the buffers overlap, the output buffer
+ * 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 input data. This must be a multiple of
+ * 16 except in the last call before mbedtls_gcm_finish().
* \param input The buffer holding the input data.
* \param output The buffer for holding the output data.
*
- * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/
int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
size_t length,
@@ -222,7 +231,8 @@
* \param tag The buffer for holding the tag.
* \param tag_len The length of the tag to generate. Must be at least four.
*
- * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/
int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
unsigned char *tag,
@@ -251,7 +261,8 @@
/**
* \brief The GCM checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_gcm_self_test( int verbose );