diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-11-09 10:31:25 -0500 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-11-09 10:33:39 -0500 |
commit | a24c5f71df9c5e3258789c2b1ade492b214509a4 (patch) | |
tree | 3f336e279aaf1f6907c8d1f111c6acd1b12e40d3 /spec/intro | |
parent | 38fa996c1cd8691cbd57b8fab543e74b33501fe3 (diff) | |
download | torspec-a24c5f71df9c5e3258789c2b1ade492b214509a4.tar.gz torspec-a24c5f71df9c5e3258789c2b1ade492b214509a4.zip |
Start a "conventions" section to span all the specs
It's short for now, but we will extract more and more things from
the rest of the specifications as we continue editing.
Diffstat (limited to 'spec/intro')
-rw-r--r-- | spec/intro/conventions.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/spec/intro/conventions.md b/spec/intro/conventions.md new file mode 100644 index 0000000..3563a33 --- /dev/null +++ b/spec/intro/conventions.md @@ -0,0 +1,77 @@ +# Notation and conventions + +These conventions apply, +at least in theory, +to all of the specification documents +unless stated otherwise. + +> Remember, our specification documents +> were once a collection of separate text files, +> written separately +> and edited over the course of years. +> +> While we are trying (as of 2023) +> to edit them into consistency, +> you should be aware that these conventions +> are not now followed uniformly everywhere. + +## MUST, SHOULD, and so on {#rfc2119} + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in +[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## Data lengths {#data-lengths} + +Unless otherwise stated, +all lengths are given as a number of 8-bit bytes. + +> All bytes are 8 bits long. +> We sometimes call them "octets"; +> the terms as used here are interchangeable. + +When referring to longer lengths, +we use [SI binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix) +(as in "kibibytes", "mebibytes", and so on) +to refer unambiguously to increments of 1024<sup>X</sup> bytes. + +> If you encounter a reference +> to "kilobytes", "megabytes", or so on, +> you cannot safely infer whether the author intended +> a decimal (1000<sup>N</sup>) or binary (1024<sup>N</sup>) interpretation. +> In these cases, it is better to revise the specifications. + +<a id="tor-spec.txt-0.1.1"></a> + +## Integer encoding {#integers} + +Unless otherwise stated, +all multi-byte integers are encoded +in big-endian ("network") order. + +> For example, 4660 (0x1234), +> when encoded as a two-byte integer, +> is the byte 0x12 followed by the byte 0x34. (\[12 34\]) +> +> When encoded as a four-byte integer, +> it is the byte 0x00, the byte 0x00, the byte 0x12, and the byte 0x34. +> (\[00 00 12 34\]). + +## Notation {#notation} + +### Binary literals {#binary-literals} + +When we write a series of one-byte hexadecimal literals +in square brackets, +it represents a multi-byte binary string. + +> For example, +> `[6f 6e 69 6f 6e 20 72 6f 75 74 69 6e 67]` +> is a 13-byte sequence representing the unterminated ASCII string, +> `onion routing`. + + + + + |