diff options
author | Gilles Peskine <gilles.peskine@arm.com> | 2021-12-09 23:28:39 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-12-09 23:28:39 +0100 |
commit | 51377d8a73f4ae25000d9274d0316d4a70d3a95a (patch) | |
tree | 3d92ea097ee212a7b360e8c261fb674cec0d0be8 | |
parent | c2c1c22dda234f771ea0a57d1d019f11291ac91d (diff) | |
parent | b56f38f57bd648ef45d069b729269a5e1cdc5841 (diff) | |
download | mbedtls-51377d8a73f4ae25000d9274d0316d4a70d3a95a.zip mbedtls-51377d8a73f4ae25000d9274d0316d4a70d3a95a.tar.gz mbedtls-51377d8a73f4ae25000d9274d0316d4a70d3a95a.tar.bz2 |
Merge pull request #5280 from davidhorstmann-arm/2.x-improve-cmac-docs
Backport 2.x: Reword documentation of CMAC operations
-rw-r--r-- | include/mbedtls/cmac.h | 49 |
1 files changed, 33 insertions, 16 deletions
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h index 94139d5..8934886 100644 --- a/include/mbedtls/cmac.h +++ b/include/mbedtls/cmac.h @@ -74,9 +74,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 @@ -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 * 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. @@ -118,12 +132,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. @@ -136,12 +151,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. - * - * It is called after mbedtls_cipher_cmac_finish() - * and before mbedtls_cipher_cmac_update(). + * \brief This function starts a new CMAC operation with the same + * key as the previous one. + * + * 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. * |