Clarify calling sequence in the Cipher layer
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index 44553e7..54fd53d 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -449,6 +449,18 @@
* \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 @@
/**
* \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