From 0f038ca4fa4c175d427251838cfee6fb6d6b9e2f Mon Sep 17 00:00:00 2001
From: Yawning Angel <yawning@torproject.org>
Date: Wed, 14 Jan 2015 20:49:56 +0000
Subject: [PATCH] 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.
--
GitLab