yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-23 09:25:36 +01:00
Code Issues Packages Projects Releases Wiki Activity

Reword documentation of CMAC operations

Browse Source 
Change the wording of the documentation for some CMAC functions,
as the existing wording, while technically correct, can be
easy to misunderstand. The reworded docs explain the flow of
a CMAC computation a little more fully.

Signed-off-by: David Horstmann <david.horstmann@arm.com>
This commit is contained in:
David Horstmann 2021-12-06 18:58:02 +00:00
parent 582f2398d4
commit b56f38f57b
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.
* *