Warn to use a constant-time comparison for MAC and AEAD tag

tf-psa-crypto/drivers/builtin/include/mbedtls/ccm.h

@@ -309,8 +309,6 @@ int mbedtls_ccm_star_auth_decrypt(mbedtls_ccm_context *ctx, size_t length,
  *                  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.
  * \param mode      The operation to perform: #MBEDTLS_CCM_ENCRYPT or
  *                  #MBEDTLS_CCM_DECRYPT or #MBEDTLS_CCM_STAR_ENCRYPT or
@@ -343,8 +341,6 @@ int mbedtls_ccm_starts(mbedtls_ccm_context *ctx,
  *                  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.
  * \param total_ad_len   The total length of additional data in bytes.
  *                       This must be less than `2^16 - 2^8`.
@@ -378,8 +374,6 @@ int mbedtls_ccm_set_lengths(mbedtls_ccm_context *ctx,
  *                  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(), the lengths of the message and
  *                  additional data must have been declared with
@@ -436,8 +430,6 @@ int mbedtls_ccm_update_ad(mbedtls_ccm_context *ctx,
  *                    the last one) then it is correct to use \p output_size
  *                    =\p input_len.
  *
- * \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 the lengths of the message and
  *                      additional data must have been declared with
@@ -474,7 +466,10 @@ 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.
+ * \warning         To verify the tag, call this function, then use
+ *                  mbedtls_ct_memcmp() to compare the actual tag
+ *                  with the expected tag. Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.
  *
  * \param ctx       The CCM context. This must have been started with
  *                  mbedtls_ccm_starts() and the lengths of the message and

tf-psa-crypto/drivers/builtin/include/mbedtls/chachapoly.h

@@ -229,14 +229,19 @@ int mbedtls_chachapoly_update(mbedtls_chachapoly_context *ctx,
                               unsigned char *output);
 
 /**
- * \brief           This function finished the ChaCha20-Poly1305 operation and
- *                  generates the MAC (authentication tag).
+ * \brief           This function finishes the ChaCha20-Poly1305 operation and
+ *                  generates the authentication tag.
  *
  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
- * \param mac       The buffer to where the 128-bit (16 bytes) MAC is written.
+ * \param mac       The buffer to where the 128-bit (16-byte) authentication
+ *                  tag is written.
  *
  * \warning         Decryption with the piecewise API is discouraged, see the
  *                  warning on \c mbedtls_chachapoly_init().
+ *                  If you use this API for decryption, you must call
+ *                  mbedtls_ct_memcmp() to compare \p mac with the
+ *                  expected tag. (Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.)
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
@@ -270,8 +275,8 @@ int mbedtls_chachapoly_finish(mbedtls_chachapoly_context *ctx,
  *                  This pointer can be \c NULL if `ilen == 0`.
  * \param output    The buffer to where the encrypted or decrypted data
  *                  is written. This pointer can be \c NULL if `ilen == 0`.
- * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC
- *                  is written. This must not be \c NULL.
+ * \param tag       The buffer to where the computed 128-bit (16-byte)
+ *                  authentication tag is written. This must not be \c NULL.
  *
  * \return          \c 0 on success.
  * \return          A negative error code on failure.

tf-psa-crypto/drivers/builtin/include/mbedtls/cipher.h

@@ -989,6 +989,9 @@ int mbedtls_cipher_finish(mbedtls_cipher_context_t *ctx,
  *                      Currently supported with GCM and ChaCha20+Poly1305.
  *                      This must be called after mbedtls_cipher_finish().
  *
+ * \warning             When decrypting, call mbedtls_cipher_check_tag()
+ *                      instead of this function.
+ *
  * \param ctx           The generic cipher context. This must be initialized,
  *                      bound to a key, and have just completed a cipher
  *                      operation through mbedtls_cipher_finish() the tag for

tf-psa-crypto/drivers/builtin/include/mbedtls/cmac.h

@@ -165,6 +165,11 @@ int mbedtls_cipher_cmac_reset(mbedtls_cipher_context_t *ctx);
  *                      The CMAC result is calculated as
  *                      output = generic CMAC(cmac key, input buffer).
  *
+ * \warning             To verify a MAC, call this function, then use
+ *                      mbedtls_ct_memcmp() to compare the actual MAC
+ *                      with the expected MAC. Do not use memcmp():
+ *                      that would be vulnerable to timing attacks.
+ *
  * \param cipher_info   The cipher information.
  * \param key           The CMAC key.
  * \param keylen        The length of the CMAC key in bits.

tf-psa-crypto/drivers/builtin/include/mbedtls/gcm.h

@@ -318,6 +318,11 @@ int mbedtls_gcm_update(mbedtls_gcm_context *ctx,
  *                  It wraps up the GCM stream, and generates the
  *                  tag. The tag can have a maximum length of 16 Bytes.
  *
+ * \warning         To verify the tag, call this function, then use
+ *                  mbedtls_ct_memcmp() to compare the actual tag
+ *                  with the expected tag. Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.
+ *
  * \param ctx       The GCM context. This must be initialized.
  * \param tag       The buffer for holding the tag. This must be a writable
  *                  buffer of at least \p tag_len Bytes.

tf-psa-crypto/drivers/builtin/include/mbedtls/md.h

@@ -463,6 +463,11 @@ int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input
  *                  or call mbedtls_md_hmac_reset() to reuse the context with
  *                  the same HMAC key.
  *
+ * \warning         To verify a MAC, call this function, then use
+ *                  mbedtls_ct_memcmp() to compare the actual MAC
+ *                  with the expected MAC. Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.
+ *
  * \param ctx       The message digest context containing an embedded HMAC
  *                  context.
  * \param output    The generic HMAC checksum result.
@@ -502,6 +507,11 @@ int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx);
  *                 The HMAC result is calculated as
  *                 output = generic HMAC(hmac key, input buffer).
  *
+ * \warning         To verify a MAC, call this function, then use
+ *                  mbedtls_ct_memcmp() to compare the actual MAC
+ *                  with the expected MAC. Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.
+ *
  * \param md_info  The information structure of the message-digest algorithm
  *                 to use.
  * \param key      The HMAC secret key.

tf-psa-crypto/drivers/builtin/include/mbedtls/poly1305.h

@@ -108,9 +108,14 @@ int mbedtls_poly1305_update(mbedtls_poly1305_context *ctx,
                             size_t ilen);
 
 /**
- * \brief           This function generates the Poly1305 Message
+ * \brief           This function generates the Poly1305 one-time Message
  *                  Authentication Code (MAC).
  *
+ * \warning         To verify a MAC, call this function, then use
+ *                  mbedtls_ct_memcmp() to compare the actual MAC
+ *                  with the expected MAC. Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.
+ *
  * \param ctx       The Poly1305 context to use for the Poly1305 operation.
  *                  This must be initialized and bound to a key.
  * \param mac       The buffer to where the MAC is written. This must
@@ -123,12 +128,17 @@ int mbedtls_poly1305_finish(mbedtls_poly1305_context *ctx,
                             unsigned char mac[16]);
 
 /**
- * \brief           This function calculates the Poly1305 MAC of the input
- *                  buffer with the provided key.
+ * \brief           This function calculates the Poly1305 one-time MAC
+ *                  of the input buffer with the provided key.
  *
  * \warning         The key must be unique and unpredictable for each
  *                  invocation of Poly1305.
  *
+ * \warning         To verify a MAC, call this function, then use
+ *                  mbedtls_ct_memcmp() to compare the actual MAC
+ *                  with the expected MAC. Do not use memcmp():
+ *                  that would be vulnerable to timing attacks.
+ *
  * \param key       The buffer containing the \c 32 Byte (\c 256 Bit) key.
  * \param ilen      The length of the input data in Bytes.
  *                  Any value is accepted.