yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Reword documentation of CMAC operations
This commit is contained in:
Gilles Peskine 2021-12-09 23:28:36 +01:00 committed by GitHub
commit d31da1c673
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
include/mbedtls/cmac.h
View file

@ -67,9 +67,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().
*
* \note When the CMAC implementation is supplied by an alternate
* implementation (through #MBEDTLS_CMAC_ALT), some ciphers
@ -95,9 +103,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.
@ -111,12 +125,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.
@ -129,12 +144,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.
*