Merge branch 'tor-spec-links' into 'main'

tor-spec: replace Section x.y.z with links

See merge request tpo/core/torspec!192

12 files changed, 38 insertions, 31 deletions

diff --git a/spec/padding-spec/circuit-level-padding.md b/spec/padding-spec/circuit-level-padding.md
index 33ecfc3..086d0f8 100644
--- a/spec/padding-spec/circuit-level-padding.md
+++ b/spec/padding-spec/circuit-level-padding.md
@@ -1,6 +1,6 @@
 <a id="padding-spec.txt-3"></a>
 
-# Circuit-level padding
+# Circuit-level padding {#circuit-level-padding}
 
 The circuit padding system in Tor is an extension of the WTF-PAD
 event-driven state machine design\[15\]. At a high level, this design places
diff --git a/spec/tor-spec/cell-packet-format.md b/spec/tor-spec/cell-packet-format.md
index 55eaf2b..b0533dd 100644
--- a/spec/tor-spec/cell-packet-format.md
+++ b/spec/tor-spec/cell-packet-format.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-3"></a>
 
-# Cell Packet format
+# Cell Packet format{#cell-packet-format}
 
 The basic unit of communication for onion routers and onion
 proxies is a fixed-width "cell".
diff --git a/spec/tor-spec/channels.md b/spec/tor-spec/channels.md
index 9495fe4..60b871d 100644
--- a/spec/tor-spec/channels.md
+++ b/spec/tor-spec/channels.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-2"></a>
 
-# Connections
+# Connections{#connections}
 
 Connections between two Tor relays, or between a client and a relay,
 use TLS/SSLv3 for link authentication and encryption.  All
@@ -46,7 +46,7 @@ party sending a two-certificate chain as in "certificates up-front".
 The initiator's ClientHello MUST include at least one ciphersuite not in
 the list above -- that's how the initiator indicates that it can
 handle this handshake.  For other considerations on the initiator's
-ClientHello, see section 2.1 below.
+ClientHello, see [Picking TLS ciphersuites](#picking-tls-ciphersuites}.
 
 In "in-protocol" (a.k.a. "the v3 handshake"), the initiator sends no
 certificates, and the
@@ -139,7 +139,8 @@ OPs alike if their certificates were missing or malformed.\]
 Once a TLS connection is established, the two sides send cells
 (specified below) to one another.  Cells are sent serially.  Standard
 cells are CELL_LEN(link_proto) bytes long, but variable-length cells
-also exist; see Section 3.  Cells may be sent embedded in TLS records
+also exist; see [Cell Packet format](./cell-packet-format.md#cell-packet-format).
+Cells may be sent embedded in TLS records
 of any size or divided across TLS records, but the framing of TLS
 records MUST NOT leak information about the type or contents of the
 cells.
@@ -160,7 +161,7 @@ of the above handshake variants.
 
 <a id="tor-spec.txt-2.1"></a>
 
-## Picking TLS ciphersuites
+## Picking TLS ciphersuites {#picking-tls-ciphersuites}
 
 Clients SHOULD send a ciphersuite list chosen to emulate some popular
 web browser or other program common on the internet. Clients may send
diff --git a/spec/tor-spec/create-created-cells.md b/spec/tor-spec/create-created-cells.md
index c27cc45..453d4b0 100644
--- a/spec/tor-spec/create-created-cells.md
+++ b/spec/tor-spec/create-created-cells.md
@@ -195,7 +195,8 @@ of each type.
 
 After checking relay identities, extending ORs generate a
 CREATE/CREATE2 cell from the contents of the EXTEND/EXTEND2 cell.
-See section 5.3 for details.
+See [Creating circuits](./#creating-circuits.md#creating-circuits)
+for details.
 
 The payload of an EXTENDED cell is the same as the payload of a
 CREATED cell.
@@ -212,7 +213,7 @@ other cases, clients SHOULD use EXTEND2.
 
 When generating an EXTEND2 cell, clients SHOULD include the target's
 Ed25519 identity whenever the target has one, and whenever the
-target supports LinkAuth subprotocol version "3". (See section 9.2.)
+target supports LinkAuth subprotocol version "3". (See [LinkAuth](./subprotocol-versioning.md#link-auth)).
 
 When encoding a non-TAP handshake in an EXTEND cell, clients SHOULD
 use the format with 'client handshake type tag'.
diff --git a/spec/tor-spec/creating-circuits.md b/spec/tor-spec/creating-circuits.md
index 23e5a83..ec595b0 100644
--- a/spec/tor-spec/creating-circuits.md
+++ b/spec/tor-spec/creating-circuits.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-5.3"></a>
 
-# Creating circuits
+# Creating circuits{#creating-circuits}
 
 When creating a circuit through the network, the circuit creator
 (OP) performs the following steps:
diff --git a/spec/tor-spec/flow-control.md b/spec/tor-spec/flow-control.md
index 83ed58a..bf1abe2 100644
--- a/spec/tor-spec/flow-control.md
+++ b/spec/tor-spec/flow-control.md
@@ -33,7 +33,7 @@ information. See proposal 111 for details.
 Link padding can be created by sending PADDING or VPADDING cells
 along the connection; relay cells of type "DROP" can be used for
 long-range padding.  The payloads of PADDING, VPADDING, or DROP
-cells are filled with padding bytes. See Section 3.
+cells are filled with padding bytes. See [Cell Packet format](./cell-packet-format#cell-packet-format).
 
 If the link protocol is version 5 or higher, link level padding is
 enabled as per padding-spec.txt. On these connections, clients may
diff --git a/spec/tor-spec/negotiating-channels.md b/spec/tor-spec/negotiating-channels.md
index 29ad91f..f5cd610 100644
--- a/spec/tor-spec/negotiating-channels.md
+++ b/spec/tor-spec/negotiating-channels.md
@@ -7,23 +7,23 @@ After Tor instances negotiate handshake with either the "renegotiation" or
 the Tor connection and make it "open" and usable for circuits.
 
 When the renegotiation handshake is used, both parties immediately
-send a VERSIONS cell (4.1 below), and after negotiating a link
-protocol version (which will be 2), each send a NETINFO cell (4.5
-below) to confirm their addresses and timestamps.  No other intervening
+send a [VERSIONS cell](#VERSIONS-cell), and after negotiating a link
+protocol version (which will be 2), each send a [NETINFO cell](#NETINFO-cells)
+to confirm their addresses and timestamps.  No other intervening
 cell types are allowed.
 
 When the in-protocol handshake is used, the initiator sends a
 VERSIONS cell to indicate that it will not be renegotiating.  The
-responder sends a VERSIONS cell, a CERTS cell (4.2 below) to give the
+responder sends a VERSIONS cell, a [CERTS cell](#CERTS-cells) to give the
 initiator the certificates it needs to learn the responder's
-identity, an AUTH_CHALLENGE cell (4.3) that the initiator must include
-as part of its answer if it chooses to authenticate, and a NETINFO
-cell (4.5).  As soon as it gets the CERTS cell, the initiator knows
+identity, an [AUTH_CHALLENGE cell](#AUTH-CHALLENGE-cells) that the initiator must include
+as part of its answer if it chooses to authenticate, and a
+[NETINFO cell](#NETINFO-cells).  As soon as it gets the CERTS cell, the initiator knows
 whether the responder is correctly authenticated.  At this point the
 initiator behaves differently depending on whether it wants to
 authenticate or not. If it does not want to authenticate, it MUST
 send a NETINFO cell.  If it does want to authenticate, it MUST send a
-CERTS cell, an AUTHENTICATE cell (4.4), and a NETINFO.  When this
+CERTS cell, an [AUTHENTICATE cell](#AUTHENTICATE-cells), and a NETINFO.  When this
 handshake is in use, the first cell must be VERSIONS, VPADDING, or
 AUTHORIZE, and no other cell type is allowed to intervene besides
 those specified, except for VPADDING cells.
@@ -41,7 +41,7 @@ the in-protocol handshake.\]
 
 There are multiple instances of the Tor link connection protocol.  Any
 connection negotiated using the "certificates up front" handshake (see
-section 2 above) is "version 1".  In any connection where both parties
+[Connections](./channels.md#connections)) is "version 1".  In any connection where both parties
 have behaved as in the "renegotiation" handshake, the link protocol
 version must be 2.  In any connection where both parties have behaved
 as in the "in-protocol" handshake, the link protocol must be 3 or higher.
diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md
index ce339b2..add1f42 100644
--- a/spec/tor-spec/relay-cells.md
+++ b/spec/tor-spec/relay-cells.md
@@ -75,11 +75,13 @@ decrypted relay payload is zero, the 'digest' field is computed as
 the first four bytes of the running digest of all the bytes that have
 been destined for this hop of the circuit or originated from this hop
 of the circuit, seeded from Df or Db respectively (obtained in
-section 5.2 above), and including this RELAY cell's entire payload
+[Setting circuit keys](./setting-circuit-keys.md#setting-circuit-keys)),
+and including this RELAY cell's entire payload
 (taken with the digest field set to zero).  Note that these digests
 _do_ include the padding bytes at the end of the cell, not only those up
 to "Len".  If the digest is correct, the cell is considered "recognized"
-for the purposes of decryption (see section 5.5 above).
+for the purposes of decryption (see
+[Routing relay cells](./routing-relay-cells.md#routing-relay-cells)).
 
 (The digest does not include any bytes from relay cells that do
 not start or end at this hop of the circuit. That is, it does not
@@ -94,13 +96,13 @@ entire circuit rather than a particular stream use a StreamID of zero
 -- they are marked in the table above as "\[control\]" style
 cells. (Sendme cells are marked as "sometimes control" because they
 can include a StreamID or not depending on their purpose -- see
-Section 7.)
+[Flow control](./flow-control.md#flow-control).)
 
 The 'Length' field of a relay cell contains the number of bytes in
 the relay payload which contain real payload data. The remainder of
 the unencrypted payload is padded with padding bytes. Implementations
 handle padding bytes of unencrypted relay cells as they do padding
-bytes for other cell types; see Section 3.
+bytes for other cell types; see [Cell Packet format](./cell-packet-format.md#cell-packet-format).
 
 The 'Padding' field is used to make relay cell contents unpredictable, to
 avoid certain attacks (see proposal 289 for rationale). Implementations
diff --git a/spec/tor-spec/routing-relay-cells.md b/spec/tor-spec/routing-relay-cells.md
index ff81e27..55520d9 100644
--- a/spec/tor-spec/routing-relay-cells.md
+++ b/spec/tor-spec/routing-relay-cells.md
@@ -48,14 +48,15 @@ with the stream cipher, as follows:
 ```
 
 The OR then decides whether it recognizes the relay cell, by
-inspecting the payload as described in section 6.1 below.  If the OR
+inspecting the payload as described in [Relay cells](./relay-cells.md#relay-cells).  If the OR
 recognizes the cell, it processes the contents of the relay cell.
 Otherwise, it passes the decrypted relay cell along the circuit if
 the circuit continues.  If the OR at the end of the circuit
 encounters an unrecognized relay cell, an error has occurred: the OR
 sends a DESTROY cell to tear down the circuit.
 
-For more information, see section 6 below.
+For more information, see
+[Application connections and stream management](./streams.md#application-connections-and-stream-management).
 
 <a id="tor-spec.txt-5.5.3"></a>
 
diff --git a/spec/tor-spec/setting-circuit-keys.md b/spec/tor-spec/setting-circuit-keys.md
index 95a5b27..6cea0f3 100644
--- a/spec/tor-spec/setting-circuit-keys.md
+++ b/spec/tor-spec/setting-circuit-keys.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-5.2"></a>
 
-# Setting circuit keys
+# Setting circuit keys{#setting-circuit-keys}
 
 <a id="tor-spec.txt-5.2.1"></a>
 
diff --git a/spec/tor-spec/subprotocol-versioning.md b/spec/tor-spec/subprotocol-versioning.md
index b0984b6..ffd17a6 100644
--- a/spec/tor-spec/subprotocol-versioning.md
+++ b/spec/tor-spec/subprotocol-versioning.md
@@ -68,25 +68,26 @@ protocol versions correspond 1:1 to those versions.
 Two Tor instances can make a connection to each other only if they have at
 least one link protocol in common.
 
-The current "link" versions are: "1" through "5". See section 4.1 for more
+The current "link" versions are: "1" through "5". See
+[Negotiating versions with VERSIONS cells](./negotiating-channels.md#VERSIONS-cells) for more
 information. All current Tor versions support "1-3"; versions from
 0.2.4.11-alpha and on support "1-4"; versions from 0.3.1.1-alpha and on
 support "1-5". Eventually we will drop "1" and "2".
 
 <a id="tor-spec.txt-9.2"></a>
 
-## "LinkAuth"
+## "LinkAuth" {#link-auth}
 
 LinkAuth protocols correspond to varieties of Authenticate cells used for
 the v3+ link protocols.
 
 Current versions are:
 
-"1" is the RSA link authentication described in section 4.4.1 above.
+"1" is the RSA link authentication described in [Link authentication type 1: RSA-SHA256-TLSSecret](./negotiating-channels.md#RSA-SHA256-TLSSecret).
 
 "2" is unused, and reserved by proposal 244.
 
-"3" is the ed25519 link authentication described in 4.4.2 above.
+"3" is the ed25519 link authentication described in [Link authentication type 3: Ed25519-SHA256-RFC5705](./negotiating-channels.md#Ed25519-SHA256-RFC5705).
 
 <a id="tor-spec.txt-9.3"></a>
 
diff --git a/spec/tor-spec/tearing-down-circuits.md b/spec/tor-spec/tearing-down-circuits.md
index 05e6444..0609307 100644
--- a/spec/tor-spec/tearing-down-circuits.md
+++ b/spec/tor-spec/tearing-down-circuits.md
@@ -35,7 +35,8 @@ Upon receiving an outgoing DESTROY cell, an OR frees resources
 associated with the corresponding circuit. If it's not the end of
 the circuit, it sends a DESTROY cell for that circuit to the next OR
 in the circuit. If the node is the end of the circuit, then it tears
-down any associated edge connections (see section 6.1).
+down any associated edge connections (see
+[Calculating the 'Digest' field](./relay-cells.md#digest-field)).
 
 After a DESTROY cell has been processed, an OR ignores all data or
 destroy cells for the corresponding circuit.