Expand upon a Nonce and how important it is

docs/secret.rst

@@ -42,18 +42,45 @@ Example
     plaintext = box.decrypt(ciphertext, nonce)
 
 
-Usage Information
------------------
-
-* :class:`~nacl.secret.SecretBox` requires a 32 byte key that must be kept
-  secret. It is the combination to your "safe" and anyone with this key will
-  be able to decrypt the data.
-* :class:`~nacl.secret.SecretBox` requires a new 24 bytes nonce with every
-  encrypted message. This nonce is *not* secret and be freely transfered or
-  stored in plaintext alongside the ciphertext. However it is absolutely
-  imperative that you **NEVER** reuse a nonce with the same key. Reusing the
-  nonce with the same key provides enough information for an attacker
-  to decrypt any and all messages made with your key.
+Requirements
+------------
+
+Key
+~~~
+
+The 32 bytes key given to :class:`~nacl.secret.SecretBox` must be kept secret.
+It is the combination to your "safe" and anyone with this key will be able to
+decrypt the data, or encrypt new data.
+
+
+Nonce
+~~~~~
+
+The 24 bytes nonce (Number used once) 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.
+
+Both the sender and the receiver should record every nonce both that they've
+used and they've received from the other. They should reject any message which
+reuses a nonce and they should make absolutely sure never to reuse a nonce. It
+is not enough to simply use a random value and hope that it's not being reused
+(simply generating random values would open up the system to a
+`Birthday Attack <https://en.wikipedia.org/wiki/Birthday_attack>`_).
+
+One good method of generating nonces is for each person to pick a unique prefix,
+for example ``b"p1"`` and ``b"p2"``. When each person generates a nonce they
+prefix it, so instead of ``nacl.random(24)`` you'd do ``b"p1" + nacl.random(22)``.
+This prefix serves as a guarantee that no two messages from different people
+will inadvertently overlap nonces while in transit. They should still record
+every nonce they've personally used and every nonce they've received to prevent
+reuse or replays.
 
 
 Reference