From 266694ea42443d8f401ebad5b93037d6af4192b3 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 20 May 2021 09:02:37 +0200 Subject: [PATCH 01/19] Define CCM multi-part API Define CCM multi-part API along the lines of the GCM multi-part API. The two APIs are not exactly the same as, contrary to GCM, CCM needs the size of the additional data and plaintext/ciphertext from the start. Signed-off-by: Ronald Cron --- ChangeLog.d/m-ccm-api.txt | 5 ++ include/mbedtls/ccm.h | 140 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 ChangeLog.d/m-ccm-api.txt diff --git a/ChangeLog.d/m-ccm-api.txt b/ChangeLog.d/m-ccm-api.txt new file mode 100644 index 0000000000..7301e12e59 --- /dev/null +++ b/ChangeLog.d/m-ccm-api.txt @@ -0,0 +1,5 @@ +Features + * The CCM API now supports multi-part operations. Alternative + implementations can add multipart support according to the new multi-part + interface functions. The implementation of these functions in Mbed TLS + will be added in a future release. diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index f63e61be50..0fc8ae4505 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -55,6 +55,11 @@ #include "mbedtls/cipher.h" +#define MBEDTLS_CCM_DECRYPT 0 +#define MBEDTLS_CCM_ENCRYPT 1 +#define MBEDTLS_CCM_STAR_DECRYPT 2 +#define MBEDTLS_CCM_STAR_ENCRYPT 3 + #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */ #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ @@ -288,6 +293,141 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len ); +/** + * \brief This function starts a CCM encryption or decryption + * operation. + * + * \param ctx The CCM context. This must be initialized. + * \param mode The operation to perform: #MBEDTLS_CCM_ENCRYPT or + * #MBEDTLS_CCM_DECRYPT or #MBEDTLS_CCM_STAR_ENCRYPT or + * #MBEDTLS_CCM_STAR_DECRYPT. + * \param iv The initialization vector. This must be a readable buffer of + * at least \p iv_len Bytes. + * \param iv_len The length of the IV. + * \param ad_len The length of the additional data in bytes. + * \param body_len The length of the data to encrypt or decrypt in bytes. + * + * \return \c 0 on success. + */ +int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, + int mode, + const unsigned char *iv, + size_t iv_len, + size_t ad_len, + size_t body_len ); + +/** + * \brief This function feeds an input buffer as associated data + * (authenticated but not encrypted data) in a CCM + * encryption or decryption operation. + * + * Call this function after mbedtls_ccm_starts() to pass + * the associated data. If the associated data is empty, + * you do not need to call this function. You may not + * call this function after calling mbedtls_ccm_update(). + * + * \note This function may be called several times per operation, + * passing the associated data in chunks. + * + * \param ctx The CCM context. This must have been started with + * mbedtls_ccm_starts() and must not have yet received + * any input with mbedtls_ccm_update(). + * \param add The buffer holding the additional data, or \c NULL + * if \p add_len is \c 0. + * \param add_len The length of the additional data. If \c 0, + * \p add may be \c NULL. + * + * \return \c 0 on success. + * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * total input length too long. + */ +int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, + const unsigned char *add, + size_t add_len ); + +/** + * \brief This function feeds an input buffer into an ongoing CCM + * encryption or decryption operation. + * + * You may call this function zero, one or more times + * to pass successive parts of the input: the plaintext to + * encrypt, or the ciphertext (not including the tag) to + * decrypt. After the last part of the input, call + * mbedtls_ccm_finish(). + * + * This function may produce output in one of the following + * ways: + * - Immediate output: the output length is always equal + * to the input length. + * - Buffered output: but for the last chunck of input data, + * the output consists of a whole number of 16-byte blocks. + * If the total input length so far (not including + * associated data) is 16 \* *B* + *A* with *A* < 16 then + * the total output length is 16 \* *B*. + * For the last chunck of input data, the output length is + * equal to the input length. The function uses the length + * in bytes of the body data passed in mbedtls_ccm_starts() + * to detect the last chunck of data to encrypt or decrypt. + * + * In particular: + * - It is always correct to call this function with + * \p output_size >= \p input_length + 15. + * - If \p input_length is a multiple of 16 for all the calls + * to this function during an operation (not necessary for + * the last one) then it is correct to use \p output_size + * =\p input_length. + * + * \note For decryption, the output buffer cannot be the same as + * the input buffer. If the buffers overlap, the output buffer + * must trail at least 8 Bytes behind the input buffer. + * + * \param ctx The CCM context. This must be initialized. + * \param input The buffer holding the input data. If \p input_length + * is greater than zero, this must be a readable buffer + * of at least \p input_length bytes. + * \param input_length The length of the input data in bytes. + * \param output The buffer for the output data. If \p output_size + * is greater than zero, this must be a writable buffer of + * at least \p output_size bytes. + * \param output_size The size of the output buffer in bytes. + * See the function description regarding the output size. + * \param output_length On success, \p *output_length contains the actual + * length of the output written in \p output. + * On failure, the content of \p *output_length is + * unspecified. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * total input length too long, + * unsupported input/output buffer overlap detected, + * or \p output_size too small. + */ +int mbedtls_ccm_update( mbedtls_ccm_context *ctx, + const unsigned char *input, size_t input_length, + unsigned char *output, size_t output_size, + size_t *output_length ); + +/** + * \brief This function finishes the CCM operation and generates + * the authentication tag. + * + * It wraps up the CCM stream, and generates the + * tag. The tag can have a maximum length of 16 Bytes. + * + * \param ctx The CCM context. This must be initialized. + * \param tag The buffer for holding the tag. If \p tag_len is greater + * than zero, this must be a writable buffer of at least \p + * tag_len Bytes. + * \param tag_len The length of the tag to generate. This must be at least + * four for CCM but can be equal to \c 0 for CCM*. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * invalid value of \p tag_len. + */ +int mbedtls_ccm_finish( mbedtls_ccm_context *ctx, + unsigned char *tag, size_t tag_len ); + #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) /** * \brief The CCM checkup routine. From 5905f91ba126936084b634d0127784b16670ce6a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 26 May 2021 09:46:09 +0200 Subject: [PATCH 02/19] Improve mbedtls_ccm_starts() description Change from `body` to `input` to refer to the input data. Add prefix total_ to the new length parameters to ease refering to them in the documentation of the other multi-part APIs. Add error code documentation. Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 0fc8ae4505..acb1482f40 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -301,20 +301,25 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \param mode The operation to perform: #MBEDTLS_CCM_ENCRYPT or * #MBEDTLS_CCM_DECRYPT or #MBEDTLS_CCM_STAR_ENCRYPT or * #MBEDTLS_CCM_STAR_DECRYPT. - * \param iv The initialization vector. This must be a readable buffer of - * at least \p iv_len Bytes. - * \param iv_len The length of the IV. - * \param ad_len The length of the additional data in bytes. - * \param body_len The length of the data to encrypt or decrypt in bytes. + * \param iv The initialization vector. This must be a readable buffer + * of at least \p iv_len Bytes. + * \param iv_len The length of the IV in bytes. + * \param total_ad_len The total length of additional data in bytes. + * \param total_input_len The total length of input data to encrypt or decrypt + * in bytes. * * \return \c 0 on success. + * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p iv_len is invalid (lower than \c 7 or greater than + * \c 13), + * \p total_ad_len is greater than \c 0xFF00. */ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, int mode, const unsigned char *iv, size_t iv_len, - size_t ad_len, - size_t body_len ); + size_t total_ad_len, + size_t total_input_len ); /** * \brief This function feeds an input buffer as associated data From d1a29a9687765871fc522ae0ac9eeaa65692346a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 26 May 2021 09:49:11 +0200 Subject: [PATCH 03/19] Align mbedtls_ccm_update_ad() and mbedtls_ccm_update() descriptions Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index acb1482f40..7303aacff4 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -326,14 +326,13 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * (authenticated but not encrypted data) in a CCM * encryption or decryption operation. * - * Call this function after mbedtls_ccm_starts() to pass - * the associated data. If the associated data is empty, - * you do not need to call this function. You may not + * You may call this function zero, one or more times + * to pass successive parts of the additional data. The + * lengths \p add_len of the data parts should eventually add + * up exactly to the total length of additional data + * \c total_ad_len passed to mbedtls_ccm_starts(). You may not * call this function after calling mbedtls_ccm_update(). * - * \note This function may be called several times per operation, - * passing the associated data in chunks. - * * \param ctx The CCM context. This must have been started with * mbedtls_ccm_starts() and must not have yet received * any input with mbedtls_ccm_update(). @@ -358,7 +357,10 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * to pass successive parts of the input: the plaintext to * encrypt, or the ciphertext (not including the tag) to * decrypt. After the last part of the input, call - * mbedtls_ccm_finish(). + * mbedtls_ccm_finish(). The lengths \p input_length of the + * data parts should eventually add up exactly to the total + * length of input data \c total_input_len passed to + * mbedtls_ccm_starts(). * * This function may produce output in one of the following * ways: From 2d40b1031fbb7f829569d4086abc9b8e0b35d621 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 26 May 2021 10:11:06 +0200 Subject: [PATCH 04/19] Fix mbedtls_ccm_update() buffered output description Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 7303aacff4..7ed4b594ba 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -366,15 +366,17 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * ways: * - Immediate output: the output length is always equal * to the input length. - * - Buffered output: but for the last chunck of input data, + * - Buffered output: but for the last part of input data, * the output consists of a whole number of 16-byte blocks. * If the total input length so far (not including * associated data) is 16 \* *B* + *A* with *A* < 16 then * the total output length is 16 \* *B*. - * For the last chunck of input data, the output length is - * equal to the input length. The function uses the length - * in bytes of the body data passed in mbedtls_ccm_starts() - * to detect the last chunck of data to encrypt or decrypt. + * For the last part of input data, the output length is + * equal to the input length plus the number of bytes (*A*) + * buffered in the previous call to the function (if any). + * The function uses the total length of input data + * \c total_input_len passed to mbedtls_ccm_starts() + * to detect the last part of input data. * * In particular: * - It is always correct to call this function with From 9ca25503ba02ec21744db349734f3b98192d645a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 26 May 2021 10:22:06 +0200 Subject: [PATCH 05/19] Fix mbedtls_ccm_finish() error code description Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 7ed4b594ba..6287054b02 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -432,7 +432,15 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * * \return \c 0 on success. * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: - * invalid value of \p tag_len. + * invalid value of \p tag_len, + * the total amount of additional data passed to + * mbedtls_ccm_update_ad() was lower than the total length of + * additional data \c total_ad_len passed to + * mbedtls_ccm_starts(), + * the total amount of input data passed to + * mbedtls_ccm_update() was lower than the total length of + * input data \c total_input_len passed to + * mbedtls_ccm_starts(). */ int mbedtls_ccm_finish( mbedtls_ccm_context *ctx, unsigned char *tag, size_t tag_len ); From 4c2a3792804a0b45c2a961de7e783250806c49d3 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 26 May 2021 10:37:45 +0200 Subject: [PATCH 06/19] State explicitly that multi-part CCM is not implemented in Mbed TLS yet Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 6287054b02..45fe7f357e 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -297,6 +297,8 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \brief This function starts a CCM encryption or decryption * operation. * + * \note This function is not implemented in Mbed TLS yet. + * * \param ctx The CCM context. This must be initialized. * \param mode The operation to perform: #MBEDTLS_CCM_ENCRYPT or * #MBEDTLS_CCM_DECRYPT or #MBEDTLS_CCM_STAR_ENCRYPT or @@ -333,6 +335,8 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * \c total_ad_len passed to mbedtls_ccm_starts(). You may not * call this function after calling mbedtls_ccm_update(). * + * \note This function is not implemented in Mbed TLS yet. + * * \param ctx The CCM context. This must have been started with * mbedtls_ccm_starts() and must not have yet received * any input with mbedtls_ccm_update(). @@ -386,6 +390,8 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * the last one) then it is correct to use \p output_size * =\p input_length. * + * \note This function is not implemented in Mbed TLS yet. + * * \note For decryption, the output buffer cannot be the same as * the input buffer. If the buffers overlap, the output buffer * must trail at least 8 Bytes behind the input buffer. @@ -423,6 +429,8 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * It wraps up the CCM stream, and generates the * tag. The tag can have a maximum length of 16 Bytes. * + * \note This function is not implemented in Mbed TLS yet. + * * \param ctx The CCM context. This must be initialized. * \param tag The buffer for holding the tag. If \p tag_len is greater * than zero, this must be a writable buffer of at least \p From eabc3afe69c96d43897d2e0fd6e30e896bbdeb78 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 26 May 2021 10:45:30 +0200 Subject: [PATCH 07/19] Align length and additional data shorthand in parameter names Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 45fe7f357e..4da50a2b53 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -306,7 +306,7 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \param iv The initialization vector. This must be a readable buffer * of at least \p iv_len Bytes. * \param iv_len The length of the IV in bytes. - * \param total_ad_len The total length of additional data in bytes. + * \param total_add_len The total length of additional data in bytes. * \param total_input_len The total length of input data to encrypt or decrypt * in bytes. * @@ -314,13 +314,13 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: * \p iv_len is invalid (lower than \c 7 or greater than * \c 13), - * \p total_ad_len is greater than \c 0xFF00. + * \p total_add_len is greater than \c 0xFF00. */ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, int mode, const unsigned char *iv, size_t iv_len, - size_t total_ad_len, + size_t total_add_len, size_t total_input_len ); /** @@ -332,8 +332,8 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * to pass successive parts of the additional data. The * lengths \p add_len of the data parts should eventually add * up exactly to the total length of additional data - * \c total_ad_len passed to mbedtls_ccm_starts(). You may not - * call this function after calling mbedtls_ccm_update(). + * \c total_add_len passed to mbedtls_ccm_starts(). You may + * not call this function after calling mbedtls_ccm_update(). * * \note This function is not implemented in Mbed TLS yet. * @@ -361,7 +361,7 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * to pass successive parts of the input: the plaintext to * encrypt, or the ciphertext (not including the tag) to * decrypt. After the last part of the input, call - * mbedtls_ccm_finish(). The lengths \p input_length of the + * mbedtls_ccm_finish(). The lengths \p input_len of the * data parts should eventually add up exactly to the total * length of input data \c total_input_len passed to * mbedtls_ccm_starts(). @@ -384,11 +384,11 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * * In particular: * - It is always correct to call this function with - * \p output_size >= \p input_length + 15. - * - If \p input_length is a multiple of 16 for all the calls + * \p output_size >= \p input_len + 15. + * - If \p input_len is a multiple of 16 for all the calls * to this function during an operation (not necessary for * the last one) then it is correct to use \p output_size - * =\p input_length. + * =\p input_len. * * \note This function is not implemented in Mbed TLS yet. * @@ -397,18 +397,18 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * must trail at least 8 Bytes behind the input buffer. * * \param ctx The CCM context. This must be initialized. - * \param input The buffer holding the input data. If \p input_length + * \param input The buffer holding the input data. If \p input_len * is greater than zero, this must be a readable buffer - * of at least \p input_length bytes. - * \param input_length The length of the input data in bytes. + * of at least \p input_len bytes. + * \param input_len The length of the input data in bytes. * \param output The buffer for the output data. If \p output_size * is greater than zero, this must be a writable buffer of * at least \p output_size bytes. * \param output_size The size of the output buffer in bytes. * See the function description regarding the output size. - * \param output_length On success, \p *output_length contains the actual + * \param output_len On success, \p *output_len contains the actual * length of the output written in \p output. - * On failure, the content of \p *output_length is + * On failure, the content of \p *output_len is * unspecified. * * \return \c 0 on success. @@ -418,9 +418,9 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * or \p output_size too small. */ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, - const unsigned char *input, size_t input_length, + const unsigned char *input, size_t input_len, unsigned char *output, size_t output_size, - size_t *output_length ); + size_t *output_len ); /** * \brief This function finishes the CCM operation and generates @@ -443,7 +443,7 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * invalid value of \p tag_len, * the total amount of additional data passed to * mbedtls_ccm_update_ad() was lower than the total length of - * additional data \c total_ad_len passed to + * additional data \c total_add_len passed to * mbedtls_ccm_starts(), * the total amount of input data passed to * mbedtls_ccm_update() was lower than the total length of From c0cc7ba51ed043407186ea42e92ff3299beb54dd Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 08:47:09 +0200 Subject: [PATCH 08/19] Change from total_input_len to plaintext_len as parameter name plaintext_len conveys more information. Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 4da50a2b53..4d9ace547a 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -306,9 +306,10 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \param iv The initialization vector. This must be a readable buffer * of at least \p iv_len Bytes. * \param iv_len The length of the IV in bytes. - * \param total_add_len The total length of additional data in bytes. - * \param total_input_len The total length of input data to encrypt or decrypt - * in bytes. + * \param total_add_len The total length of additional data in bytes. + * \param plaintext_len The length in bytes of the plaintext to encrypt or + * result of the decryption (thus not encompassing the + * additional data that are not encrypted). * * \return \c 0 on success. * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: @@ -321,7 +322,7 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, const unsigned char *iv, size_t iv_len, size_t total_add_len, - size_t total_input_len ); + size_t plaintext_len ); /** * \brief This function feeds an input buffer as associated data @@ -362,8 +363,8 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * encrypt, or the ciphertext (not including the tag) to * decrypt. After the last part of the input, call * mbedtls_ccm_finish(). The lengths \p input_len of the - * data parts should eventually add up exactly to the total - * length of input data \c total_input_len passed to + * data parts should eventually add up exactly to the + * plaintext length \c plaintext_len passed to * mbedtls_ccm_starts(). * * This function may produce output in one of the following @@ -378,8 +379,8 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * For the last part of input data, the output length is * equal to the input length plus the number of bytes (*A*) * buffered in the previous call to the function (if any). - * The function uses the total length of input data - * \c total_input_len passed to mbedtls_ccm_starts() + * The function uses the plaintext length + * \c plaintext_len passed to mbedtls_ccm_starts() * to detect the last part of input data. * * In particular: @@ -446,9 +447,8 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * additional data \c total_add_len passed to * mbedtls_ccm_starts(), * the total amount of input data passed to - * mbedtls_ccm_update() was lower than the total length of - * input data \c total_input_len passed to - * mbedtls_ccm_starts(). + * mbedtls_ccm_update() was lower than the plaintext length + * \c plaintext_len passed to mbedtls_ccm_starts(). */ int mbedtls_ccm_finish( mbedtls_ccm_context *ctx, unsigned char *tag, size_t tag_len ); From 0cc60f9985d424f440b47819597359e53953a535 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 09:01:25 +0200 Subject: [PATCH 09/19] Improve some length parameter descriptions Improve some length parameter descriptions, aligning them with the descriptions for the one-shot functions. Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 4d9ace547a..4cfb1e85cf 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -305,8 +305,11 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * #MBEDTLS_CCM_STAR_DECRYPT. * \param iv The initialization vector. This must be a readable buffer * of at least \p iv_len Bytes. - * \param iv_len The length of the IV in bytes. + * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, + * or 13. The length L of the message length field is + * 15 - \p iv_len. * \param total_add_len The total length of additional data in bytes. + * This must be less than `2^16 - 2^8`. * \param plaintext_len The length in bytes of the plaintext to encrypt or * result of the decryption (thus not encompassing the * additional data that are not encrypted). @@ -436,8 +439,9 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * \param tag The buffer for holding the tag. If \p tag_len is greater * than zero, this must be a writable buffer of at least \p * tag_len Bytes. - * \param tag_len The length of the tag to generate. This must be at least - * four for CCM but can be equal to \c 0 for CCM*. + * \param tag_len The length of the tag to generate in Bytes: + * 4, 6, 8, 10, 12, 14 or 16. + * For CCM*, zero is also valid. * * \return \c 0 on success. * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: From 86e6c9f8605138befbfa07e1d7deb30a678b705d Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 09:30:59 +0200 Subject: [PATCH 10/19] Improve expected context state for some APIs Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 4cfb1e85cf..eb0cbb2ca2 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -400,7 +400,8 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * the input buffer. If the buffers overlap, the output buffer * must trail at least 8 Bytes behind the input buffer. * - * \param ctx The CCM context. This must be initialized. + * \param ctx The CCM context. This must have been started with + * mbedtls_ccm_starts(). * \param input The buffer holding the input data. If \p input_len * is greater than zero, this must be a readable buffer * of at least \p input_len bytes. @@ -435,7 +436,8 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * * \note This function is not implemented in Mbed TLS yet. * - * \param ctx The CCM context. This must be initialized. + * \param ctx The CCM context. This must have been started with + * mbedtls_ccm_starts(). * \param tag The buffer for holding the tag. If \p tag_len is greater * than zero, this must be a writable buffer of at least \p * tag_len Bytes. From b87fe016aa966af1cb974f90792aa554a0804b29 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 09:40:46 +0200 Subject: [PATCH 11/19] Remove buffer overlap considerations Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 5 ----- 1 file changed, 5 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index eb0cbb2ca2..e5a58068e2 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -396,10 +396,6 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * * \note This function is not implemented in Mbed TLS yet. * - * \note For decryption, the output buffer cannot be the same as - * the input buffer. If the buffers overlap, the output buffer - * must trail at least 8 Bytes behind the input buffer. - * * \param ctx The CCM context. This must have been started with * mbedtls_ccm_starts(). * \param input The buffer holding the input data. If \p input_len @@ -419,7 +415,6 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * \return \c 0 on success. * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: * total input length too long, - * unsupported input/output buffer overlap detected, * or \p output_size too small. */ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, From 84cb8e00637f2688017e0f123a8d2fc2ab93c9aa Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 09:49:58 +0200 Subject: [PATCH 12/19] Add invalid mode as mbedtls_ccm_start() possible error Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 1 + 1 file changed, 1 insertion(+) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index e5a58068e2..c4e310d42b 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -316,6 +316,7 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * * \return \c 0 on success. * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p mode is invalid, * \p iv_len is invalid (lower than \c 7 or greater than * \c 13), * \p total_add_len is greater than \c 0xFF00. From ff92479f717060ec49b86ee578e96c28affba6b7 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 09:51:30 +0200 Subject: [PATCH 13/19] Wording improvement Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index c4e310d42b..b8964d8e13 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -375,7 +375,7 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * ways: * - Immediate output: the output length is always equal * to the input length. - * - Buffered output: but for the last part of input data, + * - Buffered output: except for the last part of input data, * the output consists of a whole number of 16-byte blocks. * If the total input length so far (not including * associated data) is 16 \* *B* + *A* with *A* < 16 then From 51584c6cdb43c2657c10886eb9268ae8d9773de5 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 09:47:15 +0200 Subject: [PATCH 14/19] Prefer ad to add as shorthand for additional/associated data Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 56 +++++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index b8964d8e13..ae09cf5371 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -138,10 +138,10 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, * or 13. The length L of the message length field is * 15 - \p iv_len. - * \param add The additional data field. If \p add_len is greater than - * zero, \p add must be a readable buffer of at least that + * \param ad The additional data field. If \p ad_len is greater than + * zero, \p ad must be a readable buffer of at least that * length. - * \param add_len The length of additional data in Bytes. + * \param ad_len The length of additional data in Bytes. * This must be less than `2^16 - 2^8`. * \param input The buffer holding the input data. If \p length is greater * than zero, \p input must be a readable buffer of at least @@ -159,7 +159,7 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); */ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, - const unsigned char *add, size_t add_len, + const unsigned char *ad, size_t ad_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len ); @@ -184,9 +184,9 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, * or 13. The length L of the message length field is * 15 - \p iv_len. - * \param add The additional data field. This must be a readable buffer of - * at least \p add_len Bytes. - * \param add_len The length of additional data in Bytes. + * \param ad The additional data field. This must be a readable buffer of + * at least \p ad_len Bytes. + * \param ad_len The length of additional data in Bytes. * This must be less than 2^16 - 2^8. * \param input The buffer holding the input data. If \p length is greater * than zero, \p input must be a readable buffer of at least @@ -207,7 +207,7 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, */ int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, - const unsigned char *add, size_t add_len, + const unsigned char *ad, size_t ad_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len ); @@ -223,9 +223,9 @@ int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, * or 13. The length L of the message length field is * 15 - \p iv_len. - * \param add The additional data field. This must be a readable buffer - * of at least that \p add_len Bytes.. - * \param add_len The length of additional data in Bytes. + * \param ad The additional data field. This must be a readable buffer + * of at least that \p ad_len Bytes.. + * \param ad_len The length of additional data in Bytes. * This must be less than 2^16 - 2^8. * \param input The buffer holding the input data. If \p length is greater * than zero, \p input must be a readable buffer of at least @@ -244,7 +244,7 @@ int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, */ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, - const unsigned char *add, size_t add_len, + const unsigned char *ad, size_t ad_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len ); @@ -265,9 +265,9 @@ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, * or 13. The length L of the message length field is * 15 - \p iv_len. - * \param add The additional data field. This must be a readable buffer of - * at least that \p add_len Bytes. - * \param add_len The length of additional data in Bytes. + * \param ad The additional data field. This must be a readable buffer of + * at least that \p ad_len Bytes. + * \param ad_len The length of additional data in Bytes. * This must be less than 2^16 - 2^8. * \param input The buffer holding the input data. If \p length is greater * than zero, \p input must be a readable buffer of at least @@ -289,7 +289,7 @@ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, */ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, - const unsigned char *add, size_t add_len, + const unsigned char *ad, size_t ad_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len ); @@ -308,7 +308,7 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, * or 13. The length L of the message length field is * 15 - \p iv_len. - * \param total_add_len The total length of additional data in bytes. + * \param total_ad_len The total length of additional data in bytes. * This must be less than `2^16 - 2^8`. * \param plaintext_len The length in bytes of the plaintext to encrypt or * result of the decryption (thus not encompassing the @@ -319,13 +319,13 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \p mode is invalid, * \p iv_len is invalid (lower than \c 7 or greater than * \c 13), - * \p total_add_len is greater than \c 0xFF00. + * \p total_ad_len is greater than \c 0xFF00. */ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, int mode, const unsigned char *iv, size_t iv_len, - size_t total_add_len, + size_t total_ad_len, size_t plaintext_len ); /** @@ -335,9 +335,9 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * * You may call this function zero, one or more times * to pass successive parts of the additional data. The - * lengths \p add_len of the data parts should eventually add + * lengths \p ad_len of the data parts should eventually add * up exactly to the total length of additional data - * \c total_add_len passed to mbedtls_ccm_starts(). You may + * \c total_ad_len passed to mbedtls_ccm_starts(). You may * not call this function after calling mbedtls_ccm_update(). * * \note This function is not implemented in Mbed TLS yet. @@ -345,18 +345,18 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * \param ctx The CCM context. This must have been started with * mbedtls_ccm_starts() and must not have yet received * any input with mbedtls_ccm_update(). - * \param add The buffer holding the additional data, or \c NULL - * if \p add_len is \c 0. - * \param add_len The length of the additional data. If \c 0, - * \p add may be \c NULL. + * \param ad The buffer holding the additional data, or \c NULL + * if \p ad_len is \c 0. + * \param ad_len The length of the additional data. If \c 0, + * \p ad may be \c NULL. * * \return \c 0 on success. * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: * total input length too long. */ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, - const unsigned char *add, - size_t add_len ); + const unsigned char *ad, + size_t ad_len ); /** * \brief This function feeds an input buffer into an ongoing CCM @@ -446,7 +446,7 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * invalid value of \p tag_len, * the total amount of additional data passed to * mbedtls_ccm_update_ad() was lower than the total length of - * additional data \c total_add_len passed to + * additional data \c total_ad_len passed to * mbedtls_ccm_starts(), * the total amount of input data passed to * mbedtls_ccm_update() was lower than the plaintext length From b740a617ec71a88004683c5bcdadedb008a12ec4 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 10:53:06 +0200 Subject: [PATCH 15/19] Remove change log Remove the change log as the changes in this PR only affect CCM alternative implementation developers. Signed-off-by: Ronald Cron --- ChangeLog.d/m-ccm-api.txt | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 ChangeLog.d/m-ccm-api.txt diff --git a/ChangeLog.d/m-ccm-api.txt b/ChangeLog.d/m-ccm-api.txt deleted file mode 100644 index 7301e12e59..0000000000 --- a/ChangeLog.d/m-ccm-api.txt +++ /dev/null @@ -1,5 +0,0 @@ -Features - * The CCM API now supports multi-part operations. Alternative - implementations can add multipart support according to the new multi-part - interface functions. The implementation of these functions in Mbed TLS - will be added in a future release. From 7c41cd2a7af2a499d362140a7061c40aa47da5da Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sat, 29 May 2021 17:22:10 +0200 Subject: [PATCH 16/19] Split operation start and the declaration of data lengths Split operation start and the declaration of data lengths to better align with the PSA Cryptography multipart AEAD APIs. Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 59 +++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index ae09cf5371..f89ddc2e0f 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -308,6 +308,26 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, * or 13. The length L of the message length field is * 15 - \p iv_len. + * + * \return \c 0 on success. + * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p mode is invalid, + * \p iv_len is invalid (lower than \c 7 or greater than + * \c 13). + */ +int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, + int mode, + const unsigned char *iv, + size_t iv_len ); + +/** + * \brief This function declares the lengths of the message + * and additional data for a CCM encryption or decryption + * operation. + * + * \note This function is not implemented in Mbed TLS yet. + * + * \param ctx The CCM context. This must be initialized. * \param total_ad_len The total length of additional data in bytes. * This must be less than `2^16 - 2^8`. * \param plaintext_len The length in bytes of the plaintext to encrypt or @@ -316,17 +336,11 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * * \return \c 0 on success. * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: - * \p mode is invalid, - * \p iv_len is invalid (lower than \c 7 or greater than - * \c 13), * \p total_ad_len is greater than \c 0xFF00. */ -int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, - int mode, - const unsigned char *iv, - size_t iv_len, - size_t total_ad_len, - size_t plaintext_len ); +int mbedtls_ccm_set_lengths( mbedtls_ccm_context *ctx, + size_t total_ad_len, + size_t plaintext_len ); /** * \brief This function feeds an input buffer as associated data @@ -337,14 +351,17 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * to pass successive parts of the additional data. The * lengths \p ad_len of the data parts should eventually add * up exactly to the total length of additional data - * \c total_ad_len passed to mbedtls_ccm_starts(). You may - * not call this function after calling mbedtls_ccm_update(). + * \c total_ad_len passed to mbedtls_ccm_set_lengths(). You + * may not call this function after calling + * mbedtls_ccm_update(). * * \note This function is not implemented in Mbed TLS yet. * * \param ctx The CCM context. This must have been started with - * mbedtls_ccm_starts() and must not have yet received - * any input with mbedtls_ccm_update(). + * mbedtls_ccm_starts(), the lengths of the message and + * additional data must have been declared with + * mbedtls_ccm_set_lengths() and this must not have yet + * received any input with mbedtls_ccm_update(). * \param ad The buffer holding the additional data, or \c NULL * if \p ad_len is \c 0. * \param ad_len The length of the additional data. If \c 0, @@ -369,7 +386,7 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * mbedtls_ccm_finish(). The lengths \p input_len of the * data parts should eventually add up exactly to the * plaintext length \c plaintext_len passed to - * mbedtls_ccm_starts(). + * mbedtls_ccm_set_lengths(). * * This function may produce output in one of the following * ways: @@ -384,7 +401,7 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * equal to the input length plus the number of bytes (*A*) * buffered in the previous call to the function (if any). * The function uses the plaintext length - * \c plaintext_len passed to mbedtls_ccm_starts() + * \c plaintext_len passed to mbedtls_ccm_set_lengths() * to detect the last part of input data. * * In particular: @@ -398,7 +415,9 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * \note This function is not implemented in Mbed TLS yet. * * \param ctx The CCM context. This must have been started with - * mbedtls_ccm_starts(). + * mbedtls_ccm_starts() and the lengths of the message and + * additional data must have been declared with + * mbedtls_ccm_set_lengths(). * \param input The buffer holding the input data. If \p input_len * is greater than zero, this must be a readable buffer * of at least \p input_len bytes. @@ -433,7 +452,9 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * \note This function is not implemented in Mbed TLS yet. * * \param ctx The CCM context. This must have been started with - * mbedtls_ccm_starts(). + * mbedtls_ccm_starts() and the lengths of the message and + * additional data must have been declared with + * mbedtls_ccm_set_lengths(). * \param tag The buffer for holding the tag. If \p tag_len is greater * than zero, this must be a writable buffer of at least \p * tag_len Bytes. @@ -447,10 +468,10 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * the total amount of additional data passed to * mbedtls_ccm_update_ad() was lower than the total length of * additional data \c total_ad_len passed to - * mbedtls_ccm_starts(), + * mbedtls_ccm_set_lengths(), * the total amount of input data passed to * mbedtls_ccm_update() was lower than the plaintext length - * \c plaintext_len passed to mbedtls_ccm_starts(). + * \c plaintext_len passed to mbedtls_ccm_set_lengths(). */ int mbedtls_ccm_finish( mbedtls_ccm_context *ctx, unsigned char *tag, size_t tag_len ); From f668bd18dfc11e2092f65c1cd13162cbe8975fbe Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 27 May 2021 11:48:00 +0200 Subject: [PATCH 17/19] Add migration guide for developers of CCM alternative implementation Signed-off-by: Ronald Cron --- docs/3.0-migration-guide.d/ccm-alt.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/3.0-migration-guide.d/ccm-alt.md diff --git a/docs/3.0-migration-guide.d/ccm-alt.md b/docs/3.0-migration-guide.d/ccm-alt.md new file mode 100644 index 0000000000..1abac7acdf --- /dev/null +++ b/docs/3.0-migration-guide.d/ccm-alt.md @@ -0,0 +1,9 @@ +CCM interface changes: impact for alternative implementations +------------------------------------------------------------- + +The CCM interface has changed with the addition of support for +multi-part operations. Five new API functions have been defined: +mbedtls_ccm_starts(), mbedtls_ccm_set_lengths(), +mbedtls_ccm_update_ad(), mbedtls_ccm_update() and mbedtls_ccm_finish(). +Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to +implement those additional five API functions. From 542957d6b1dfd61bb7c162061e0ab7c38cfec802 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 1 Jun 2021 09:22:05 +0200 Subject: [PATCH 18/19] Add some API calling order documentation Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index f89ddc2e0f..c4fc6b55d9 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -297,6 +297,11 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * \brief This function starts a CCM encryption or decryption * operation. * + * This function and mbedtls_ccm_set_lengths() must be called + * before calling mbedtls_ccm_update_ad() or + * mbedtls_ccm_update(). This function can be called before + * or after mbedtls_ccm_set_lengths(). + * * \note This function is not implemented in Mbed TLS yet. * * \param ctx The CCM context. This must be initialized. @@ -325,6 +330,11 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * and additional data for a CCM encryption or decryption * operation. * + * This function and mbedtls_ccm_starts() must be called + * before calling mbedtls_ccm_update_ad() or + * mbedtls_ccm_update(). This function can be called before + * or after mbedtls_ccm_starts(). + * * \note This function is not implemented in Mbed TLS yet. * * \param ctx The CCM context. This must be initialized. From e13d3083ee5b8c8bb9f552e06520ae22c3600d6f Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 1 Jun 2021 13:35:40 +0200 Subject: [PATCH 19/19] Add invalid context as a possible reason for _BAD_INPUT error code Signed-off-by: Ronald Cron --- include/mbedtls/ccm.h | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index c4fc6b55d9..ea03a3579c 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -315,7 +315,8 @@ int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, * 15 - \p iv_len. * * \return \c 0 on success. - * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p ctx is in an invalid state, * \p mode is invalid, * \p iv_len is invalid (lower than \c 7 or greater than * \c 13). @@ -345,7 +346,8 @@ int mbedtls_ccm_starts( mbedtls_ccm_context *ctx, * additional data that are not encrypted). * * \return \c 0 on success. - * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p ctx is in an invalid state, * \p total_ad_len is greater than \c 0xFF00. */ int mbedtls_ccm_set_lengths( mbedtls_ccm_context *ctx, @@ -378,7 +380,8 @@ int mbedtls_ccm_set_lengths( mbedtls_ccm_context *ctx, * \p ad may be \c NULL. * * \return \c 0 on success. - * \return \#MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p ctx is in an invalid state, * total input length too long. */ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, @@ -444,6 +447,7 @@ int mbedtls_ccm_update_ad( mbedtls_ccm_context *ctx, * * \return \c 0 on success. * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p ctx is in an invalid state, * total input length too long, * or \p output_size too small. */ @@ -474,6 +478,7 @@ int mbedtls_ccm_update( mbedtls_ccm_context *ctx, * * \return \c 0 on success. * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: + * \p ctx is in an invalid state, * invalid value of \p tag_len, * the total amount of additional data passed to * mbedtls_ccm_update_ad() was lower than the total length of