diff options
Diffstat (limited to 'spec')
| -rw-r--r-- | spec/STYLE.md | 2 | ||||
| -rw-r--r-- | spec/back-matter.md | 10 | ||||
| -rw-r--r-- | spec/guard-spec/algorithm.md | 4 | ||||
| -rw-r--r-- | spec/rend-spec/introduction-protocol.md | 4 | ||||
| -rw-r--r-- | spec/tor-spec/create-created-cells.md | 16 | ||||
| -rw-r--r-- | spec/tor-spec/negotiating-channels.md | 48 | ||||
| -rw-r--r-- | spec/tor-spec/routing-relay-cells.md | 2 | ||||
| -rw-r--r-- | spec/tor-spec/subprotocol-versioning.md | 6 |
8 files changed, 47 insertions, 45 deletions
diff --git a/spec/STYLE.md b/spec/STYLE.md index 102b786..74388c3 100644 --- a/spec/STYLE.md +++ b/spec/STYLE.md @@ -133,7 +133,7 @@ for more information about how.) If you want to link to a specific section within a file, make sure that the section has a defined anchor that makes sense. -The syntax to define [heading ids] in mdbook looks like this: +The syntax to define heading ids in mdbook looks like this: `## Heading with a long title that you want shorter name for { #shortname }` diff --git a/spec/back-matter.md b/spec/back-matter.md index 6a50633..90ddea2 100644 --- a/spec/back-matter.md +++ b/spec/back-matter.md @@ -55,12 +55,14 @@ see the ## Editing advice -To edit these specs, clone the [git repository] and edit the -appropriate file in the [`spec` directory]. These files will match +To edit these specs, clone the +[git repository](https://gitlab.torproject.org/tpo/core/torspec/) +and edit the +appropriate file in the `spec` directory. These files will match the URLs of their corresponding pages, so if you want to edit -[`tor-spec/flow-control.html`], +`tor-spec/flow-control.html`, you'll be looking for a file -called [`spec/tor-spec/flow-control.md`]. +called `spec/tor-spec/flow-control.md`. We have started a [style guide](./STYLE.md) for writing new parts of this spec; as of 2023 it is quite preliminary. You should feel free to diff --git a/spec/guard-spec/algorithm.md b/spec/guard-spec/algorithm.md index 1db72f5..ba1c725 100644 --- a/spec/guard-spec/algorithm.md +++ b/spec/guard-spec/algorithm.md @@ -407,11 +407,11 @@ When we want to build a circuit, and we need to pick a guard: When selecting a guard according to this approach, its circuit is `<usable_on_completion>`. - [Note: We do not use {is_pending} on primary guards, since we + \[Note: We do not use {is_pending} on primary guards, since we are willing to try to build multiple circuits through them before we know for sure whether they work, and since we will not use any non-primary guards until we are sure that the - primary guards are all down. (XX is this good?)] + primary guards are all down. (XX is this good?)\] * Otherwise, if the ordered intersection of {CONFIRMED_GUARDS} and {USABLE_FILTERED_GUARDS} is nonempty, return the first diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 60e5a40..dee054f 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -534,14 +534,14 @@ prop327. If the service requires the PROOF_OF_WORK extension but received an INTRODUCE1 cell without any embedded proof-of-work, the service SHOULD consider this cell as a zero-effort introduction for the purposes of the priority queue (see -section [INTRO_QUEUE] of prop327). +section \[INTRO_QUEUE\] of prop327). (TODO: We should have a proof-of-work.md to fold in prop327. For now, just point to the proposal.) #### Subprotocol Request -[RESERVED] +\[RESERVED\] EXT_FIELD_TYPE: diff --git a/spec/tor-spec/create-created-cells.md b/spec/tor-spec/create-created-cells.md index 965cad1..b5cf224 100644 --- a/spec/tor-spec/create-created-cells.md +++ b/spec/tor-spec/create-created-cells.md @@ -141,10 +141,10 @@ connect to it. Recognized specifiers are: | Value | Description | ----- | ----------- -| [00] | TLS-over-TCP, IPv4 address. A four-byte IPv4 address plus two-byte ORPort. -| [01] | TLS-over-TCP, IPv6 address. A sixteen-byte IPv6 address plus two-byte ORPort. -| [02] | Legacy identity. A 20-byte SHA1 identity fingerprint. At most one may be listed. -| [03] | Ed25519 identity. A 32-byte Ed25519 identity fingerprint. At most one may be listed. +| \[00\] | TLS-over-TCP, IPv4 address. A four-byte IPv4 address plus two-byte ORPort. +| \[01\] | TLS-over-TCP, IPv6 address. A sixteen-byte IPv6 address plus two-byte ORPort. +| \[02\] | Legacy identity. A 20-byte SHA1 identity fingerprint. At most one may be listed. +| \[03\] | Ed25519 identity. A 32-byte Ed25519 identity fingerprint. At most one may be listed. Nodes MUST ignore unrecognized specifiers, and MUST accept multiple instances of specifiers other than 'legacy identity' and @@ -336,7 +336,7 @@ The server's handshake reply is: | `SERVER_KP` | `Y` | `G_LENGTH` bytes | `AUTH` | `H(auth_input, t_mac)` | `H_LENGTH` bytes -The client then checks `Y` is in G<sup>*</sup> [see NOTE below], and computes +The client then checks `Y` is in G<sup>*</sup> \[see NOTE below\], and computes ```text secret_input = EXP(Y,x) | EXP(B,x) | ID | B | X | Y | PROTOID @@ -601,13 +601,13 @@ they may be overridden in the description of individual extensions.) Currently supported extensions are: - * 1 -- `CC_FIELD_REQUEST` [Client to server] + * 1 -- `CC_FIELD_REQUEST` \[Client to server\] Contains an empty payload. Signifies that the client wants to use the extended congestion control described in proposal 324. - * 2 -- `CC_FIELD_RESPONSE` [Server to client] + * 2 -- `CC_FIELD_RESPONSE` \[Server to client\] Indicates that the relay will use the congestion control of proposal 324, as requested by the client. One byte @@ -615,7 +615,7 @@ Currently supported extensions are: `sendme_inc [1 byte]` - * 3 -- Subprotocol Request [Client to Server] + * 3 -- Subprotocol Request \[Client to Server\] (RESERVED) Tells the endpoint what protocol version to use on the circuit (prop346). diff --git a/spec/tor-spec/negotiating-channels.md b/spec/tor-spec/negotiating-channels.md index 1184fd8..1ab3721 100644 --- a/spec/tor-spec/negotiating-channels.md +++ b/spec/tor-spec/negotiating-channels.md @@ -321,34 +321,34 @@ cell, and authenticated the responder. If AuthType is 1 (meaning "RSA-SHA256-TLSSecret"), then the Authentication field of the AUTHENTICATE cell contains the following: -* TYPE: The characters "AUTH0001" [8 octets] -* CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets] -* SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets] +* TYPE: The characters "AUTH0001" \[8 octets\] +* CID: A SHA256 hash of the initiator's RSA1024 identity key \[32 octets\] +* SID: A SHA256 hash of the responder's RSA1024 identity key \[32 octets\] * SLOG: A SHA256 hash of all bytes sent from the responder to the initiator as part of the negotiation up to and including the AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell, - the AUTH_CHALLENGE cell, and any padding cells. [32 octets] + the AUTH_CHALLENGE cell, and any padding cells. \[32 octets\] * CLOG: A SHA256 hash of all bytes sent from the initiator to the responder as part of the negotiation so far; that is, the - VERSIONS cell and the CERTS cell and any padding cells. [32 - octets] -* SCERT: A SHA256 hash of the responder's TLS link certificate. [32 - octets] + VERSIONS cell and the CERTS cell and any padding cells. \[32 + octets\] +* SCERT: A SHA256 hash of the responder's TLS link certificate. \[32 + octets\] * TLSSECRETS: A SHA256 HMAC, using the TLS master secret as the secret key, of the following: - client_random, as sent in the TLS Client Hello - server_random, as sent in the TLS Server Hello - the NUL terminated ASCII string: "Tor V3 handshake TLS cross-certification" - [32 octets] + \[32 octets\] * RAND: A 24 byte value, randomly chosen by the initiator. (In an imitation of SSL3's gmt_unix_time field, older versions of Tor sent an 8-byte timestamp as the first 8 bytes of this field; - new implementations should not do that.) [24 octets] + new implementations should not do that.) \[24 octets\] * SIG: A signature of a SHA256 hash of all the previous fields using the initiator's "Authenticate" key as presented. (As always in Tor, we use OAEP-MGF1 padding; see [Ciphers](./preliminaries.md#ciphers)) - [variable length] + \[variable length\] To check the AUTHENTICATE cell, a responder checks that all fields from TYPE through TLSSECRETS contain their unique @@ -370,31 +370,31 @@ Authentication field of the AuthType cell is as below: Modified values and new fields below are marked with asterisks. -* TYPE: The characters "AUTH0003" [8 octets] -* CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets] -* SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets] -* CID_ED: The initiator's Ed25519 identity key [32 octets] -* SID_ED: The responder's Ed25519 identity key, or all-zero. [32 octets] +* TYPE: The characters "AUTH0003" \[8 octets\] +* CID: A SHA256 hash of the initiator's RSA1024 identity key \[32 octets\] +* SID: A SHA256 hash of the responder's RSA1024 identity key \[32 octets\] +* CID_ED: The initiator's Ed25519 identity key \[32 octets\] +* SID_ED: The responder's Ed25519 identity key, or all-zero. \[32 octets\] * SLOG: A SHA256 hash of all bytes sent from the responder to the initiator as part of the negotiation up to and including the AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell, - the AUTH_CHALLENGE cell, and any padding cells. [32 octets] + the AUTH_CHALLENGE cell, and any padding cells. \[32 octets\] * CLOG: A SHA256 hash of all bytes sent from the initiator to the responder as part of the negotiation so far; that is, the - VERSIONS cell and the CERTS cell and any padding cells. [32 - octets] -* SCERT: A SHA256 hash of the responder's TLS link certificate. [32 - octets] + VERSIONS cell and the CERTS cell and any padding cells. \[32 + octets\] +* SCERT: A SHA256 hash of the responder's TLS link certificate. \[32 + octets\] * TLSSECRETS: The output of an RFC5705 Exporter function on the TLS session, using as its inputs: - The label string "EXPORTER FOR TOR TLS CLIENT BINDING AUTH0003" - The context value equal to the initiator's Ed25519 identity key. - The length 32. - [32 octets] -* RAND: A 24 byte value, randomly chosen by the initiator. [24 octets] + \[32 octets\] +* RAND: A 24 byte value, randomly chosen by the initiator. \[24 octets\] * SIG: A signature of all previous fields using the initiator's Ed25519 authentication key (as in the cert with CertType 6). - [variable length] + \[variable length\] To check the AUTHENTICATE cell, a responder checks that all fields from TYPE through TLSSECRETS contain their unique diff --git a/spec/tor-spec/routing-relay-cells.md b/spec/tor-spec/routing-relay-cells.md index 15a5f20..abe9828 100644 --- a/spec/tor-spec/routing-relay-cells.md +++ b/spec/tor-spec/routing-relay-cells.md @@ -93,4 +93,4 @@ OP receives relay cell from node 1: Stop and process the payload. ``` -[1]: ["Relay cells"](./relay-cells.md#relay-cells) +\[1\]: ["Relay cells"](./relay-cells.md#relay-cells) diff --git a/spec/tor-spec/subprotocol-versioning.md b/spec/tor-spec/subprotocol-versioning.md index 780a337..82b25c4 100644 --- a/spec/tor-spec/subprotocol-versioning.md +++ b/spec/tor-spec/subprotocol-versioning.md @@ -162,7 +162,7 @@ Current versions are as follows. 0.4.7.3-alpha. This adds a new CREATE2 cell type. See proposal 332 and [The "ntor-v3" handshake](./create-created-cells.md#ntor-v3) for more details. - * "5" -- [RESERVED] support the ntorv3 subprotocol request extension (prop346) + * "5" -- \[RESERVED\] support the ntorv3 subprotocol request extension (prop346) allowing a client to request what features to be used on a circuit. <a id="tor-spec.txt-9.4"></a> @@ -266,7 +266,7 @@ These correspond more or less with consensus methods. Describes the padding capabilities of the relay. - * "1" -- [DEFUNCT] Relay supports circuit-level padding. This version MUST NOT + * "1" -- \[DEFUNCT\] Relay supports circuit-level padding. This version MUST NOT be used as it was also enabled in relays that don't actually support circuit-level padding. Advertised by Tor versions from tor-0.4.0.1-alpha and only up to and including tor-0.4.1.4-rc. @@ -303,6 +303,6 @@ in order to split traffic across multiple paths. Describes the UDP protocol capabilities of a relay. - * "1" -- [RESERVED] supports UDP by an Exit as in the relay command + * "1" -- \[RESERVED\] supports UDP by an Exit as in the relay command CONNECT_UDP, CONNECTED_UDP and DATAGRAM. See proposal 339 for more details. (Not yet advertised, reserved) |