From 3349d033f51cc8b57e357bafdbb6700205e2d058 Mon Sep 17 00:00:00 2001
From: Brian Warner <warner@lothar.com>
Date: Wed, 25 Jun 2014 16:00:39 -0700
Subject: [PATCH] docs/secret.rst: update text about nonces

---
 docs/secret.rst | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/docs/secret.rst b/docs/secret.rst
index 18f5dde3..797ecefa 100644
--- a/docs/secret.rst
+++ b/docs/secret.rst
@@ -56,19 +56,28 @@ decrypt the data, or encrypt new data.
 Nonce
 ~~~~~
 
-The 24 bytes nonce (`Number used once <https://en.wikipedia.org/wiki/Cryptographic_nonce>`_)
-given to :meth:`~nacl.secret.SecretBox.encrypt` and :meth:`~nacl.secret.SecretBox.decrypt`
-must **NEVER** be reused for a particular key. Reusing the nonce means an
-attacker will have enough information to recover your secret key and encrypt or
-decrypt arbitrary messages. A nonce is not considered secret and may be freely
-transmitted or stored in plaintext alongside the ciphertext.
-
-A nonce does not need to be random, nor does the method of generating them need
-to be secret. A nonce could simply be a counter incremented with each message
-encrypted.
-
-The nonce is long enough that using random bytes from ``nacl.utils.random(24)``
-suffices. A birthday attack would require octillions of nonces before collision.
+The 24-byte nonce (`Number used once <https://en.wikipedia.org/wiki/Cryptographic_nonce>`_)
+given to :meth:`~nacl.secret.SecretBox.encrypt` and
+:meth:`~nacl.secret.SecretBox.decrypt` must **NEVER** be reused for a
+particular key. Reusing a nonce may give an attacker enough information to
+decrypt or forge other messages. A nonce is not considered secret and may be
+freely transmitted or stored in plaintext alongside the ciphertext.
+
+A nonce does not need to be random or unpredictable, nor does the method of
+generating them need to be secret. A nonce could simply be a counter
+incremented with each message encrypted, which can be useful in
+connection-oriented protocols to reject duplicate messages ("replay
+attacks"). A bidirectional connection could use the same key for both
+directions, as long as their nonces never overlap (e.g. one direction always
+sets the high bit to "1", the other always sets it to "0").
+
+If you use a counter-based nonce along with a key that is persisted from one
+session to another (e.g. saved to disk), you must store the counter along
+with the key, to avoid accidental nonce reuse on the next session. For this
+reason, many protocols derive a new key for each session, reset the counter
+to zero with each new key, and never store the derived key or the counter.
+
+You can safely generate random nonces by calling ``nacl.utils.random(SecretBox.NONCE_SIZE)``.
 
 
 Reference
-- 
GitLab