diff options
-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. * |