commit 0f038ca4fa4c175d427251838cfee6fb6d6b9e2f Author: Yawning Angel <yawning@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.