Merge pull request #5270 from davidhorstmann-arm/improve-cmac-docs
Reword documentation of CMAC operations
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 3e599b9..21ce882 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -67,9 +67,17 @@
#endif /* !MBEDTLS_CMAC_ALT */
/**
- * \brief This function sets the CMAC key, and prepares to authenticate
+ * \brief This function starts a new CMAC computation
+ * by setting the CMAC key, and preparing to authenticate
* the input data.
- * Must be called with an initialized cipher context.
+ * It must be called with an initialized cipher context.
+ *
+ * Once this function has completed, data can be supplied
+ * to the CMAC computation by calling
+ * mbedtls_cipher_cmac_update().
+ *
+ * To start a CMAC computation using the same key as a previous
+ * CMAC computation, use mbedtls_cipher_cmac_finish().
*
* \note When the CMAC implementation is supplied by an alternate
* implementation (through #MBEDTLS_CMAC_ALT), some ciphers
@@ -95,9 +103,15 @@
* \brief This function feeds an input buffer into an ongoing CMAC
* computation.
*
- * It is called between mbedtls_cipher_cmac_starts() or
- * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
- * Can be called repeatedly.
+ * The CMAC computation must have previously been started
+ * by calling mbedtls_cipher_cmac_starts() or
+ * mbedtls_cipher_cmac_reset().
+ *
+ * Call this function as many times as needed to input the
+ * data to be authenticated.
+ * Once all of the required data has been input,
+ * call mbedtls_cipher_cmac_finish() to obtain the result
+ * of the CMAC operation.
*
* \param ctx The cipher context used for the CMAC operation.
* \param input The buffer holding the input data.
@@ -111,12 +125,13 @@
const unsigned char *input, size_t ilen );
/**
- * \brief This function finishes the CMAC operation, and writes
- * the result to the output buffer.
+ * \brief This function finishes an ongoing CMAC operation, and
+ * writes the result to the output buffer.
*
- * It is called after mbedtls_cipher_cmac_update().
- * It can be followed by mbedtls_cipher_cmac_reset() and
- * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
+ * It should be followed either by
+ * mbedtls_cipher_cmac_reset(), which starts another CMAC
+ * operation with the same key, or mbedtls_cipher_free(),
+ * which clears the cipher context.
*
* \param ctx The cipher context used for the CMAC operation.
* \param output The output buffer for the CMAC checksum result.
@@ -129,12 +144,14 @@
unsigned char *output );
/**
- * \brief This function prepares the authentication of another
- * message with the same key as the previous CMAC
- * operation.
+ * \brief This function starts a new CMAC operation with the same
+ * key as the previous one.
*
- * It is called after mbedtls_cipher_cmac_finish()
- * and before mbedtls_cipher_cmac_update().
+ * It should be called after finishing the previous CMAC
+ * operation with mbedtls_cipher_cmac_finish().
+ * After calling this function,
+ * call mbedtls_cipher_cmac_update() to supply the new
+ * CMAC operation with data.
*
* \param ctx The cipher context used for the CMAC operation.
*
