@@ -329,8 +329,15 @@ typedef struct mbedtls_cipher_context_t {
329329 /** Padding functions to use, if relevant for
330330 * the specific cipher mode.
331331 */
332- void (* MBEDTLS_PRIVATE (add_padding ))(unsigned char * output , size_t olen , size_t data_len );
333- int (* MBEDTLS_PRIVATE (get_padding ))(unsigned char * input , size_t ilen , size_t * data_len );
332+ void (* MBEDTLS_PRIVATE (add_padding ))(unsigned char * output , size_t olen ,
333+ size_t data_len );
334+ /* Report invalid-padding condition through the output parameter
335+ * invalid_padding. To minimize changes in Mbed TLS 3.6, where this
336+ * declaration is in a public header, use the public type size_t
337+ * rather than the internal type mbedtls_ct_condition_t. */
338+ int (* MBEDTLS_PRIVATE (get_padding ))(unsigned char * input , size_t ilen ,
339+ size_t * data_len ,
340+ size_t * invalid_padding );
334341#endif
335342
336343 /** Buffer for input that has not been processed yet. */
@@ -878,23 +885,24 @@ int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx,
878885 *
879886 * \note With non-AEAD ciphers, the order of calls for each message
880887 * is as follows:
881- * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce.
882- * 2. mbedtls_cipher_reset()
883- * 3. mbedtls_cipher_update() one or more times
884- * 4. mbedtls_cipher_finish()
888+ * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce;
889+ * 2. mbedtls_cipher_reset();
890+ * 3. mbedtls_cipher_update() zero, one or more times;
891+ * 4. mbedtls_cipher_finish_padded() (recommended for decryption
892+ * if the mode uses padding) or mbedtls_cipher_finish().
885893 * .
886894 * This sequence can be repeated to encrypt or decrypt multiple
887895 * messages with the same key.
888896 *
889897 * \note With AEAD ciphers, the order of calls for each message
890898 * is as follows:
891- * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce.
892- * 2. mbedtls_cipher_reset()
893- * 3. mbedtls_cipher_update_ad()
894- * 4. mbedtls_cipher_update() one or more times
895- * 5. mbedtls_cipher_finish()
899+ * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce;
900+ * 2. mbedtls_cipher_reset();
901+ * 3. mbedtls_cipher_update_ad();
902+ * 4. mbedtls_cipher_update() zero, one or more times;
903+ * 5. mbedtls_cipher_finish() (or mbedtls_cipher_finish_padded());
896904 * 6. mbedtls_cipher_check_tag() (for decryption) or
897- * mbedtls_cipher_write_tag() (for encryption).
905+ * mbedtls_cipher_write_tag() (for encryption).
898906 * .
899907 * This sequence can be repeated to encrypt or decrypt multiple
900908 * messages with the same key.
@@ -930,7 +938,8 @@ int mbedtls_cipher_update_ad(mbedtls_cipher_context_t *ctx,
930938 * many block-sized blocks of data as possible to output.
931939 * Any data that cannot be written immediately is either
932940 * added to the next block, or flushed when
933- * mbedtls_cipher_finish() is called.
941+ * mbedtls_cipher_finish() or mbedtls_cipher_finish_padded()
942+ * is called.
934943 * Exception: For MBEDTLS_MODE_ECB, expects a single block
935944 * in size. For example, 16 Bytes for AES.
936945 *
@@ -964,30 +973,97 @@ int mbedtls_cipher_update(mbedtls_cipher_context_t *ctx,
964973 * contained in it is padded to the size of
965974 * the last block, and written to the \p output buffer.
966975 *
976+ * \warning This function reports invalid padding through an error
977+ * code. Adversaries may be able to decrypt encrypted
978+ * data if they can submit chosen ciphertexts and
979+ * detect whether it has valid padding or not,
980+ * either through direct observation or through a side
981+ * channel such as timing. This is known as a
982+ * padding oracle attack.
983+ * Therefore applications that call this function for
984+ * decryption with a cipher that involves padding
985+ * should take care around error handling. Preferably,
986+ * such applications should use
987+ * mbedtls_cipher_finish_padded() instead of this function.
988+ *
967989 * \param ctx The generic cipher context. This must be initialized and
968990 * bound to a key.
969991 * \param output The buffer to write data to. This needs to be a writable
970992 * buffer of at least block_size Bytes.
971993 * \param olen The length of the data written to the \p output buffer.
972994 * This may not be \c NULL.
995+ * Note that when decrypting in a mode with padding,
996+ * the actual output length is sensitive and may be
997+ * used to mount a padding oracle attack (see warning
998+ * above), although less efficiently than through
999+ * the invalid-padding condition.
9731000 *
9741001 * \return \c 0 on success.
9751002 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
9761003 * parameter-verification failure.
9771004 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
9781005 * expecting a full block but not receiving one.
9791006 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
980- * while decrypting.
1007+ * while decrypting. Note that invalid-padding errors
1008+ * should be handled carefully; see the warning above.
9811009 * \return A cipher-specific error code on failure.
9821010 */
9831011int mbedtls_cipher_finish (mbedtls_cipher_context_t * ctx ,
9841012 unsigned char * output , size_t * olen );
9851013
1014+ /**
1015+ * \brief The generic cipher finalization function. If data still
1016+ * needs to be flushed from an incomplete block, the data
1017+ * contained in it is padded to the size of
1018+ * the last block, and written to the \p output buffer.
1019+ *
1020+ * \note This function is similar to mbedtls_cipher_finish().
1021+ * The only difference is that it reports invalid padding
1022+ * decryption differently, through the \p invalid_padding
1023+ * parameter rather than an error code.
1024+ * For encryption, and in modes without padding (including
1025+ * all authenticated modes), this function is identical
1026+ * to mbedtls_cipher_finish().
1027+ *
1028+ * \param[in,out] ctx The generic cipher context. This must be initialized and
1029+ * bound to a key.
1030+ * \param[out] output The buffer to write data to. This needs to be a writable
1031+ * buffer of at least block_size Bytes.
1032+ * \param[out] olen The length of the data written to the \p output buffer.
1033+ * This may not be \c NULL.
1034+ * Note that when decrypting in a mode with padding,
1035+ * the actual output length is sensitive and may be
1036+ * used to mount a padding oracle attack (see warning
1037+ * on mbedtls_cipher_finish()).
1038+ * \param[out] invalid_padding
1039+ * If this function returns \c 0 on decryption,
1040+ * \p *invalid_padding is \c 0 if the ciphertext was
1041+ * valid, and all-bits-one if the ciphertext had invalid
1042+ * padding.
1043+ * On encryption, or in a mode without padding (including
1044+ * all authenticated modes), \p *invalid_padding is \c 0
1045+ * on success.
1046+ * The value in \p *invalid_padding is unspecified if
1047+ * this function returns a nonzero status.
1048+ *
1049+ * \return \c 0 on success.
1050+ * Also \c 0 for decryption with invalid padding.
1051+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
1052+ * parameter-verification failure.
1053+ * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
1054+ * expecting a full block but not receiving one.
1055+ * \return A cipher-specific error code on failure.
1056+ */
1057+ int mbedtls_cipher_finish_padded (mbedtls_cipher_context_t * ctx ,
1058+ unsigned char * output , size_t * olen ,
1059+ size_t * invalid_padding );
1060+
9861061#if defined(MBEDTLS_GCM_C ) || defined(MBEDTLS_CHACHAPOLY_C )
9871062/**
9881063 * \brief This function writes a tag for AEAD ciphers.
9891064 * Currently supported with GCM and ChaCha20+Poly1305.
990- * This must be called after mbedtls_cipher_finish().
1065+ * This must be called after mbedtls_cipher_finish()
1066+ * or mbedtls_cipher_finish_padded().
9911067 *
9921068 * \param ctx The generic cipher context. This must be initialized,
9931069 * bound to a key, and have just completed a cipher
@@ -1006,7 +1082,8 @@ int mbedtls_cipher_write_tag(mbedtls_cipher_context_t *ctx,
10061082/**
10071083 * \brief This function checks the tag for AEAD ciphers.
10081084 * Currently supported with GCM and ChaCha20+Poly1305.
1009- * This must be called after mbedtls_cipher_finish().
1085+ * This must be called after mbedtls_cipher_finish()
1086+ * or mbedtls_cipher_finish_padded().
10101087 *
10111088 * \param ctx The generic cipher context. This must be initialized.
10121089 * \param tag The buffer holding the tag. This must be a readable
0 commit comments