chachapoly: warn against piecewise decryption
diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h
index 249dba1..be10cfd 100644
--- a/include/mbedtls/chachapoly.h
+++ b/include/mbedtls/chachapoly.h
@@ -89,13 +89,31 @@
* \c mbedtls_chachapoly_crypt_and_tag() or
* \c mbedtls_chachapoly_auth_decrypt().
*
- * In order to encrypt or decrypt messages piecewise, for each
+ * In order to encrypt messages piecewise, for each
* message you should make a call to
* \c mbedtls_chachapoly_starts(), then 0 or more calls to
* \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
* \c mbedtls_chachapoly_update(), then one call to
* \c mbedtls_chachapoly_finish().
*
+ * \warning Decryption with the piecewise API is discouraged! Always
+ * use \c mbedtls_chachapoly_auth_decrypt() when possible!
+ *
+ * If however this is not possible because the data is too
+ * large to fit in memory, you need to:
+ *
+ * - call \c mbedtls_chachapoly_starts() and (if needed)
+ * \c mbedtls_chachapoly_update_aad() as above,
+ * - call \c mbedtls_chachapoly_update() multiple times and
+ * ensure its output (the plaintext) is NOT used in any other
+ * way than placing it in temporary storage at this point,
+ * - call \c mbedtls_chachapoly_finish() to compute the
+ * authentication tag and compared it in constant time to the
+ * tag received with the ciphertext.
+ *
+ * If the tags are not equal, you must immediately discard
+ * all previous outputs of \c mbedtls_chachapoly_update(),
+ * otherwise you can now safely use the plaintext.
*
* \param ctx The ChachaPoly context to initialize.
*/
@@ -134,10 +152,13 @@
* \note If the context is being used for AAD only (no data to
* encrypt or decrypt) then \p mode can be set to any value.
*
+ * \warning Decryption with the piecewise API is discouraged, see the
+ * warning on \c mbedtls_chachapoly_init().
+ *
* \param ctx The ChaCha20-Poly1305 context.
* \param nonce The nonce/IV to use for the message. Must be 12 bytes.
* \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
- * #MBEDTLS_CHACHAPOLY_DECRYPT.
+ * #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
@@ -169,6 +190,9 @@
* been processed by \c mbedtls_chachapoly_update(),
* or if the context has been finished.
*
+ * \warning Decryption with the piecewise API is discouraged, see the
+ * warning on \c mbedtls_chachapoly_init().
+ *
* \param ctx The ChaCha20-Poly1305 context to use.
* \param aad_len The length (in bytes) of the AAD. The length has no
* restrictions.
@@ -200,6 +224,9 @@
* this function 0 times, if no data is to be encrypted
* or decrypted.
*
+ * \warning Decryption with the piecewise API is discouraged, see the
+ * warning on \c mbedtls_chachapoly_init().
+ *
* \param ctx The ChaCha20-Poly1305 context to use.
* \param len The length (in bytes) of the data to encrypt or decrypt.
* \param input The buffer containing the data to encrypt or decrypt.
@@ -227,6 +254,9 @@
* \param ctx The ChaCha20-Poly1305 context to use.
* \param mac The buffer to where the 128-bit (16 bytes) MAC is written.
*
+ * \warning Decryption with the piecewise API is discouraged, see the
+ * warning on \c mbedtls_chachapoly_init().
+ *
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if \p ctx or \p mac are NULL.