TeamHepta/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2026-04-05 12:06:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5281 from davidhorstmann-arm/2.16-improve-cmac-docs

Browse Source 
Backport 2.16: Reword documentation of CMAC operations
This commit is contained in:
Gilles Peskine
2021-12-09 23:28:42 +01:00
committed by GitHub
parent 286bd2427f f39bd9739d
commit 8727985683
1 changed files with 32 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
include/mbedtls/cmac.h
View File

@@ -101,9 +101,17 @@ struct mbedtls_cmac_context_t
#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().
*
* \param ctx The cipher context used for the CMAC operation, initialized
* as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
@@ -123,9 +131,15 @@ int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
* \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.
@@ -139,12 +153,13 @@ int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
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.
@@ -157,12 +172,14 @@ int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
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.
*