Make it more explicit that everything in tor-spec is big-endian

Clarify what we mean when we talk about the MSB of a big-endian value.

1 files changed, 13 insertions, 2 deletions

diff --git a/tor-spec.txt b/tor-spec.txt
index 9aea142..b9834bc 100644
--- a/tor-spec.txt
+++ b/tor-spec.txt
@@ -33,10 +33,17 @@ see tor-design.pdf.
    [A0 B1 C2] -- a three-byte sequence, containing the bytes with
    hexadecimal values A0, B1, and C2, in that order.
 
-   All numeric values are encoded in network (big-endian) order.
-
    H(m) -- a cryptographic hash of m.
 
+   We use "byte" and "octet" interchangeably.  Possibly we shouldn't.
+
+0.1.1. Encoding integers
+
+   Unless we explicitly say otherwise below, all numeric values in the
+   Tor protocol are encoded in network (big-endian) order.  So a "32-bit
+   integer" means a big-endian 32-bit integer; a "2-byte" integer means
+   a big-endian 16-bit integer, and so forth.
+
 0.2. Security parameters
 
    Tor uses a stream cipher, a public-key cipher, the Diffie-Hellman
@@ -1277,6 +1284,10 @@ see tor-design.pdf.
 
    The FLAGS value has one or more of the following bits set, where
    "bit 1" is the LSB of the 32-bit value, and "bit 32" is the MSB.
+   (Remember that all values in Tor are big-endian (see 0.1.1 above), so
+   the MSB of a 4-byte value is the MSB of the first byte, and the LSB
+   of a 4-byte value is the LSB of its last byte.)
+
      bit   meaning
       1 -- IPv6 okay.  We support learning about IPv6 addresses and
            connecting to IPv6 addresses.