From 4ee9d24c904cab2c3540bf9f240efe768bd11703 Mon Sep 17 00:00:00 2001
From: Rose Zadik <rose.zadik@arm.com>
Date: Mon, 26 Mar 2018 17:18:44 +0100
Subject: [PATCH 1/5] 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.
---
 include/mbedtls/ccm.h | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 630b7fdf6..93ec157d8 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 @@ void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
  * \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 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
 /**
  * \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 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
  * \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 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
  * \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 @@ extern "C" {
 /**
  * \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 */

From bd9571a01eb29d2be7dab23925de213021f21d0a Mon Sep 17 00:00:00 2001
From: Rose Zadik <rose.zadik@arm.com>
Date: Mon, 16 Apr 2018 09:45:12 +0100
Subject: [PATCH 2/5] Update ccm.h

minor changes based on comments
---
 include/mbedtls/ccm.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 93ec157d8..f354ef9fb 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -118,6 +118,7 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
  * \return          \c 0 on success.
+ * \return          A cipher-specific error code on failure.
  */
 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
                          const unsigned char *iv, size_t iv_len,
@@ -143,8 +144,8 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
  * \param tag_len   The length of the tag in Bytes.
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
- * \return          0 if successful and authenticated.
- * \return          #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return          \c 0 on success.
+ * \return          A cipher-specific error code on failure.
  */
 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
                       const unsigned char *iv, size_t iv_len,

From ef8717984218f9a7d62f121ebb69b6c0219585b7 Mon Sep 17 00:00:00 2001
From: Rose Zadik <rose.zadik@arm.com>
Date: Tue, 17 Apr 2018 10:41:48 +0100
Subject: [PATCH 3/5] Update ccm.h

updated failure returns to "A CCM or cipher-specific error code on failure."
---
 include/mbedtls/ccm.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index f354ef9fb..8f252c4bd 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -78,7 +78,7 @@ void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
  * \param keybits   The key size in bits. This must be acceptable by the cipher.
  *
  * \return          \c 0 on success.
- * \return          A cipher-specific error code on failure.
+ * \return          A CCM or cipher-specific error code on failure.
  */
 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
                         mbedtls_cipher_id_t cipher,
@@ -118,7 +118,7 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
  * \return          \c 0 on success.
- * \return          A cipher-specific error code on failure.
+ * \return          A CCM or cipher-specific error code on failure.
  */
 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
                          const unsigned char *iv, size_t iv_len,
@@ -145,7 +145,7 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
  * \return          \c 0 on success.
- * \return          A cipher-specific error code on failure.
+ * \return          A CCM or cipher-specific error code on failure.
  */
 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
                       const unsigned char *iv, size_t iv_len,

From 477dce15bca9e4a20f9e06d4ad71a9a45fa6974f Mon Sep 17 00:00:00 2001
From: Rose Zadik <rose.zadik@arm.com>
Date: Tue, 17 Apr 2018 16:31:22 +0100
Subject: [PATCH 4/5] Update ccm.h

updated brief desc.
---
 include/mbedtls/ccm.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 8f252c4bd..40ee1b3c8 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,7 +1,8 @@
 /**
  * \file ccm.h
  *
- * \brief This file contains CCM definitions and functions.
+ * \brief This file provides an API for the CCM authenticated encryption
+ *        mode for block ciphers.
  *
  * CCM combines Counter mode encryption with CBC-MAC authentication
  * for 128-bit block ciphers.

From 379b95ca9b5ca518dcff2b9f0a69702a49c01269 Mon Sep 17 00:00:00 2001
From: Rose Zadik <rose.zadik@arm.com>
Date: Tue, 17 Apr 2018 16:43:00 +0100
Subject: [PATCH 5/5] Update ccm.h

Updated return values for mbedtls_ccm_auth_decrypt().
---
 include/mbedtls/ccm.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 40ee1b3c8..5a34f3a0a 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -145,8 +145,9 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
  * \param tag_len   The length of the tag in Bytes.
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
- * \return          \c 0 on success.
- * \return          A CCM or cipher-specific error code on failure.
+ * \return          \c 0 on success. This indicates that the message is authentic.
+ * \return          #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return          A cipher-specific error code on calculation failure.
  */
 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
                       const unsigned char *iv, size_t iv_len,