AuroraMiddleware/mbedtls
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve CMAC documentation

Browse Source 
- 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
This commit is contained in:
Rose Zadik 2018-01-25 21:52:41 +00:00 committed by Jaeden Amero
parent 9ba6b621de
commit 380d05d7ff
1 changed files with 87 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
include/mbedtls/cmac.h
View File

@ -1,11 +1,11 @@
/** /**
* \file cmac.h * \file cmac.h
* *
* \brief Cipher-based Message Authentication Code (CMAC) Mode for * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
* Authentication * 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 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * 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 * See the License for the specific language governing permissions and
* limitations under the License. * 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 #ifndef MBEDTLS_CMAC_H
#define MBEDTLS_CMAC_H #define MBEDTLS_CMAC_H
@ -31,110 +32,125 @@
extern "C" { extern "C" {
#endif #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_AES_BLOCK_SIZE 16
#define MBEDTLS_DES3_BLOCK_SIZE 8 #define MBEDTLS_DES3_BLOCK_SIZE 8
#if defined(MBEDTLS_AES_C) #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 #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 #endif
#if !defined(MBEDTLS_CMAC_ALT) #if !defined(MBEDTLS_CMAC_ALT)
/** /**
* CMAC context structure - Contains internal state information only * The CMAC context structure.
*/ */
struct mbedtls_cmac_context_t 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]; unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX];
/** Unprocessed data - either data that was not block aligned and is still /** 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]; 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; size_t unprocessed_len;
}; };
/** /**
* \brief Set the CMAC key and prepare to authenticate the input * \brief This function sets the CMAC key, and prepares to authenticate
* data. * the input data.
* Should be called with an initialized cipher context. * Must be called with an initialized cipher context.
* *
* \param ctx Cipher context. This should be a cipher context, * \param ctx The cipher context used for the CMAC operation, initialized
* initialized to be one of the following types: * as one of the following types:<ul>
* MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB, * <li>MBEDTLS_CIPHER_AES_128_ECB</li>
* MBEDTLS_CIPHER_AES_256_ECB or * <li>MBEDTLS_CIPHER_AES_192_ECB</li>
* MBEDTLS_CIPHER_DES_EDE3_ECB. * <li>MBEDTLS_CIPHER_AES_256_ECB</li>
* \param key CMAC key * <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
* \param keybits length of the CMAC key in bits * \param key The CMAC key.
* (must be acceptable by the cipher) * \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, int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
const unsigned char *key, size_t keybits ); const unsigned char *key, size_t keybits );
/** /**
* \brief Generic CMAC process buffer. * \brief This function feeds an input buffer into an ongoing CMAC
* Called between mbedtls_cipher_cmac_starts() or * computation.
* mbedtls_cipher_cmac_reset() and
* mbedtls_cipher_cmac_finish().
* May be called repeatedly.
* *
* \param ctx CMAC context * It is called between mbedtls_cipher_cmac_starts() or
* \param input buffer holding the data * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
* \param ilen length of the input data * Can be called repeatedly.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The cipher context used for the CMAC operation.
* verification fails. * \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, int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
const unsigned char *input, size_t ilen ); const unsigned char *input, size_t ilen );
/** /**
* \brief Output CMAC. * \brief This function finishes the CMAC operation, and writes
* Called after mbedtls_cipher_cmac_update(). * the result to the output buffer.
* Usually followed by mbedtls_cipher_cmac_reset(), then
* mbedtls_cipher_cmac_starts(), or mbedtls_cipher_free().
* *
* \param ctx CMAC context * It is called after mbedtls_cipher_cmac_update().
* \param output Generic CMAC checksum result * 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 * \param ctx The cipher context used for the CMAC operation.
* verification fails. * \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, int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief Prepare to authenticate a new message with the same key. * \brief This function prepares the authentication of another
* Called after mbedtls_cipher_cmac_finish() and before * message with the same key as the previous CMAC
* mbedtls_cipher_cmac_update(). * 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 * \param ctx The cipher context used for the CMAC operation.
* verification fails. *
* \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 ); 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 * The function allocates the context, performs the
* \param key CMAC key * calculation, and frees the context.
* \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
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * The CMAC result is calculated as
* verification fails. * 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, int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
const unsigned char *key, size_t keylen, const unsigned char *key, size_t keylen,
@ -143,16 +159,21 @@ int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
#if defined(MBEDTLS_AES_C) #if defined(MBEDTLS_AES_C)
/** /**
* \brief AES-CMAC-128-PRF * \brief This function implements the AES-CMAC-PRF-128 pseudorandom
* Implementation of (AES-CMAC-PRF-128), as defined in RFC 4615 * 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 The key to use.
* \param key_len PRF key length in bytes * \param key_len The key length in Bytes.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param in_len length of the input data in bytes * \param in_len The length of the input data in Bytes.
* \param output buffer holding the generated pseudorandom output (16 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, int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
const unsigned char *input, size_t in_len, const unsigned char *input, size_t in_len,
@ -173,9 +194,9 @@ extern "C" {
#if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) ) #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 ); int mbedtls_cmac_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */ #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */