yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-25 12:55:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5280 from davidhorstmann-arm/2.x-improve-cmac-docs

Browse source 
Backport 2.x: Reword documentation of CMAC operations
This commit is contained in:
Gilles Peskine 2021-12-09 23:28:39 +01:00 committed by GitHub
parent c2c1c22dda b56f38f57b
commit 51377d8a73
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

@ -74,9 +74,17 @@ struct mbedtls_cmac_context_t
#endif /* !MBEDTLS_CMAC_ALT */ #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. * 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 * \note When the CMAC implementation is supplied by an alternate
* implementation (through #MBEDTLS_CMAC_ALT), some ciphers * implementation (through #MBEDTLS_CMAC_ALT), some ciphers
@ -102,9 +110,15 @@ int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
* \brief This function feeds an input buffer into an ongoing CMAC * \brief This function feeds an input buffer into an ongoing CMAC
* computation. * computation.
* *
* It is called between mbedtls_cipher_cmac_starts() or * The CMAC computation must have previously been started
* mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish(). * by calling mbedtls_cipher_cmac_starts() or
* Can be called repeatedly. * 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 ctx The cipher context used for the CMAC operation.
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
@ -118,12 +132,13 @@ 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 This function finishes the CMAC operation, and writes * \brief This function finishes an ongoing CMAC operation, and
* the result to the output buffer. * writes the result to the output buffer.
* *
* It is called after mbedtls_cipher_cmac_update(). * It should be followed either by
* It can be followed by mbedtls_cipher_cmac_reset() and * mbedtls_cipher_cmac_reset(), which starts another CMAC
* mbedtls_cipher_cmac_update(), or mbedtls_cipher_free(). * 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 ctx The cipher context used for the CMAC operation.
* \param output The output buffer for the CMAC checksum result. * \param output The output buffer for the CMAC checksum result.
@ -136,12 +151,14 @@ int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief This function prepares the authentication of another * \brief This function starts a new CMAC operation with the same
* message with the same key as the previous CMAC * key as the previous one.
* operation.
* *
* It is called after mbedtls_cipher_cmac_finish() * It should be called after finishing the previous CMAC
* and before mbedtls_cipher_cmac_update(). * 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. * \param ctx The cipher context used for the CMAC operation.
* *