Update ccm.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.
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 630b7fd..93ec157 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,8 +1,10 @@
/**
* \file ccm.h
*
- * \brief CCM combines Counter mode encryption with CBC-MAC authentication
- * for 128-bit block ciphers.
+ * \brief This file contains CCM definitions and functions.
+ *
+ * CCM combines Counter mode encryption with CBC-MAC authentication
+ * for 128-bit block ciphers.
*
* Input to CCM includes the following elements:
* <ul><li>Payload - data that is both authenticated and encrypted.</li>
@@ -75,7 +77,8 @@
* \param key The encryption key.
* \param keybits The key size in bits. This must be acceptable by the cipher.
*
- * \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_ccm_setkey( mbedtls_ccm_context *ctx,
mbedtls_cipher_id_t cipher,
@@ -93,6 +96,13 @@
/**
* \brief This function encrypts a buffer using CCM.
*
+ *
+ * \note The tag is written to a separate buffer. To concatenate
+ * the \p tag with the \p output, as done in <em>RFC-3610:
+ * Counter with CBC-MAC (CCM)</em>, use
+ * \p tag = \p output + \p length, and make sure that the
+ * output buffer is at least \p length + \p tag_len wide.
+ *
* \param ctx The CCM context to use for encryption.
* \param length The length of the input data in Bytes.
* \param iv Initialization vector (nonce).
@@ -107,12 +117,6 @@
* \param tag_len The length of the tag to generate in Bytes:
* 4, 6, 8, 10, 12, 14 or 16.
*
- * \note The tag is written to a separate buffer. To concatenate
- * the \p tag with the \p output, as done in <em>RFC-3610:
- * Counter with CBC-MAC (CCM)</em>, use
- * \p tag = \p output + \p length, and make sure that the
- * output buffer is at least \p length + \p tag_len wide.
- *
* \return \c 0 on success.
*/
int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
@@ -139,8 +143,8 @@
* \param tag_len The length of the tag in Bytes.
* 4, 6, 8, 10, 12, 14 or 16.
*
- * \return 0 if successful and authenticated, or
- * #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return 0 if successful and authenticated.
+ * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
*/
int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
@@ -164,7 +168,8 @@
/**
* \brief The CCM checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_ccm_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */