From 8a1b2c88060d05865794047958a44f34645b9f84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?=
 <manuel.pegourie-gonnard@arm.com>
Date: Wed, 23 May 2018 13:26:22 +0200
Subject: [PATCH] Update CTR documentation

---
 include/mbedtls/aria.h | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h
index 4bb1fc28a..8e59ffc04 100644
--- a/include/mbedtls/aria.h
+++ b/include/mbedtls/aria.h
@@ -255,19 +255,44 @@ int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
  *
  *             There are two common strategies for managing nonces with CTR:
  *
- *             1. Use a counter starting at 0 or a random value. With this
- *             strategy, this function will increment the counter for you, so
- *             you only need to preserve the \p nonce_counter buffer between
- *             calls. With this strategy, you must not encrypt more than
- *             2**128 blocks of data.
- *             2. Use a randomly-generated \p nonce_counter for each call.
- *             With this strategy, you need to ensure the nonce is generated
- *             in an unbiased way and you must not encrypt more than 2**64
+ *             1. You can handle everything as a single message processed over
+ *             successive calls to this function. In that case, you want to
+ *             set \p nonce_counter and \p nc_off to 0 for the first call, and
+ *             then preserve the values of \p nonce_counter, \p nc_off and \p
+ *             stream_block across calls to this function as they will be
+ *             updated by this function.
+ *
+ *             With this strategy, you must not encrypt more than 2**128
  *             blocks of data.
  *
+ *             2. You can encrypt separate messages by dividing the \p
+ *             nonce_counter buffer in two areas: the first one used for a
+ *             per-message nonce, handled by yourself, and the second one
+ *             updated by this function internally.
+ *
+ *             For example, you might reserve the first 12 bytes for the
+ *             per-message nonce, and the last 4 bytes for internal use. In that
+ *             case, before calling this function on a new message you need to
+ *             set the first 12 bytes of \p nonce_counter to your chosen nonce
+ *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
+ *             stream_block to be ignored). That way, you can encrypt at most
+ *             2**96 messages of up to 2**32 blocks each.
+ *
+ *             The per-message nonce (or information sufficient to reconstruct
+ *             it) needs to be communicated with the ciphertext and must be unique.
+ *             The recommended way to ensure uniqueness is to use a message
+ *             counter. An alternative is to generate random nonces, but this
+ *             limits the number of messages that can be securely encrypted:
+ *             for example, with 96-bit random nonces, you should not encrypt
+ *             more than 2**32 messages with the same key.
+ *
  *             Note that for both stategies, the limit is in number of blocks
  *             and that an ARIA block is 16 bytes.
  *
+ * \warning    Upon return, \p stream_block constains sensitive data. Its
+ *             content must not be written to insecure storage and should be
+ *             securely discarded as soon as it's no longer needed.
+ *
  * \param ctx              The ARIA context to use for encryption or decryption.
  * \param length           The length of the input data.
  * \param nc_off           The offset in the current \p stream_block, for