Improve CMAC documentation
- Rephrase file/function/parameter/enum/define/error descriptions into full
and clear sentences.
- Make sure to adhere to the Arm writing guidelines.
- Fix missing/incorrect Doxygen tags.
- Standardize terminology used within the file.
GitHub PR: #1315
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 1cac948..628c9da 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,11 +1,11 @@
/**
* \file cmac.h
*
- * \brief Cipher-based Message Authentication Code (CMAC) Mode for
- * Authentication
+ * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
+ * Authentication.
*/
/*
- * Copyright (C) 2015-2016, ARM Limited, All Rights Reserved
+ * Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -20,8 +20,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
- * This file is part of mbed TLS (https://tls.mbed.org)
+ * This file is part of Mbed TLS (https://tls.mbed.org)
*/
+
#ifndef MBEDTLS_CMAC_H
#define MBEDTLS_CMAC_H
@@ -31,110 +32,125 @@
extern "C" {
#endif
-#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */
+#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */
#define MBEDTLS_AES_BLOCK_SIZE 16
#define MBEDTLS_DES3_BLOCK_SIZE 8
#if defined(MBEDTLS_AES_C)
-#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* longest used by CMAC is AES */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* The longest block used by CMAC is that of AES. */
#else
-#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* longest used by CMAC is 3DES */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* The longest block used by CMAC is that of 3DES. */
#endif
#if !defined(MBEDTLS_CMAC_ALT)
/**
- * CMAC context structure - Contains internal state information only
+ * The CMAC context structure.
*/
struct mbedtls_cmac_context_t
{
- /** Internal state of the CMAC algorithm */
+ /** The internal state of the CMAC algorithm. */
unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX];
/** Unprocessed data - either data that was not block aligned and is still
- * pending to be processed, or the final block */
+ * pending processing, or the final block. */
unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
- /** Length of data pending to be processed */
+ /** The length of data pending processing. */
size_t unprocessed_len;
};
/**
- * \brief Set the CMAC key and prepare to authenticate the input
- * data.
- * Should be called with an initialized cipher context.
+ * \brief This function sets the CMAC key, and prepares to authenticate
+ * the input data.
+ * Must be called with an initialized cipher context.
*
- * \param ctx Cipher context. This should be a cipher context,
- * initialized to be one of the following types:
- * MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB,
- * MBEDTLS_CIPHER_AES_256_ECB or
- * MBEDTLS_CIPHER_DES_EDE3_ECB.
- * \param key CMAC key
- * \param keybits length of the CMAC key in bits
- * (must be acceptable by the cipher)
+ * \param ctx The cipher context used for the CMAC operation, initialized
+ * as one of the following types:<ul>
+ * <li>MBEDTLS_CIPHER_AES_128_ECB</li>
+ * <li>MBEDTLS_CIPHER_AES_192_ECB</li>
+ * <li>MBEDTLS_CIPHER_AES_256_ECB</li>
+ * <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
+ * \param key The CMAC key.
+ * \param keybits The length of the CMAC key in bits.
+ * Must be supported by the cipher.
*
- * \return 0 if successful, or a cipher specific error code
+ * \return \c 0 on success, or a cipher-specific error code.
*/
int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
const unsigned char *key, size_t keybits );
/**
- * \brief Generic CMAC process buffer.
- * Called between mbedtls_cipher_cmac_starts() or
- * mbedtls_cipher_cmac_reset() and
- * mbedtls_cipher_cmac_finish().
- * May be called repeatedly.
+ * \brief This function feeds an input buffer into an ongoing CMAC
+ * computation.
*
- * \param ctx CMAC context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * It is called between mbedtls_cipher_cmac_starts() or
+ * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
+ * Can be called repeatedly.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The cipher context used for the CMAC operation.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
const unsigned char *input, size_t ilen );
/**
- * \brief Output CMAC.
- * Called after mbedtls_cipher_cmac_update().
- * Usually followed by mbedtls_cipher_cmac_reset(), then
- * mbedtls_cipher_cmac_starts(), or mbedtls_cipher_free().
+ * \brief This function finishes the CMAC operation, and writes
+ * the result to the output buffer.
*
- * \param ctx CMAC context
- * \param output Generic CMAC checksum result
+ * 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().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The cipher context used for the CMAC operation.
+ * \param output The output buffer for the CMAC checksum result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output );
/**
- * \brief Prepare to authenticate a new message with the same key.
- * Called after mbedtls_cipher_cmac_finish() and before
- * mbedtls_cipher_cmac_update().
+ * \brief This function prepares the authentication of another
+ * message with the same key as the previous CMAC
+ * operation.
*
- * \param ctx CMAC context to be reset
+ * It is called after mbedtls_cipher_cmac_finish()
+ * and before mbedtls_cipher_cmac_update().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The cipher context used for the CMAC operation.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
/**
- * \brief Output = Generic_CMAC( cmac key, input buffer )
+ * \brief This function calculates the full generic CMAC
+ * on the input buffer with the provided key.
*
- * \param cipher_info message digest info
- * \param key CMAC key
- * \param keylen length of the CMAC key in bits
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output Generic CMAC-result
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * The CMAC result is calculated as
+ * output = generic CMAC(cmac key, input buffer).
+ *
+ *
+ * \param cipher_info The cipher information.
+ * \param key The CMAC key.
+ * \param keylen The length of the CMAC key in bits.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the generic CMAC result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
const unsigned char *key, size_t keylen,
@@ -143,16 +159,21 @@
#if defined(MBEDTLS_AES_C)
/**
- * \brief AES-CMAC-128-PRF
- * Implementation of (AES-CMAC-PRF-128), as defined in RFC 4615
+ * \brief This function implements the AES-CMAC-PRF-128 pseudorandom
+ * function, as defined in
+ * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
+ * Message Authentication Code-Pseudo-Random Function-128
+ * (AES-CMAC-PRF-128) Algorithm for the Internet Key
+ * Exchange Protocol (IKE).</em>
*
- * \param key PRF key
- * \param key_len PRF key length in bytes
- * \param input buffer holding the input data
- * \param in_len length of the input data in bytes
- * \param output buffer holding the generated pseudorandom output (16 bytes)
+ * \param key The key to use.
+ * \param key_len The key length in Bytes.
+ * \param input The buffer holding the input data.
+ * \param in_len The length of the input data in Bytes.
+ * \param output The buffer holding the generated 16 Bytes of
+ * pseudorandom output.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
const unsigned char *input, size_t in_len,
@@ -173,9 +194,9 @@
#if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
/**
- * \brief Checkup routine
+ * \brief The CMAC checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_cmac_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */