From 08fd33a875b50aa6e5297f26915c20a3ea265d86 Mon Sep 17 00:00:00 2001 From: Waleed Elmelegy Date: Fri, 22 Sep 2023 14:45:25 +0100 Subject: [PATCH 1/6] Add warning to mbedtls_cipher_setup() about setting padding mode Signed-off-by: Waleed Elmelegy --- include/mbedtls/cipher.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 56fc2d828..b1149f6fa 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -449,6 +449,10 @@ void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); * \brief This function initializes a cipher context for * use with the given cipher primitive. * + * \warning The behavior if mbedtls_cipher_set_padding_mode() + * is not called after calling this function is not + * guaranteed. + * * \param ctx The context to initialize. This must be initialized. * \param cipher_info The cipher to use. * From 3697954ac64d6a19d68e6078acf93c30eed7f763 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 27 May 2021 12:59:11 +0200 Subject: [PATCH 2/6] Fix inconsistent documentation of cipher_setup() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - the \internal note said that calling cipher_init() first would be made mandatory later, but the documention of the ctx parameter already said the context had to be initialized... - the documentation was using the word initialize for two different meanings (calling setup() vs calling init()), making the documentation of the ctx parameter quite confusing (you must initialize before you can initialize...) Signed-off-by: Manuel Pégourié-Gonnard --- include/mbedtls/cipher.h | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index b1149f6fa..44553e729 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -446,14 +446,11 @@ void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); /** - * \brief This function initializes a cipher context for + * \brief This function prepares a cipher context for * use with the given cipher primitive. * - * \warning The behavior if mbedtls_cipher_set_padding_mode() - * is not called after calling this function is not - * guaranteed. - * - * \param ctx The context to initialize. This must be initialized. + * \param ctx The context to prepare. This must be initialized by + * a call to mbedtls_cipher_init() first. * \param cipher_info The cipher to use. * * \return \c 0 on success. @@ -461,10 +458,6 @@ void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * cipher-specific context fails. - * - * \internal Currently, the function also clears the structure. - * In future versions, the caller will be required to call - * mbedtls_cipher_init() on the structure first. */ int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info); From 8013e685f5d3009991c15d9810e95a61baf28463 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 31 May 2021 11:13:35 +0200 Subject: [PATCH 3/6] Clarify calling sequence in the Cipher layer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- include/mbedtls/cipher.h | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 44553e729..54fd53d8c 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -449,6 +449,18 @@ void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); * \brief This function prepares a cipher context for * use with the given cipher primitive. * + * \note After calling this function, you should call + * mbedtls_cipher_setkey() and, if the mode uses padding, + * mbedtls_cipher_set_padding_mode(), then for each + * message to encrypt or decrypt with this key, either: + * - mbedtls_cipher_crypt() for one-shot processing with + * non-AEAD modes; + * - mbedtls_cipher_auth_encrypt_ext() or + * mbedtls_cipher_auth_decrypt_ext() for one-shot + * processing with AEAD modes or NIST_KW; + * - for multi-part processing, see the documentation of + * mbedtls_cipher_reset(). + * * \param ctx The context to prepare. This must be initialized by * a call to mbedtls_cipher_init() first. * \param cipher_info The cipher to use. @@ -701,7 +713,30 @@ int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, /** * \brief This function resets the cipher state. * - * \param ctx The generic cipher context. This must be initialized. + * \note With non-AEAD ciphers, the order of calls for each message + * is as follows: + * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce. + * 2. mbedtls_cipher_reset() + * 3. mbedtls_cipher_update() one or more times + * 4. mbedtls_cipher_finish() + * . + * This sequence can be repeated to encrypt of decrypt multiple + * messages with the same key. + * + * \note With AEAD ciphers, the order of calls for each message + * is as follows: + * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce. + * 2. mbedtls_cipher_reset() + * 3. mbedtls_cipher_update_ad() + * 4. mbedtls_cipher_update() one or more times + * 5. mbedtls_cipher_finish() + * 6. mbedtls_cipher_check_tag() (for decryption) or + * mbedtls_cipher_write_tag() (for encryption). + * . + * This sequence can be repeated to encrypt of decrypt multiple + * messages with the same key. + * + * \param ctx The generic cipher context. This must be bound to a key. * * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on From e4138e3279a42541d40450bd7e1c0c6a65cf7209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 31 May 2021 12:14:02 +0200 Subject: [PATCH 4/6] Fix a typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- include/mbedtls/cipher.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 54fd53d8c..de2ea9950 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -720,7 +720,7 @@ int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, * 3. mbedtls_cipher_update() one or more times * 4. mbedtls_cipher_finish() * . - * This sequence can be repeated to encrypt of decrypt multiple + * This sequence can be repeated to encrypt or decrypt multiple * messages with the same key. * * \note With AEAD ciphers, the order of calls for each message @@ -733,7 +733,7 @@ int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, * 6. mbedtls_cipher_check_tag() (for decryption) or * mbedtls_cipher_write_tag() (for encryption). * . - * This sequence can be repeated to encrypt of decrypt multiple + * This sequence can be repeated to encrypt or decrypt multiple * messages with the same key. * * \param ctx The generic cipher context. This must be bound to a key. From 8ce42ebd87ea4582f316d811b9c09e26d14cb9ce Mon Sep 17 00:00:00 2001 From: Waleed Elmelegy Date: Mon, 25 Sep 2023 14:21:49 +0100 Subject: [PATCH 5/6] Remove invalid comments from cipher.h Signed-off-by: Waleed Elmelegy --- include/mbedtls/cipher.h | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index de2ea9950..784b4e301 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -449,6 +449,12 @@ void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); * \brief This function prepares a cipher context for * use with the given cipher primitive. * + * \warning In CBC mode, if mbedtls_cipher_set_padding_mode() is not called: + * - If MBEDTLS_CIPHER_PADDING_PKCS7 is enabled, the + * context will use PKCS7 padding. + * - Otherwise the context uses no padding and the input + * must be a whole number of blocks. + * * \note After calling this function, you should call * mbedtls_cipher_setkey() and, if the mode uses padding, * mbedtls_cipher_set_padding_mode(), then for each @@ -672,8 +678,6 @@ int mbedtls_cipher_setkey(mbedtls_cipher_context_t *ctx, * \brief This function sets the padding mode, for cipher modes * that use padding. * - * The default passing mode is PKCS7 padding. - * * \param ctx The generic cipher context. This must be initialized and * bound to a cipher information structure. * \param mode The padding mode. @@ -729,8 +733,7 @@ int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, * 2. mbedtls_cipher_reset() * 3. mbedtls_cipher_update_ad() * 4. mbedtls_cipher_update() one or more times - * 5. mbedtls_cipher_finish() - * 6. mbedtls_cipher_check_tag() (for decryption) or + * 5. mbedtls_cipher_check_tag() (for decryption) or * mbedtls_cipher_write_tag() (for encryption). * . * This sequence can be repeated to encrypt or decrypt multiple From 916ed7b8dbbf1aa5fe5542cd24d74a48d617b3a9 Mon Sep 17 00:00:00 2001 From: Waleed Elmelegy Date: Mon, 25 Sep 2023 15:18:48 +0100 Subject: [PATCH 6/6] restore internal comment in cipher.h due to LTS Signed-off-by: Waleed Elmelegy --- include/mbedtls/cipher.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 784b4e301..fa57efeb0 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -476,6 +476,10 @@ void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * cipher-specific context fails. + * + * \internal Currently, the function also clears the structure. + * In future versions, the caller will be required to call + * mbedtls_cipher_init() on the structure first. */ int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info);