[tor-commits] [obfs4/master] Document the obfs4 NaCl secretbox nonce generation.

[yawning at torproject.org]

commit 0f038ca4fa4c175d427251838cfee6fb6d6b9e2f
Author: Yawning Angel <yawning at torproject.org>
Date:   Wed Jan 14 20:49:56 2015 +0000

    Document the obfs4 NaCl secretbox nonce generation.
    
    Forgot to include this in the spec, though it was documented as a
    comment in the framing code.
---
 doc/obfs4-spec.txt |   11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/obfs4-spec.txt b/doc/obfs4-spec.txt
index 0e844a1..7d54ffc 100644
--- a/doc/obfs4-spec.txt
+++ b/doc/obfs4-spec.txt
@@ -269,6 +269,17 @@
    The maximum allowed frame length is 1448 bytes, which allows up to 1427
    bytes of useful payload to be transmitted per "frame".
 
+   The NaCl secretbox (Poly1305/XSalsa20) nonce format is:
+
+      uint8_t[24] prefix (Fixed)
+      uint64_t    counter (Big endian)
+
+   The counter is initialized to 1, and is incremented on each frame.  Since
+   the protocol is designed to be used over a reliable medium, the nonce is not
+   transmitted over the wire as both sides of the conversation know the prefix
+   and the initial counter value.  It is imperative that the counter does not
+   wrap, and sessions MUST terminate before 2^64 frames are sent.
+
    If unsealing a secretbox ever fails (due to a Tag mismatch), implementations
    MUST drop the connection.