From 2ddd6a2f2522270333f79d5cf92e302115c5cd13 Mon Sep 17 00:00:00 2001
From: Ben Taylor <ben.taylor@linaro.org>
Date: Tue, 2 Jun 2026 13:50:32 +0100
Subject: [PATCH] Improve comments and guards

Signed-off-by: Ben Taylor <ben.taylor@linaro.org>
---
 include/mbedtls/chachapoly.h | 9 +++++++++
 include/psa/crypto.h         | 2 ++
 library/chacha20_internal.h  | 2 ++
 library/chachapoly.c         | 2 ++
 4 files changed, 15 insertions(+)

diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h
index 3dc21e380b..7faf7cd415 100644
--- a/include/mbedtls/chachapoly.h
+++ b/include/mbedtls/chachapoly.h
@@ -227,6 +227,9 @@ int mbedtls_chachapoly_update_aad(mbedtls_chachapoly_context *ctx,
  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
  *                  if the operation has not been started or has been
  *                  finished.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA
+ *                  if processing \p len bytes would make the 32-bit block
+ *                  counter wrap.
  * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_chachapoly_update(mbedtls_chachapoly_context *ctx,
@@ -280,6 +283,9 @@ int mbedtls_chachapoly_finish(mbedtls_chachapoly_context *ctx,
  *                  is written. This must not be \c NULL.
  *
  * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA
+ *                  if processing \p length bytes would make the 32-bit block
+ *                  counter wrap.
  * \return          A negative error code on failure.
  */
 int mbedtls_chachapoly_encrypt_and_tag(mbedtls_chachapoly_context *ctx,
@@ -314,6 +320,9 @@ int mbedtls_chachapoly_encrypt_and_tag(mbedtls_chachapoly_context *ctx,
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
  *                  if the data was not authentic.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA
+ *                  if processing \p length bytes would make the 32-bit block
+ *                  counter wrap.
  * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_chachapoly_auth_decrypt(mbedtls_chachapoly_context *ctx,
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2fe9f35ec3..34a622a17a 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2470,6 +2470,8 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  * psa_aead_set_nonce() or psa_aead_generate_nonce().
  *
  * - For #PSA_ALG_CCM, calling this function is required.
+ * - For #PSA_ALG_CHACHA20_POLY1305, the plaintext length must not
+ *   exceed `UINT32_MAX * 64` bytes.
  * - For the other AEAD algorithms defined in this specification, calling
  *   this function is not required.
  * - For vendor-defined algorithm, refer to the vendor documentation.
diff --git a/library/chacha20_internal.h b/library/chacha20_internal.h
index 7b2a062a99..487d536007 100644
--- a/library/chacha20_internal.h
+++ b/library/chacha20_internal.h
@@ -15,7 +15,9 @@
 
 #include "mbedtls/chacha20.h"
 
+#if !defined(MBEDTLS_CHACHA20_ALT)
 int mbedtls_chacha20_check_counter_wrap(const mbedtls_chacha20_context *ctx,
                                         size_t size);
+#endif /* !MBEDTLS_CHACHA20_ALT */
 
 #endif /* MBEDTLS_CHACHA20_INTERNAL_H */
diff --git a/library/chachapoly.c b/library/chachapoly.c
index 5cda8d6b7e..c43b930c0f 100644
--- a/library/chachapoly.c
+++ b/library/chachapoly.c
@@ -167,10 +167,12 @@ int mbedtls_chachapoly_update(mbedtls_chachapoly_context *ctx,
         return MBEDTLS_ERR_CHACHAPOLY_BAD_STATE;
     }
 
+#if !defined(MBEDTLS_CHACHA20_ALT)
     ret = mbedtls_chacha20_check_counter_wrap(&ctx->chacha20_ctx, len);
     if (ret != 0) {
         return ret;
     }
+#endif /* !MBEDTLS_CHACHA20_ALT */
 
     if (ctx->state == CHACHAPOLY_STATE_AAD) {
         ctx->state = CHACHAPOLY_STATE_CIPHERTEXT;