diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-10-14 18:52:20 -0400 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-10-14 18:53:18 -0400 |
commit | 3457b0720834c8347d8318c1080ebc9486d77300 (patch) | |
tree | b486a3d03fdfae7d98c4e6cf510179cf907c443f /spec | |
parent | a331e9f48790ad4beaba1ee443c5ad8b13d3afb4 (diff) | |
download | torspec-3457b0720834c8347d8318c1080ebc9486d77300.tar.gz torspec-3457b0720834c8347d8318c1080ebc9486d77300.zip |
Add short IDs for most long section names
I've left off sections that are headings for their whole document.
Diffstat (limited to 'spec')
48 files changed, 302 insertions, 424 deletions
diff --git a/spec/bandwidth-file-spec/implementation-details.md b/spec/bandwidth-file-spec/implementation-details.md index 90f84fa..1695793 100644 --- a/spec/bandwidth-file-spec/implementation-details.md +++ b/spec/bandwidth-file-spec/implementation-details.md @@ -4,7 +4,7 @@ <a id="bandwidth-file-spec.txt-2.4.1"></a> -### Writing bandwidth files atomically +### Writing bandwidth files atomically { #write-atomically } To avoid inconsistent reads, implementations SHOULD write bandwidth files atomically. If the file is transferred from another host, it SHOULD be @@ -19,13 +19,13 @@ Torflow does not write bandwidth files atomically. <a id="bandwidth-file-spec.txt-2.4.2"></a> -### Additional KeyValue pair definitions +### Additional KeyValue pair definitions { #key-value-pairs } KeyValue pairs in RelayLines that current implementations generate. <a id="bandwidth-file-spec.txt-2.4.2.1"></a> -#### Simple Bandwidth Scanner +#### Simple Bandwidth Scanner { #sbws } sbws RelayLines contain these keys: diff --git a/spec/bandwidth-file-spec/relay-line-format.md b/spec/bandwidth-file-spec/relay-line-format.md index ec47146..275abc6 100644 --- a/spec/bandwidth-file-spec/relay-line-format.md +++ b/spec/bandwidth-file-spec/relay-line-format.md @@ -1,6 +1,6 @@ <a id="bandwidth-file-spec.txt-2.3"></a> -## Relay Line format +## Relay Line format { #relay-line } It consists of zero or more RelayLines containing relay ids and bandwidths. The relays and their KeyValues are in arbitrary order. diff --git a/spec/bandwidth-file-spec/sample-data.md b/spec/bandwidth-file-spec/sample-data.md index 45bb43f..1a689fd 100644 --- a/spec/bandwidth-file-spec/sample-data.md +++ b/spec/bandwidth-file-spec/sample-data.md @@ -6,7 +6,7 @@ The following has not been obtained from any real measurement. <a id="bandwidth-file-spec.txt-A.1"></a> -## Generated by Torflow +## Generated by Torflow { #torflow } This an example version 1.0.0 document: @@ -18,7 +18,7 @@ node_id=$96C15995F30895689291F455587BD94CA427B6FC bw=189 nick=Test2 measured_at= <a id="bandwidth-file-spec.txt-A.2"></a> -## Generated by sbws version 0.1.0 +## Generated by sbws version 0.1.0 { #sbws-010 } ```text 1523911758 @@ -37,7 +37,7 @@ bw=189 error_circ=0 error_misc=0 error_stream=0 master_key_ed25519=a6a+dZadrQBtf <a id="bandwidth-file-spec.txt-A.3"></a> -## Generated by sbws version 1.0.3 +## Generated by sbws version 1.0.3 { #sbws-103 } ````text 1523911758 @@ -61,7 +61,7 @@ bw=1 bw_mean=199162 bw_median=185675 desc_bw_avg=409600 desc_bw_obs_last=836165 <a id="bandwidth-file-spec.txt-A.3.1"></a> -### When there are not enough eligible measured relays +### When there are not enough eligible measured relays { #sbws-103-not-enough-measured } ```text 1540496079 @@ -82,7 +82,7 @@ software_version=1.0.3 <a id="bandwidth-file-spec.txt-A.4"></a> -## Headers generated by sbws version 1.0.4 +## Headers generated by sbws version 1.0.4 { #sbws-104 } ```text 1523911758 @@ -105,7 +105,7 @@ software_version=1.0.4 <a id="bandwidth-file-spec.txt-A.5"></a> -## Generated by sbws version 1.1.0 +## Generated by sbws version 1.1.0 { #sbws-110 } ```text 1523911758 diff --git a/spec/bandwidth-file-spec/scaling-bandwidths.md b/spec/bandwidth-file-spec/scaling-bandwidths.md index 8d8906e..65bb317 100644 --- a/spec/bandwidth-file-spec/scaling-bandwidths.md +++ b/spec/bandwidth-file-spec/scaling-bandwidths.md @@ -21,7 +21,7 @@ enough already. <a id="bandwidth-file-spec.txt-B.2"></a> -## A linear scaling method +## A linear scaling method { #linear-method } If scaling is required, here is a simple linear bandwidth scaling method, which ensures that all bandwidth votes contain approximately diff --git a/spec/bridgedb-spec.md b/spec/bridgedb-spec.md index 0ce607d..4ced4bd 100644 --- a/spec/bridgedb-spec.md +++ b/spec/bridgedb-spec.md @@ -1,29 +1,7 @@ -BridgeDB specification - -```text - Karsten Loesing - Nick Mathewson - -Table of Contents - - 0. Preliminaries - 1. Importing bridge network statuses and bridge descriptors - 1.1. Parsing bridge network statuses - 1.2. Parsing bridge descriptors - 1.3. Parsing extra-info documents - 2. Assigning bridges to distributors - 3. Giving out bridges upon requests - 4. Selecting bridges to be given out based on IP addresses - 5. Selecting bridges to be given out based on email addresses - 6. Selecting unallocated bridges to be stored in file buckets - 7. Displaying Bridge Information - 8. Writing bridge assignments for statistics -``` +# BridgeDB specification <a id="bridgedb-spec.txt-0"></a> -# Preliminaries - This document specifies how BridgeDB processes bridge descriptor files to learn about new bridges, maintains persistent assignments of bridges to distributors, and decides which bridges to give out upon user @@ -35,7 +13,7 @@ behavior. <a id="bridgedb-spec.txt-1"></a> -# Importing bridge network statuses and bridge descriptors +# Importing bridge network statuses and bridge descriptors { #importing } BridgeDB learns about bridges by parsing bridge network statuses, bridge descriptors, and extra info documents as specified in Tor's @@ -51,7 +29,7 @@ from a Tor instance that did the validation for us. <a id="bridgedb-spec.txt-1.1"></a> -## Parsing bridge network statuses +## Parsing bridge network statuses { #parsing-network-status } Bridge network status documents contain the information of which bridges are known to the bridge authority and which flags the bridge authority @@ -79,7 +57,7 @@ with these flags. <a id="bridgedb-spec.txt-1.2"></a> -## Parsing bridge descriptors +## Parsing bridge descriptors { #parsing-bridge-descriptors } BridgeDB learns about a bridge's most recent IP address and OR port from parsing bridge descriptors. @@ -121,7 +99,7 @@ to the set of bridges to be given out to bridge users. <a id="bridgedb-spec.txt-1.3"></a> -## Parsing extra-info documents +## Parsing extra-info documents { #parsing-extra-info } BridgeDB learns if a bridge supports a pluggable transport by parsing extra-info documents. @@ -148,7 +126,7 @@ Bridges that do not have an associated extra-info entry are not invalid. <a id="bridgedb-spec.txt-2"></a> -# Assigning bridges to distributors +# Assigning bridges to distributors { #assigning-to-distributors } A "distributor" is a mechanism by which bridges are given (or not given) to clients. The current distributors are "email", "https", @@ -170,7 +148,7 @@ distributors change or distributors are disabled entirely. <a id="bridgedb-spec.txt-3"></a> -# Giving out bridges upon requests +# Giving out bridges upon requests { #distributing } Upon receiving a client request, a BridgeDB distributor provides a subset of the bridges assigned to it. @@ -187,7 +165,7 @@ should not be blocked. <a id="bridgedb-spec.txt-4"></a> -# Selecting bridges to be given out based on IP addresses +# Selecting bridges to be given out based on IP addresses { #ip-based } ```text BridgeDB may be configured to support one or more distributors which @@ -379,7 +357,7 @@ proceeds as follows: <a id="bridgedb-spec.txt-6"></a> -# Selecting unallocated bridges to be stored in file buckets +# Selecting unallocated bridges to be stored in file buckets { #unallocated-buckets } > Kaner should have a look at this section. -NM @@ -409,7 +387,7 @@ proceeds as follows: <a id="bridgedb-spec.txt-7"></a> -# Displaying Bridge Information +# Displaying Bridge Information { #formatting } After bridges are selected using one of the methods described in Sections 4 - 6, they are output in one of two formats. Bridges are diff --git a/spec/cert-spec.md b/spec/cert-spec.md index 0b98f75..f78af10 100644 --- a/spec/cert-spec.md +++ b/spec/cert-spec.md @@ -1,25 +1,4 @@ -Ed25519 certificates in Tor - -Table of Contents - -```text - 1. Scope and Preliminaries - 1.1. Signing - 1.2. Integer encoding - 2. Document formats - 2.1. Ed25519 Certificates - 2.2. Basic extensions - 2.2.1. Signed-with-ed25519-key extension [type 04] - 2.3. RSA->Ed25519 cross-certificate - A.1. List of certificate types (CERT_TYPE field) - A.2. List of extension types - A.3. List of signature prefixes - A.4. List of certified key types (CERT_KEY_TYPE field) -``` - -<a id="cert-spec.txt-1"></a> - -# Scope and Preliminaries +# Ed25519 certificates in Tor This document describes a certificate format that Tor uses for its Ed25519 internal certificates. It is not the only @@ -117,7 +96,7 @@ sizeof(ed25519_cert) - 64 bytes). <a id="cert-spec.txt-2.2.1"></a> -### Signed-with-ed25519-key extension \[type 04\] +### Signed-with-ed25519-key extension \[type 04\] { #signed-with-ed25519 } In several places, it's desirable to bundle the key signing a certificate along with the certificate. We do so with this @@ -134,7 +113,7 @@ sign the certificate. <a id="cert-spec.txt-2.3"></a> -## RSA->Ed25519 cross-certificate +## RSA->Ed25519 cross-certificate { #rsa-cross-cert } Certificate type \[07\] (Cross-certification of Ed25519 identity with RSA key) contains the following data: @@ -162,7 +141,7 @@ certificate." <a id="cert-spec.txt-A.1"></a> -## List of certificate types (CERT_TYPE field) +## List of certificate types (CERT_TYPE field) { #list-cert-types } The values marked with asterisks are not types corresponding to the certificate format of section 2.1. Instead, they are @@ -204,13 +183,13 @@ certificate type enumeration of in our Ed25519 certificates. <a id="cert-spec.txt-A.2"></a> -## List of extension types +## List of extension types { #list-ext-types } \[04\] - signed-with-ed25519-key (section 2.2.1) <a id="cert-spec.txt-A.3"></a> -## List of signature prefixes +## List of signature prefixes { #list-sig-prefixes } We describe various documents as being signed with a prefix. Here are those prefixes: @@ -219,7 +198,7 @@ are those prefixes: <a id="cert-spec.txt-A.4"></a> -## List of certified key types (CERT_KEY_TYPE field) +## List of certified key types (CERT_KEY_TYPE field) { #list-key-types } ```text [01] ed25519 key diff --git a/spec/control-spec/implementation-notes.md b/spec/control-spec/implementation-notes.md index 37ce9d6..ebbf113 100644 --- a/spec/control-spec/implementation-notes.md +++ b/spec/control-spec/implementation-notes.md @@ -64,7 +64,7 @@ or encoded in hexadecimal. <a id="control-spec.txt-5.2"></a> -## Don't let the buffer get too big +## Don't let the buffer get too big { #buffer-size } With old versions of Tor (before 0.2.0.16-alpha), if you ask for lots of events, and 16MB of them queue up on the buffer, the Tor @@ -76,7 +76,7 @@ of memory, so you should still be careful about buffer size. <a id="control-spec.txt-5.3"></a> -## Backward compatibility with v0 control protocol +## Backward compatibility with v0 control protocol { #v0-compat } The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now @@ -90,7 +90,7 @@ This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha. <a id="control-spec.txt-5.4"></a> -## Tor config options for use by controllers +## Tor config options for use by controllers { #special-config-options } Tor provides a few special configuration options for use by controllers. These options are not saved to disk by SAVECONF. Most can be set and @@ -188,7 +188,7 @@ to fill this gap, Tor will not correctly handle user requests. <a id="control-spec.txt-5.5"></a> -## Phases from the Bootstrap status event +## Phases from the Bootstrap status event { #bootstrap-phases } ```text [For the bootstrap phases reported by Tor prior to 0.4.0.x, see @@ -209,7 +209,7 @@ fails. <a id="control-spec.txt-5.5.1"></a> -### Overview of Bootstrap reporting +### Overview of Bootstrap reporting { #bootstrap-overview } Bootstrap phases can be viewed as belonging to one of three stages: @@ -244,7 +244,7 @@ connections to relays or bridges that it did not connect to in Stage <a id="control-spec.txt-5.5.2"></a> -### Phases in Bootstrap Stage 1 +### Phases in Bootstrap Stage 1 { #bootstrap-stage1 } Phase 0: tag=starting summary="Starting" @@ -321,7 +321,7 @@ established. <a id="control-spec.txt-5.5.3"></a> -### Phases in Bootstrap Stage 2 +### Phases in Bootstrap Stage 2 { #bootstrap-stage2 } ```text Phase 20: @@ -408,7 +408,7 @@ indicate partial steps. <a id="control-spec.txt-5.5.4"></a> -### Phases in Bootstrap Stage 3 +### Phases in Bootstrap Stage 3 { #bootstrap-stage3 } ```text Phase 76: @@ -521,7 +521,7 @@ application connections now. <a id="control-spec.txt-5.6"></a> -## Bootstrap phases reported by older versions of Tor +## Bootstrap phases reported by older versions of Tor { #bootstrap-obsolete } These phases were reported by Tor older than 0.4.0.x. For newer versions of Tor, see Section 5.5. diff --git a/spec/control-spec/message-format.md b/spec/control-spec/message-format.md index 5a1a6ad..a9af669 100644 --- a/spec/control-spec/message-format.md +++ b/spec/control-spec/message-format.md @@ -64,7 +64,7 @@ controller correctly. <a id="control-spec.txt-2.2"></a> -## Commands from controller to Tor +## Commands from controller to Tor { #commands } ```text Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData @@ -81,7 +81,7 @@ their arguments are described below in section 3. <a id="control-spec.txt-2.3"></a> -## Replies from Tor to the controller +## Replies from Tor to the controller { #replies } ```text Reply = SyncReply / AsyncReply @@ -109,7 +109,7 @@ the final line (usually "650 OK") omitted.\] <a id="control-spec.txt-2.4"></a> -## General-use tokens +## General-use tokens { #tokens } ; CRLF means, "the ASCII Carriage Return character (decimal value 13) ; followed by the ASCII Linefeed character (decimal value 10)." diff --git a/spec/control-spec/replies.md b/spec/control-spec/replies.md index c7b1ab7..4046d6d 100644 --- a/spec/control-spec/replies.md +++ b/spec/control-spec/replies.md @@ -141,7 +141,7 @@ become a "MUST NOT". <a id="control-spec.txt-4.1.1"></a> -### Circuit status changed +### Circuit status changed { #CIRC } The syntax is: @@ -301,7 +301,7 @@ The syntax is: <a id="control-spec.txt-4.1.2"></a> -### Stream status changed +### Stream status changed { #STREAM } The syntax is: @@ -457,7 +457,7 @@ to talk to itself. <a id="control-spec.txt-4.1.3"></a> -### OR Connection status changed +### OR Connection status changed { #ORCONN } The syntax is: @@ -530,7 +530,7 @@ events. <a id="control-spec.txt-4.1.4"></a> -### Bandwidth used in the last second +### Bandwidth used in the last second { #BW } The syntax is: @@ -548,7 +548,7 @@ bandwidth this second (not implemented yet).\] <a id="control-spec.txt-4.1.5"></a> -### Log messages +### Log messages { #LOG } The syntax is: @@ -570,7 +570,7 @@ events, to avoid modifying control output when debugging. <a id="control-spec.txt-4.1.6"></a> -### New descriptors available +### New descriptors available { #NEWDESC } This event is generated when new router descriptors (not microdescs or extrainfos or anything else) are received. @@ -587,7 +587,7 @@ Syntax: <a id="control-spec.txt-4.1.7"></a> -### New Address mapping +### New Address mapping { #ADDRMAP } These events are generated when a new address mapping is entered in Tor's address map cache, or when the answer for a RESOLVE command is @@ -630,7 +630,7 @@ the address was resolved. <a id="control-spec.txt-4.1.8"></a> -### Descriptors uploaded to us in our role as authoritative dirserver +### Descriptors uploaded to us in our role as authoritative dirserver { #AUTHDIR_NEWDESCS} \[NOTE: This feature was removed in Tor 0.3.2.1-alpha.\] @@ -656,7 +656,7 @@ explaining why we chose the Action. (It doesn't contain newlines.) <a id="control-spec.txt-4.1.9"></a> -### Our descriptor changed +### Our descriptor changed { #DESCCHANGED } Syntax: @@ -666,7 +666,7 @@ Syntax: <a id="control-spec.txt-4.1.10"></a> -### Status events +### Status events { #STATUS } Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent based on occurrences in the Tor process pertaining to the general state of @@ -1111,7 +1111,7 @@ Actions for STATUS_GENERAL events can be as follows: <a id="control-spec.txt-4.1.11"></a> -### Our set of guard nodes has changed +### Our set of guard nodes has changed { #GUARD } Syntax: @@ -1147,7 +1147,7 @@ The Status values are: <a id="control-spec.txt-4.1.12"></a> -### Network status has changed +### Network status has changed { #NS } Syntax: @@ -1163,7 +1163,7 @@ down in our local status, for example based on connection attempts. <a id="control-spec.txt-4.1.13"></a> -### Bandwidth used on an application stream +### Bandwidth used on an application stream { #STREAM_BW } The syntax is: @@ -1192,7 +1192,7 @@ or so on). They are not generated for exiting streams. <a id="control-spec.txt-4.1.14"></a> -### Per-country client stats +### Per-country client stats { #CLIENTS_SEEN } The syntax is: @@ -1229,7 +1229,7 @@ in dir-spec.txt. <a id="control-spec.txt-4.1.15"></a> -### New consensus networkstatus has arrived +### New consensus networkstatus has arrived { #NEWCONSENSUS } The syntax is: @@ -1247,7 +1247,7 @@ relay *not* mentioned in this list is implicitly no longer recommended. <a id="control-spec.txt-4.1.16"></a> -### New circuit buildtime has been set +### New circuit buildtime has been set { #BUILDTIMEOUT_SET } The syntax is: @@ -1289,7 +1289,7 @@ this value to the nearest second before using it. <a id="control-spec.txt-4.1.17"></a> -### Signal received +### Signal received { #SIGNAL } The syntax is: @@ -1313,7 +1313,7 @@ generate any event. <a id="control-spec.txt-4.1.18"></a> -### Configuration changed +### Configuration changed { #CONF_CHANGED } The syntax is: @@ -1331,7 +1331,7 @@ Undefined configuration options contain only the KEYWORD. <a id="control-spec.txt-4.1.19"></a> -### Circuit status changed slightly +### Circuit status changed slightly { #CIRC_MINOR } The syntax is: @@ -1360,7 +1360,7 @@ Other fields are as specified in section 4.1.1 above. <a id="control-spec.txt-4.1.20"></a> -### Pluggable transport launched +### Pluggable transport launched { #TRANSPORT_LAUNCHED } The syntax is: @@ -1378,7 +1378,7 @@ The syntax is: <a id="control-spec.txt-4.1.21"></a> -### Bandwidth used on an OR or DIR or EXIT connection +### Bandwidth used on an OR or DIR or EXIT connection { #CONN_BW } The syntax is: @@ -1411,7 +1411,7 @@ These events are only generated if TestingTorNetwork is set. <a id="control-spec.txt-4.1.22"></a> -### Bandwidth used by all streams attached to a circuit +### Bandwidth used by all streams attached to a circuit { #CIRC_BW } The syntax is: @@ -1486,7 +1486,7 @@ were added in Tor 0.3.4.0-alpha\] <a id="control-spec.txt-4.1.23"></a> -### Per-circuit cell stats +### Per-circuit cell stats { #CELL_STATS } The syntax is: @@ -1558,7 +1558,7 @@ cell. These events are only generated if TestingTorNetwork is set. <a id="control-spec.txt-4.1.24"></a> -### Token buckets refilled +### Token buckets refilled { #TB_EMPTY } The syntax is: @@ -1607,7 +1607,7 @@ These events are only generated if TestingTorNetwork is set. <a id="control-spec.txt-4.1.25"></a> -### HiddenService descriptors +### HiddenService descriptors { #HS_DESC } The syntax is: @@ -1681,7 +1681,7 @@ The syntax is: <a id="control-spec.txt-4.1.26"></a> -### HiddenService descriptors content +### HiddenService descriptors content { #HS_DESC_CONTENT } The syntax is: @@ -1719,7 +1719,7 @@ this event will reply either the descriptor's content or an empty one. <a id="control-spec.txt-4.1.27"></a> -### Network liveness has changed +### Network liveness has changed { #NETWORK_LIVENESS } Syntax: @@ -1735,7 +1735,7 @@ Syntax: <a id="control-spec.txt-4.1.28"></a> -### Pluggable Transport Logs +### Pluggable Transport Logs { #PT_LOG } Syntax: @@ -1764,7 +1764,7 @@ Syntax: <a id="control-spec.txt-4.1.29"></a> -### Pluggable Transport Status +### Pluggable Transport Status { #PT_STATUS } Syntax: diff --git a/spec/dir-spec-intro.md b/spec/dir-spec-intro.md index 0f4cafd..7d4b278 100644 --- a/spec/dir-spec-intro.md +++ b/spec/dir-spec-intro.md @@ -29,7 +29,7 @@ The earliest versions of Onion Routing shipped with a list of known routers and their keys. When the set of routers changed, users needed to fetch a new list. -### The Version 1 Directory protocol +### The Version 1 Directory protocol { #v1-protocol } Early versions of Tor (0.0.2) introduced "Directory authorities": servers that served signed "directory" documents containing a list of signed @@ -49,7 +49,7 @@ routers on the network, rather than a complete list of all the descriptors. Clients and caches would fetch these documents far more frequently than they would fetch full directories. -### The Version 2 Directory Protocol +### The Version 2 Directory Protocol { #v2-protocol } During the Tor 0.1.1.x series, Tor revised its handling of directory documents in order to address two major problems: @@ -87,7 +87,7 @@ contents were substantially changed. <a id="dir-spec.txt-0.2"></a> -### Goals of the version 3 protocol +### Goals of the version 3 protocol { #v3-goals } Version 3 of the Tor directory protocol tries to solve the following issues: @@ -118,7 +118,7 @@ issues: <a id="dir-spec.txt-0.3"></a> -## Some Remaining questions +## Some Remaining questions { #open-questions } Things we could solve on a v3 timeframe: diff --git a/spec/dir-spec/client-operation.md b/spec/dir-spec/client-operation.md index 42a5906..a9e6783 100644 --- a/spec/dir-spec/client-operation.md +++ b/spec/dir-spec/client-operation.md @@ -7,7 +7,7 @@ not have a DirPort set) implements this section. <a id="dir-spec.txt-5.1"></a> -## Downloading network-status documents +## Downloading network-status documents { #download-ns } Each client maintains a list of directory authorities. Insofar as possible, clients SHOULD all use the same list. @@ -90,7 +90,7 @@ most recent consensus it has if that consensus is "reasonably live". A <a id="dir-spec.txt-5.2"></a> -## Downloading server descriptors or microdescriptors +## Downloading server descriptors or microdescriptors { #download-desc } Clients try to have the best descriptor for each router. A descriptor is "best" if: @@ -164,7 +164,7 @@ for longer or shorter times. <a id="dir-spec.txt-5.3"></a> -## Downloading extra-info documents +## Downloading extra-info documents { #download-extra } Any client that uses extra-info documents should implement this section. @@ -180,7 +180,7 @@ We follow the same splitting and back-off rules as in section 5.2. <a id="dir-spec.txt-5.4"></a> -## Using directory information +## Using directory information { #using-info } \[XXX This subsection really belongs in path-spec.txt, not here. -KL\] @@ -191,7 +191,7 @@ above.) <a id="dir-spec.txt-5.4.1"></a> -### Choosing routers for circuits +### Choosing routers for circuits { #choosing-routers } Circuits SHOULD NOT be built until the client has enough directory information: a live consensus network status \[XXXX fallback?\] and @@ -219,25 +219,6 @@ These flags are used as follows: See the "path-spec.txt" document for more details. ``` -<a id="dir-spec.txt-5.4.2"></a> - -### Managing naming - -(This section is removed; authorities no longer assign the 'Named' flag.) - -<a id="dir-spec.txt-5.4.3"></a> - -### Software versions - -An implementation of Tor SHOULD warn when it has fetched a consensus -network-status, and it is running a software version not listed. - -<a id="dir-spec.txt-5.4.4"></a> - -### Warning about a router's status - -(This section is removed; authorities no longer assign the 'Named' flag.) - <a id="dir-spec.txt-5.5"></a> ## Retrying failed downloads diff --git a/spec/dir-spec/directory-cache-operation.md b/spec/dir-spec/directory-cache-operation.md index 9807857..14f9a9c 100644 --- a/spec/dir-spec/directory-cache-operation.md +++ b/spec/dir-spec/directory-cache-operation.md @@ -6,7 +6,7 @@ All directory caches implement this section, except as noted. <a id="dir-spec.txt-4.1"></a> -## Downloading consensus status documents from directory authorities +## Downloading consensus status documents from directory authorities { #download-ns-from-auth } All directory caches try to keep a recent network-status consensus document to serve to clients. A cache ALWAYS @@ -36,7 +36,7 @@ the directory authorities. <a id="dir-spec.txt-4.2"></a> -## Downloading server descriptors from directory authorities +## Downloading server descriptors from directory authorities { #download-desc-from-auth } Periodically (currently, every 10 seconds), directory caches check whether there are any specific descriptors that they do not have and that @@ -61,7 +61,7 @@ descriptor seemed newest.) <a id="dir-spec.txt-4.3"></a> -## Downloading microdescriptors from directory authorities +## Downloading microdescriptors from directory authorities { #download-md-from-auth } Directory mirrors should fetch, cache, and serve each microdescriptor from the authorities. @@ -85,7 +85,7 @@ can be retrieved in a single request.) <a id="dir-spec.txt-4.4"></a> -## Downloading extra-info documents from directory authorities +## Downloading extra-info documents from directory authorities { #download-ei-from-auth } Any cache that chooses to cache extra-info documents should implement this section. @@ -99,7 +99,7 @@ same splitting and back-off rules as in section 4.2. <a id="dir-spec.txt-4.5"></a> -## Consensus diffs +## Consensus diffs { #diffs } Instead of downloading an entire consensus, clients may download a "diff" document containing an ed-style diff from a previous @@ -112,7 +112,7 @@ advertised with the DirCache protocol version "2" or later.) <a id="dir-spec.txt-4.5.1"></a> -### Consensus diff format +### Consensus diff format { #diff-format } Consensus diffs are formatted as follows: @@ -134,7 +134,7 @@ in appendix E. <a id="dir-spec.txt-4.5.2"></a> -### Serving and requesting diffs +### Serving and requesting diffs { #diff-requests } When downloading the current consensus, a client may include an HTTP header of the form @@ -162,6 +162,6 @@ fingerprints as in appendix B. <a id="dir-spec.txt-4.6"></a> -## Retrying failed downloads +## Retrying failed downloads { #retry-as-cache } See section 5.5 below; it applies to caches as well as clients. diff --git a/spec/dir-spec/outline.md b/spec/dir-spec/outline.md index e183e33..5d3ed01 100644 --- a/spec/dir-spec/outline.md +++ b/spec/dir-spec/outline.md @@ -46,7 +46,7 @@ All directory information is uploaded and downloaded with HTTP. <a id="dir-spec.txt-1.1"></a> -## What's different from version 2? +## What's different from version 2? { #changes-since-v2 } Clients used to download multiple network status documents, corresponding roughly to "status votes" above. They would compute the @@ -61,7 +61,7 @@ main descriptors. <a id="dir-spec.txt-1.2"></a> -## Document meta-format +## Document meta-format { #metaformat } Server descriptors, directories, and running-routers documents all obey the following lightweight extensible information format. @@ -160,7 +160,7 @@ Whenever an item DOES NOT allow extra arguments, we will tag it with <a id="dir-spec.txt-1.3"></a> -## Signing documents +## Signing documents { #signing } Every signable document below is signed in a similar manner, using a given "Initial Item", a final "Signature Item", a digest algorithm, and diff --git a/spec/dir-spec/serving-bandwidth-list-files.md b/spec/dir-spec/serving-bandwidth-list-files.md index 6b0296b..7397dba 100644 --- a/spec/dir-spec/serving-bandwidth-list-files.md +++ b/spec/dir-spec/serving-bandwidth-list-files.md @@ -1,6 +1,6 @@ <a id="dir-spec.txt-3.4.3"></a> -### Serving bandwidth list files +### Serving bandwidth list files { #serving-bwlist } If an authority has used a bandwidth list file to generate a vote document it SHOULD make it available at @@ -29,13 +29,13 @@ Tor 0.4.0.4-alpha. <a id="dir-spec.txt-3.5"></a> -## Downloading missing certificates from other directory authorities +## Downloading missing certificates from other directory authorities { #download-missing-certs } XXX when to download certificates. <a id="dir-spec.txt-3.6"></a> -## Downloading server descriptors from other directory authorities +## Downloading server descriptors from other directory authorities { #download-missing-descs } Periodically (currently, every 10 seconds), directory authorities check whether there are any specific descriptors that they do not have and that @@ -71,7 +71,7 @@ immediately reject for reasons listed in section 3.2. <a id="dir-spec.txt-3.7"></a> -## Downloading extra-info documents from other directory authorities +## Downloading extra-info documents from other directory authorities { #download-missing-extrainfo } Periodically, an authority checks whether it is missing any extra-info documents: in other words, if it has any server descriptors with an @@ -82,7 +82,7 @@ as in section 3.6. <a id="dir-spec.txt-3.8"></a> -## Computing a consensus from a set of votes +## Computing a consensus from a set of votes { #computing-consensus } Given a set of votes, authorities compute the contents of the consensus. @@ -316,7 +316,7 @@ earlier item. <a id="dir-spec.txt-3.8.0.1"></a> -### Deciding which Ids to include +### Deciding which Ids to include { #choosing-relay-ids } This sorting algorithm is used for consensus-method 22 and later. @@ -343,7 +343,7 @@ This sorting algorithm is used for consensus-method 22 and later. <a id="dir-spec.txt-3.8.0.2"></a> -#### Deciding which descriptors to include +#### Deciding which descriptors to include { #choosing-relay-descs } Deciding which descriptors to include. @@ -362,7 +362,7 @@ published, and then in favor of the smaller server descriptor digest. <a id="dir-spec.txt-3.8.1"></a> -### Forward compatibility +### Forward compatibility { #consensus-method-list } Future versions of Tor will need to include new information in the consensus documents, but it is important that all authorities (or at least @@ -844,7 +844,7 @@ consensus document.\] <a id="dir-spec.txt-3.11"></a> -## Publishing the signed consensus +## Publishing the signed consensus { #publishing-signed-consensus } The voting period ends at the valid-after time. If the consensus has been signed by a majority of authorities, these documents are made diff --git a/spec/dos-spec.md b/spec/dos-spec.md index d0b8e89..d37649f 100644 --- a/spec/dos-spec.md +++ b/spec/dos-spec.md @@ -3,7 +3,7 @@ This document is incomplete; it describes some mechanisms that Tor uses to avoid different kinds of denial-of-service attacks. -## Handling low-memory conditions +## Handling low-memory conditions { #oom } (See also `tor-spec.txt`, section 8.1.) @@ -22,7 +22,7 @@ With this in mind, any Tor implementation—especially one that runs as a relay or onion service—must take steps to prevent memory-based denial-of-service attacks. -### Detecting low memory +### Detecting low memory { #oom-detection } The easiest way to notice you're out of memory would, in theory, be getting an error when you try to allocate more. Unfortunately, some @@ -52,7 +52,7 @@ kinds of allocation: Note that directory caches aren't counted, since those are stored on disk and accessed via mmap. -### Responding to low memory +### Responding to low memory { #oom-response } If our allocations exceed MaxMemInQueues, then we take the following steps to reduce our memory allocation. @@ -87,7 +87,7 @@ rule, according to the age of their oldest queued data. Upon freeing a circuit, a "DESTROY cell" must be sent in both directions. -### Reporting low memory +### Reporting low memory { #oom-reporting } We define a "low threshold" equal to 3/4 of MaxMemInQueues. Every time our memory usage is above the low threshold, we record diff --git a/spec/ext-orport-spec.md b/spec/ext-orport-spec.md index 9d84f92..1341630 100644 --- a/spec/ext-orport-spec.md +++ b/spec/ext-orport-spec.md @@ -1,25 +1,12 @@ +# Extended ORPort for pluggable transports + ```text - Extended ORPort for pluggable transports - George Kadianakis, Nick Mathewson - -Table of Contents - - 1. Overview - 2. Establishing a connection and authenticating. - 2.1. Authentication type: SAFE_COOKIE - 2.1.2. Cookie-file format - 2.1.3. SAFE_COOKIE Protocol specification - 3. The extended ORPort protocol - 3.1. Protocol - 3.2. Command descriptions - 3.2.1. USERADDR - 3.2.2. TRANSPORT - 4. Security Considerations + George Kadianakis, Nick Mathewson ``` <a id="ext-orport-spec.txt-1"></a> -# Overview +## Overview This document describes the "Extended ORPort" protocol, a wrapper around Tor's ordinary ORPort protocol for use by bridges that @@ -35,7 +22,7 @@ extended with authentication in proposal 217. <a id="ext-orport-spec.txt-2"></a> -# Establishing a connection and authenticating +## Establishing a connection and authenticating { #establishing } When a client (that is to say, a server-side pluggable transport) connects to an Extended ORPort, the server sends: @@ -71,7 +58,7 @@ server does not support, the server MUST close the connection. <a id="ext-orport-spec.txt-2.1"></a> -## Authentication type: SAFE_COOKIE +### Authentication type: SAFE_COOKIE { #SAFE_COOKIE } We define one authentication type: SAFE_COOKIE. Its AuthType value is 1. It is based on the client proving to the bridge that @@ -92,7 +79,7 @@ where `<path>` is a filesystem path. <a id="ext-orport-spec.txt-2.1.2"></a> -### Cookie-file format +#### Cookie-file format { #SAFE_COOKIE_file } The format of the cookie-file is: @@ -113,11 +100,13 @@ authentication protocol. <a id="ext-orport-spec.txt-2.1.3"></a> -### SAFE_COOKIE Protocol specification +#### SAFE_COOKIE Protocol specification { #SAFE_COOKIE_spec } A client that performs the SAFE_COOKIE handshake begins by sending: -ClientNonce \[32 octets\] +```text +ClientNonce [32 octets] +``` Where, @@ -144,9 +133,9 @@ terminate the connection. Otherwise the client replies with: -ClientHash \[32 octets\] - ```text +ClientHash [32 octets] + Where, + ClientHash is computed as: HMAC-SHA256(CookieString, @@ -168,14 +157,14 @@ Status \[1 octet\] <a id="ext-orport-spec.txt-3"></a> -# The extended ORPort protocol +## The extended ORPort protocol { #ext_orport_protocol} Once a connection is established and authenticated, the parties communicate with the protocol described here. <a id="ext-orport-spec.txt-3.1"></a> -## Protocol +### Protocol The extended server port protocol is as follows: @@ -213,11 +202,11 @@ MUST close the connection to the client. <a id="ext-orport-spec.txt-3.2"></a> -## Command descriptions +### Command descriptions { #ext-orport-commands} <a id="ext-orport-spec.txt-3.2.1"></a> -### USERADDR +#### USERADDR ```text An ASCII string holding the TCP/IP address of the client of the @@ -234,7 +223,7 @@ The string MUST not be NUL-terminated. <a id="ext-orport-spec.txt-3.2.2"></a> -### TRANSPORT +#### TRANSPORT An ASCII string holding the name of the pluggable transport used by the client of the pluggable transport proxy. A Tor bridge that @@ -248,7 +237,7 @@ for correctness. <a id="ext-orport-spec.txt-4"></a> -# Security Considerations +## Security Considerations Extended ORPort or TransportControlPort do _not_ provide link confidentiality, authentication or integrity. Sensitive data, like diff --git a/spec/gettor-spec.md b/spec/gettor-spec.md index 9a5caea..446f116 100644 --- a/spec/gettor-spec.md +++ b/spec/gettor-spec.md @@ -1,19 +1,6 @@ -```text - GetTor specification - Jacob Appelbaum - -Table of Contents - - 0. Preface - 1. Overview - 2. Implementation - 2.1. Reference implementation - 3. SMTP transport - 3.1. SMTP transport security considerations - 3.2. SMTP transport privacy considerations - 4. Other transports - 5. Implementation suggestions -``` +# GetTor specification + +Jacob Appelbaum <a id="gettor-spec.txt-0"></a> diff --git a/spec/glossary.md b/spec/glossary.md index 8f62ff7..908686c 100644 --- a/spec/glossary.md +++ b/spec/glossary.md @@ -1,4 +1,4 @@ -Glossary +# Glossary The Tor Project @@ -10,28 +10,6 @@ This glossary is not a design document; it is only a reference. This glossary is a work-in-progress; double-check its definitions before citing them authoritatively. ;) -Table of Contents - -```text - 0. Preliminaries - 1.0. Commonly used Tor configuration terms - 2.0. Tor network components - 2.1. Relays, aka OR (onion router) - 2.1.1. Specific roles - 2.2. Client, aka OP (onion proxy) - 2.3. Authorities - 2.4. Hidden Service - 2.5. Circuit - 2.6. Edge connection - 2.7. Consensus - 2.8. Descriptor - 3.0. Tor network protocols - 3.1. Link handshake - 3.2. Circuit handshake - 3.3. Hidden Service Protocol - 3.4. Directory Protocol - 4.0. General network definitions -``` <a id="glossary.txt-0"></a> @@ -44,24 +22,24 @@ RFC 2119. <a id="glossary.txt-1.0"></a> -## Commonly used Tor configuration terms +## Commonly used Tor configuration terms { #configuration } ORPort - Onion Router Port DirPort - Directory Port <a id="glossary.txt-2.0"></a> -## Tor network components +## Tor network components { #network-compoennts } <a id="glossary.txt-2.1"></a> -## Relays, aka OR (onion router) +## Relays, aka OR (onion router) { #relay} \[Style guide: prefer the term "Relay"\] <a id="glossary.txt-2.1.1"></a> -### Specific roles +### Specific roles { #roles } Exit relay: The final hop in an exit circuit before traffic leaves the Tor network to connect to external servers. @@ -91,13 +69,13 @@ rendezvous point. <a id="glossary.txt-2.2"></a> -## Client, aka OP (onion proxy) +## Client, aka OP (onion proxy) { #client } \[Style: the "OP" and "onion proxy" terms are deprecated.\] <a id="glossary.txt-2.3"></a> -## Authorities +## Authorities { #authorities } Directory Authority: Nine total in the Tor network, operated by trusted individuals. Directory authorities define and serve the @@ -117,7 +95,7 @@ information it has.) <a id="glossary.txt-2.4"></a> -## Hidden Service +## Hidden Service { #hidden-service } A hidden service is a server that will only accept incoming connections via the hidden service protocol. Connection diff --git a/spec/guard-spec/algorithm.md b/spec/guard-spec/algorithm.md index b18803b..832814a 100644 --- a/spec/guard-spec/algorithm.md +++ b/spec/guard-spec/algorithm.md @@ -4,7 +4,7 @@ <a id="guard-spec.txt-4.0"></a> -## The guards listed in the current consensus. \[Section:GUARDS\] +## The guards listed in the current consensus. {#GUARDS} By {set:GUARDS} we mean the set of all guards in the current consensus that are usable for all circuits and directory @@ -17,7 +17,7 @@ from any guard, so that all guards are usable for all circuits. <a id="guard-spec.txt-4.1"></a> -## The Sampled Guard Set. \[Section:SAMPLED\] +## The Sampled Guard Set. {#SAMPLED} We maintain a set, {set:SAMPLED_GUARDS}, that persists across invocations of Tor. It is a subset of the nodes ordered by a sample idx that @@ -130,7 +130,7 @@ adversary node. <a id="guard-spec.txt-4.2"></a> -## The Usable Sample \[Section:FILTERED\] +## The Usable Sample {#FILTERED} We maintain another set, {set:FILTERED_GUARDS}, that does not persist. It is derived from: @@ -185,7 +185,7 @@ filtering restrictions that we had in the past. <a id="guard-spec.txt-4.3"></a> -## The confirmed-guard list. \[Section:CONFIRMED\] +## The confirmed-guard list. {#CONFIRMED} \[formerly USED_GUARDS\] @@ -247,7 +247,7 @@ traffic. <a id="guard-spec.txt-4.4"></a> -## The Primary guards \[Section:PRIMARY\] +## The Primary guards {#PRIMARY} We keep a run-time non-persistent ordered list of {list:PRIMARY_GUARDS}. It is a subset of {FILTERED_GUARDS}. It @@ -280,7 +280,7 @@ usable after all. <a id="guard-spec.txt-4.5"></a> -## Retrying guards. \[Section:RETRYING\] +## Retrying guards. {#RETRYING} (We run this process as frequently as needed. It can be done once a second, or just-in-time.) @@ -410,7 +410,7 @@ sure that it's the best guard we're getting. (see below). <a id="guard-spec.txt-4.7"></a> -## When a circuit fails. \[Section:ON_FAIL\] +## When a circuit fails. {#ON_FAIL} When a circuit fails in a way that makes us conclude that a guard is not reachable, we take the following steps: @@ -437,7 +437,7 @@ See \[SELECTING\] above for rationale. <a id="guard-spec.txt-4.8"></a> -## When a circuit succeeds \[Section:ON_SUCCESS\] +## When a circuit succeeds {#ON_SUCCESS} When a circuit succeeds in a way that makes us conclude that a guard _was_ reachable, we take these steps: @@ -476,7 +476,7 @@ See \[SELECTING\] above for rationale. <a id="guard-spec.txt-4.9"></a> -## Updating the list of waiting circuits \[Section:UPDATE_WAITING\] +## Updating the list of waiting circuits {#UPDATE_WAITING} We run this procedure whenever it's possible that a `<waiting_for_better_guard>` circuit might be ready to be called @@ -516,7 +516,7 @@ them after all if the `<complete>` circuit goes down before <a id="guard-spec.txt-4.9.1"></a> -### Without a list of waiting circuits \[Section:NO_CIRCLIST\] +### Without a list of waiting circuits {#NO_CIRCLIST} As an alternative to the section \[SECTION:UPDATE_WAITING\] above, this section presents a new way to maintain guard status @@ -559,7 +559,7 @@ these rules: <a id="guard-spec.txt-4.10"></a> -## Whenever we get a new consensus. \[Section:ON_CONSENSUS\] +## Whenever we get a new consensus. {#ON_CONSENSUS} We update {GUARDS}. diff --git a/spec/guard-spec/appendices.md b/spec/guard-spec/appendices.md index 34368ad..2eacc62 100644 --- a/spec/guard-spec/appendices.md +++ b/spec/guard-spec/appendices.md @@ -11,7 +11,7 @@ CNS-1314637, CNS-1526306, CNS-1619454, and CNS-1640548. <a id="guard-spec.txt-A.1"></a> -## Parameters with suggested values. \[Section:PARAM_VALS\] +## Parameters with suggested values. {#PARAM_VALS} (All suggested values chosen arbitrarily) @@ -80,7 +80,7 @@ CNS-1314637, CNS-1526306, CNS-1619454, and CNS-1640548. <a id="guard-spec.txt-A.2"></a> -## Random values \[Section:RANDOM\] +## Random values {#RANDOM} Frequently, we want to randomize the expiration time of something so that it's not easy for an observer to match it to its start @@ -92,7 +92,7 @@ the past, chosen uniformly at random. <a id="guard-spec.txt-A.3"></a> -## Why not a sliding scale of primaryness? \[Section:CVP\] +## Why not a sliding scale of primaryness? {#CVP} At one meeting, I floated the idea of having "primaryness" be a continuous variable rather than a boolean. @@ -157,7 +157,7 @@ become built too. <a id="guard-spec.txt-A.5"></a> -## Persistent state format +## Persistent state format {#persistent-state} The persistent state format doesn't need to be part of this specification, since different implementations can do it diff --git a/spec/guard-spec/guard-selection-intro.md b/spec/guard-spec/guard-selection-intro.md index b31609f..c3738d4 100644 --- a/spec/guard-spec/guard-selection-intro.md +++ b/spec/guard-spec/guard-selection-intro.md @@ -1,6 +1,6 @@ <a id="guard-spec.txt-3"></a> -# Circuit Creation, Entry Guard Selection (1000 foot view) +# Circuit Creation, Entry Guard Selection (1000 foot view) {#1000-foot} A circuit in Tor is a path through the network connecting a client to its destination. At a high-level, a three-hop exit circuit will look @@ -12,7 +12,7 @@ Entry guards are the only nodes which a client will connect to directly. Exit relays are the nodes by which traffic exits the Tor network in order to connect to an external destination. -3.1 Path selection +## Path selection For any multi-hop circuit, at least one entry guard and middle node(s) are required. An exit node is required if traffic will exit the Tor @@ -21,7 +21,7 @@ consensus could be used for any of these roles. However, this specification defines how entry guards specifically should be selected and managed, as opposed to middle or exit nodes. -3.1.1 Managing entry guards +### Managing entry guards At a high level, a relay listed in a consensus will move through the following states in the process from initial selection to eventual @@ -52,14 +52,14 @@ It is always preferable to use a primary guard when building a new circuit in order to reduce guard churn; only on failure to connect to existing primary guards will new guards be used. -3.1.2 Middle and exit node selection +### Middle and exit node selection Middle nodes are selected at random from relays listed in the latest consensus, weighted by bandwidth and bandwidth-weights. Exit nodes are chosen similarly but restricted to relays with a sufficiently permissive exit policy. -3.2 Circuit Building +## Circuit Building Once a path is chosen, Tor will use this path to build a new circuit. diff --git a/spec/padding-spec/circuit-level-padding.md b/spec/padding-spec/circuit-level-padding.md index a220507..33ecfc3 100644 --- a/spec/padding-spec/circuit-level-padding.md +++ b/spec/padding-spec/circuit-level-padding.md @@ -23,7 +23,7 @@ future padding defenses, see the research developer documentation\[17\]. <a id="padding-spec.txt-3.1"></a> -## Circuit Padding Negotiation +## Circuit Padding Negotiation {#negotiation} Circuit padding machines are advertised as "Padding" subprotocol versions (see tor-spec.txt Section 9). The onion service circuit padding machines are @@ -96,7 +96,7 @@ on the circuit, the command is ignored. <a id="padding-spec.txt-3.2"></a> -## Circuit Padding Machine Message Management +## Circuit Padding Machine Message Management { #machine-msg-mgt } Clients MAY send padding cells towards the relay before receiving the circpad_negotiated response, to allow for outbound cover traffic before @@ -112,7 +112,7 @@ immediately tear down such circuits to avoid side channel risk. <a id="padding-spec.txt-3.3"></a> -## Obfuscating client-side onion service circuit setup +## Obfuscating client-side onion service circuit setup { #hiding-circ-setup } The circuit padding currently deployed in Tor attempts to hide client-side onion service circuit setup. Service-side setup is not covered, because doing @@ -129,7 +129,7 @@ Note that inter-arrival timing is not obfuscated by this defense. <a id="padding-spec.txt-3.3.1"></a> -### Common general circuit construction sequences +### Common general circuit construction sequences { #circ-setup-sequences} Most general Tor circuits used to surf the web or download directory information start with the following 6-cell relay cell sequence (cells @@ -156,7 +156,7 @@ network/guard-level adversary. <a id="padding-spec.txt-3.3.2"></a> -### Client-side onion service introduction circuit obfuscation +### Client-side onion service introduction circuit obfuscation { #hiding-intro } Two circuit padding machines work to hide client-side introduction circuits: one machine at the origin, and one machine at the second hop of the circuit. @@ -199,7 +199,7 @@ minutes). <a id="padding-spec.txt-3.3.3"></a> -### Client-side rendezvous circuit hiding +### Client-side rendezvous circuit hiding { #hiding-rendezvous } Following a similar argument as for intro circuits, we are aiming for padded rendezvous circuits to blend in with the initial cell sequence of general @@ -240,7 +240,7 @@ will look alike. <a id="padding-spec.txt-3.3.4"></a> -### Circuit setup machine overhead +### Circuit setup machine overhead { #setup-overhead } For the intro circuit case, we see that the origin-side machine just sends a single \[PADDING_NEGOTIATE\] cell, whereas the origin-side machine sends a @@ -252,7 +252,7 @@ padding cells, for a total of 4 padding cells. <a id="padding-spec.txt-3.4"></a> -## Circuit padding consensus parameters +## Circuit padding consensus parameters { #consenus-parameters } The circuit padding system has a handful of consensus parameters that can either disable circuit padding entirely, or rate limit the total overhead diff --git a/spec/padding-spec/connection-level-padding.md b/spec/padding-spec/connection-level-padding.md index 5c01f38..c2890d8 100644 --- a/spec/padding-spec/connection-level-padding.md +++ b/spec/padding-spec/connection-level-padding.md @@ -133,7 +133,7 @@ padding should not be scheduled until after the queue does become empty.) <a id="padding-spec.txt-2.3"></a> -## Padding Cell Timeout Distribution Statistics +## Padding Cell Timeout Distribution Statistics { #distribution-statistics } To limit the amount of padding sent, instead of sampling each endpoint timeout uniformly, we instead sample it from max(X,X), where X is @@ -184,7 +184,7 @@ idle, so we expect the actual overhead to be much lower than this. <a id="padding-spec.txt-2.5"></a> -## Reducing or Disabling Padding via Negotiation +## Reducing or Disabling Padding via Negotiation { #negotiation } To allow mobile clients to either disable or reduce their padding overhead, the CELL_PADDING_NEGOTIATE cell (tor-spec.txt section 7.2) may be sent from @@ -229,7 +229,7 @@ and close the channel if they receive one. <a id="padding-spec.txt-2.6"></a> -## Consensus Parameters Governing Behavior +## Consensus Parameters Governing Behavior { #consensus-parameters } Connection-level padding is controlled by the following consensus parameters: diff --git a/spec/param-spec.md b/spec/param-spec.md index bd18c0c..025110c 100644 --- a/spec/param-spec.md +++ b/spec/param-spec.md @@ -3,24 +3,9 @@ Tor network parameters This file lists the recognized parameters that can appear on the "params" line of a directory consensus. -Table of Contents - -1. Network protocol parameters -1. Performance-tuning parameters -1. Voting-related parameters -1. Circuit-build-timeout parameters -1. Directory-related parameters -1. Pathbias parameters -1. Relay behavior -1. V3 onion service parameters -1. Denial-of-service parameters -1. Padding-related parameters -1. Guard-related parameters - X. Obsolete parameters - <a id="param-spec.txt-1"></a> -# Network protocol parameters +# Network protocol parameters {#network-protocol} "circwindow" -- the default package window that circuits should be established with. It started out at 1000 cells, but some research @@ -73,7 +58,7 @@ First appeared: 0.4.5.1-alpha. <a id="param-spec.txt-2"></a> -# Performance-tuning parameters +# Performance-tuning parameters {#performance-tuning} "CircuitPriorityHalflifeMsec" -- the halflife parameter used when weighting which circuit will send the next cell. Obeyed by Tor @@ -123,7 +108,7 @@ First appeared: 0.4.8.2 <a id="param-spec.txt-3"></a> -# Voting-related parameters +# Voting-related parameters {#voting} "bwweightscale" -- Value that bandwidth-weights are divided by. If not present then this defaults to 10000. @@ -161,7 +146,7 @@ dirauth. <a id="param-spec.txt-4"></a> -# Circuit-build-timeout parameters +# Circuit-build-timeout parameters {#cbt} "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts", "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq", @@ -172,7 +157,7 @@ consensus parameters. <a id="param-spec.txt-5"></a> -# Directory-related parameters +# Directory-related parameters {#directory} "max-consensus-age-to-cache-for-diff" -- Determines how much consensus history (in hours) relays should try to cache in order to @@ -184,7 +169,7 @@ try to find a diff for it. (min 0, max 8192, default 72) <a id="param-spec.txt-6"></a> -# Pathbias parameters +# Pathbias parameters {#pathbias} "pb_mincircs", "pb_noticepct", "pb_warnpct", "pb_extremepct", "pb_dropguards", "pb_scalecircs", "pb_scalefactor", @@ -193,7 +178,7 @@ try to find a diff for it. (min 0, max 8192, default 72) <a id="param-spec.txt-7"></a> -# Relay behavior +# Relay behavior parameters {#relay-behavior} "refuseunknownexits" -- if set to one, exit relays look at the previous hop of circuits that ask to open an exit stream, and refuse to exit if @@ -277,7 +262,7 @@ First appeared: 0.4.7.5-alpha. <a id="param-spec.txt-8"></a> -# V3 onion service parameters +# V3 onion service parameters {#onion-service} "hs_intro_min_introduce2", "hs_intro_max_introduce2" -- Minimum/maximum amount of INTRODUCE2 cells allowed per circuits @@ -336,7 +321,7 @@ First appeared: 0.4.2.1-alpha. <a id="param-spec.txt-9"></a> -# Denial-of-service parameters +# Denial-of-service parameters {#dos} Denial of Service mitigation parameters. Introduced in 0.3.3.2-alpha: @@ -383,7 +368,7 @@ rendezvous points for single hop clients. <a id="param-spec.txt-10"></a> -# Padding-related parameters +# Padding-related parameters {#padding} "circpad_max_circ_queued_cells" -- The circuitpadding module will stop sending more padding cells if more than this many cells are in @@ -514,7 +499,7 @@ First appeared: 0.3.0 <a id="param-spec.txt-X"></a> -# Obsolete parameters +# Obsolete parameters {#obsolete} "NumDirectoryGuards", "NumEntryGuards" -- Number of guard nodes clients should use by default. If NumDirectoryGuards is 0, we diff --git a/spec/path-spec/detecting-route-manipulation.md b/spec/path-spec/detecting-route-manipulation.md index c7ff50c..48cf4f7 100644 --- a/spec/path-spec/detecting-route-manipulation.md +++ b/spec/path-spec/detecting-route-manipulation.md @@ -1,6 +1,6 @@ <a id="path-spec.txt-7"></a> -# Detecting route manipulation by Guard nodes (Path Bias) +# Detecting route manipulation by Guard nodes (Path Bias) {#pathbias} The Path Bias defense is designed to defend against a type of route capture where malicious Guard nodes deliberately fail or choke circuits @@ -35,7 +35,7 @@ section 7.5). <a id="path-spec.txt-7.1"></a> -## Measuring path construction success rates +## Measuring path construction success rates {#construction-success-rate} Clients maintain two counts for each of their guards: a count of the number of times a circuit was extended to at least two hops through that @@ -52,7 +52,7 @@ requested to close by the client, this is counted as a failure. <a id="path-spec.txt-7.2"></a> -## Measuring path usage success rates +## Measuring path usage success rates {#usage-success-rate} Clients maintain two usage counts for each of their guards: a count of the number of usage attempts, and a count of the number of @@ -88,7 +88,7 @@ failures. <a id="path-spec.txt-7.3"></a> -## Scaling success counts +## Scaling success counts {#scaling} To provide a moving average of recent Guard activity while still preserving the ability to verify correctness, we periodically @@ -104,7 +104,7 @@ scaling, and added back after scaling. <a id="path-spec.txt-7.4"></a> -## Parametrization +## Parametrization {#parameters} The following consensus parameters tune various aspects of the defense. @@ -189,7 +189,7 @@ defense. <a id="path-spec.txt-7.5"></a> -## Known barriers to enforcement +## Known barriers to enforcement {#barriers} Due to intermittent CPU overload at relays, the normal rate of successful circuit completion is highly variable. The Guard-dropping diff --git a/spec/path-spec/general-operation.md b/spec/path-spec/general-operation.md index 7127fee..c491f98 100644 --- a/spec/path-spec/general-operation.md +++ b/spec/path-spec/general-operation.md @@ -77,7 +77,7 @@ supports the request according to the rules given below. <a id="path-spec.txt-1.2"></a> -## A relay's bandwidth +## A relay's bandwidth {#bandwidth} Old versions of Tor did not report bandwidths in network status documents, so clients had to learn them from the routers' advertised diff --git a/spec/path-spec/guard-nodes.md b/spec/path-spec/guard-nodes.md index 553d5e3..af5750c 100644 --- a/spec/path-spec/guard-nodes.md +++ b/spec/path-spec/guard-nodes.md @@ -9,7 +9,7 @@ guard-spec.txt. <a id="path-spec.txt-5.1"></a> -## How consensus bandwidth weights factor into entry guard selection +## How consensus bandwidth weights factor into entry guard selection {#bw-and-guards} When weighting a list of routers for choosing an entry guard, the following consensus parameters (from the "bandwidth-weights" line) apply: diff --git a/spec/path-spec/learning-timeouts.md b/spec/path-spec/learning-timeouts.md index 939f3a2..e53ab66 100644 --- a/spec/path-spec/learning-timeouts.md +++ b/spec/path-spec/learning-timeouts.md @@ -1,6 +1,6 @@ <a id="path-spec.txt-2.4"></a> -## Learning when to give up ("timeout") on circuit construction +## Learning when to give up ("timeout") on circuit construction {#timing-out} Since version 0.2.2.8-alpha, Tor clients attempt to learn when to give up on circuits based on network conditions. @@ -19,7 +19,7 @@ distribution with a single Pareto curve. <a id="path-spec.txt-2.4.2"></a> -### How much data to record +### How much data to record {#observations} From our observations, the minimum number of circuit build times for a reasonable fit appears to be on the order of 100. However, to keep a @@ -122,7 +122,7 @@ but at least 60 seconds: <a id="path-spec.txt-2.4.3"></a> -### Calculating timeouts thresholds for circuits of different lengths +### Calculating timeouts thresholds for circuits of different lengths {#different-lengths} The timeout_ms and close_ms estimates above are good only for 3-hop circuits, since only 3-hop circuits are recorded in the list of build @@ -145,7 +145,7 @@ required with the Xth hop. <a id="path-spec.txt-2.4.4"></a> -### How to record timeouts +### How to record timeouts {#recording-timeouts} Pareto estimators begin to lose their accuracy if the tail is omitted. Hence, Tor clients actually calculate two timeouts: a usage timeout, and a @@ -166,7 +166,7 @@ offline. <a id="path-spec.txt-2.4.5"></a> -### Detecting Changing Network Conditions +### Detecting Changing Network Conditions {#changes-in-network} Tor clients attempt to detect both network connectivity loss and drastic changes in the timeout characteristics. @@ -187,7 +187,7 @@ we start with a new, empty state. <a id="path-spec.txt-2.4.6"></a> -### Consensus parameters governing behavior +### Consensus parameters governing behavior {#parameters} Clients that implement circuit build timeout learning should obey the following consensus parameters that govern behavior, in order to allow diff --git a/spec/path-spec/old-notes.md b/spec/path-spec/old-notes.md index ce3ec44..495a69a 100644 --- a/spec/path-spec/old-notes.md +++ b/spec/path-spec/old-notes.md @@ -4,9 +4,10 @@ <a id="path-spec.txt-X.1"></a> -## Do we actually do this? +## Do we actually do this? {#is-this-real} ```text + How to deal with network down. - While all helpers are down/unreachable and there are no established or on-the-way testing circuits, launch a testing circuit. (Do this @@ -31,7 +32,7 @@ remove it. -NM\] <a id="path-spec.txt-X.2"></a> -## A thing we could do to deal with reachability +## A thing we could do to deal with reachability {#a-thing} And as a bonus, it leads to an answer to Nick's attack ("If I pick my helper nodes all on 18.0.0.0:\*, then I move, you'll know where I @@ -43,7 +44,7 @@ Is that smart or just complex? <a id="path-spec.txt-X.3"></a> -## Some stuff that worries me about entry guards. 2006 Jun, Nickm +## Some stuff that worries me about entry guards. 2006 Jun, Nickm {#worries} It is unlikely for two users to have the same set of entry guards. Observing a user is sufficient to learn its entry guards. So, as we move diff --git a/spec/pt-spec/configuration-environment.md b/spec/pt-spec/configuration-environment.md index 79e9f67..767c37b 100644 --- a/spec/pt-spec/configuration-environment.md +++ b/spec/pt-spec/configuration-environment.md @@ -1,6 +1,6 @@ <a id="pt-spec.txt-3.2"></a> -## Pluggable Transport Configuration Environment Variables +## Pluggable Transport Configuration Environment Variables {#envvars} All Pluggable Transport proxy instances are configured by their parent process at launch time via a set of well defined @@ -12,7 +12,7 @@ specification. <a id="pt-spec.txt-3.2.1"></a> -### Common Environment Variables +### Common Environment Variables {#common} When launching either a client or server Pluggable Transport proxy, the following common environment variables MUST be set. @@ -102,7 +102,7 @@ TOR_PT_OUTBOUND_BIND_ADDRESS_V6=\[2001:db8::4\] <a id="pt-spec.txt-3.2.2"></a> -### Pluggable Transport Client Environment Variables +### Pluggable Transport Client Environment Variables {#client} Client-side Pluggable Transport forward proxies are configured via the following environment variables. @@ -143,7 +143,7 @@ Examples: <a id="pt-spec.txt-3.2.3"></a> -### Pluggable Transport Server Environment Variables +### Pluggable Transport Server Environment Variables {#server} Server-side Pluggable Transport reverse proxies are configured via the following environment variables. diff --git a/spec/pt-spec/ipc.md b/spec/pt-spec/ipc.md index 21fd18b..8c5d001 100644 --- a/spec/pt-spec/ipc.md +++ b/spec/pt-spec/ipc.md @@ -96,7 +96,7 @@ ENV-ERROR No TOR_PT_AUTH_COOKIE_FILE when TOR_PT_EXTENDED_SERVER_PORT set <a id="pt-spec.txt-3.3.2"></a> -### Pluggable Transport Client Messages +### Pluggable Transport Client Messages {#client-messages} After negotiating the Pluggable Transport Specification version, PT client proxies MUST first validate "TOR_PT_PROXY" (3.2.2) if @@ -178,7 +178,7 @@ Notes: <a id="pt-spec.txt-3.3.3"></a> -### Pluggable Transport Server Messages +### Pluggable Transport Server Messages {#server-messages} PT server reverse proxies iterate over the requested transports in "TOR_PT_CLIENT_TRANSPORTS" and initialize the listeners. @@ -245,7 +245,7 @@ initialization is complete. <a id="pt-spec.txt-3.3.4"></a> -### Pluggable Transport Log Message +### Pluggable Transport Log Message {#log-messages} This message is for a client or server PT to be able to signal back to the parent process via stdout or stderr any log messages. @@ -276,7 +276,7 @@ Example: <a id="pt-spec.txt-3.3.5"></a> -### Pluggable Transport Status Message +### Pluggable Transport Status Message {#status-messages} This message is for a client or server PT to be able to signal back to the parent process via stdout or stderr any status messages. diff --git a/spec/rend-spec-v3/deriving-keys.md b/spec/rend-spec-v3/deriving-keys.md index 201fc92..cbf62fe 100644 --- a/spec/rend-spec-v3/deriving-keys.md +++ b/spec/rend-spec-v3/deriving-keys.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-2.1"></a> -## Deriving blinded keys and subcredentials \[SUBCRED\] +## Deriving blinded keys and subcredentials {#SUBCRED} In each time period (see \[TIME-PERIODS\] for a definition of time periods), a hidden service host uses a different blinded private key @@ -58,7 +58,7 @@ Which Tor servers hosts a hidden service depends on: <a id="rend-spec-v3.txt-2.2.1"></a> -### Dividing time into periods \[TIME-PERIODS\] +### Dividing time into periods {#TIME-PERIODS} To prevent a single set of hidden service directory from becoming a target by adversaries looking to permanently censor a hidden service, @@ -90,7 +90,7 @@ after the epoch, at 2016-04-12 12:00 UTC, and ended at 16904*1440*60 + <a id="rend-spec-v3.txt-2.2.2"></a> -### When to publish a hidden service descriptor \[WHEN-HSDESC\] +### When to publish a hidden service descriptor {#WHEN-HSDESC} Hidden services periodically publish their descriptor to the responsible HSDirs. The set of responsible HSDirs is determined as specified in @@ -104,7 +104,7 @@ descriptor again to the responsible HSDirs for that time period. <a id="rend-spec-v3.txt-2.2.2.1"></a> -#### Overlapping descriptors +#### Overlapping descriptors {#OVERLAPPING-DESCS} Hidden services need to upload multiple descriptors so that they can be reachable to clients with older or newer consensuses than them. Services @@ -125,7 +125,7 @@ achieved. <a id="rend-spec-v3.txt-2.2.3"></a> -### Where to publish a hidden service descriptor \[WHERE-HSDESC\] +### Where to publish a hidden service descriptor {#WHERE-HSDESC} This section specifies how the HSDir hash ring is formed at any given time. Whenever a time value is needed (e.g. to get the current time period @@ -190,7 +190,7 @@ choosing the spread for a replica. <a id="rend-spec-v3.txt-2.2.4"></a> -### Using time periods and SRVs to fetch/upload HS descriptors \[FETCHUPLOADDESC\] +### Using time periods and SRVs to fetch/upload HS descriptors {#FETCHUPLOADDESC} Hidden services and clients need to make correct use of time periods (TP) and shared random values (SRVs) to successfully fetch and upload @@ -228,7 +228,7 @@ Let's start with an illustration of the system: <a id="rend-spec-v3.txt-2.2.4.1"></a> -#### Client behavior for fetching descriptors \[CLIENTFETCH\] +#### Client behavior for fetching descriptors {#CLIENTFETCH} And here is how clients use TPs and SRVs to fetch descriptors: @@ -258,7 +258,7 @@ after SRV#2, it will still use TP#1 and SRV#1. <a id="rend-spec-v3.txt-2.2.4.2"></a> -#### Service behavior for uploading descriptors \[SERVICEUPLOAD\] +#### Service behavior for uploading descriptors {#SERVICEUPLOAD} As discussed above, services maintain two active descriptors at any time. We call these the "first" and "second" service descriptors. Services rotate @@ -272,7 +272,7 @@ values based on their position in the graph above. Here is the logic: <a id="rend-spec-v3.txt-2.2.4.2.1"></a> -##### First descriptor upload logic \[FIRSTDESCUPLOAD\] +##### First descriptor upload logic {#FIRSTDESCUPLOAD} Here is the service logic for uploading its first descriptor: @@ -308,7 +308,7 @@ first descriptor using TP#1 and SRV#1. <a id="rend-spec-v3.txt-2.2.4.2.2"></a> -##### Second descriptor upload logic \[SECONDDESCUPLOAD\] +##### Second descriptor upload logic {#SECONDDESCUPLOAD} Here is the service logic for uploading its second descriptor: @@ -368,7 +368,7 @@ necessary client credentials (for decrypting the second layer). <a id="rend-spec-v3.txt-2.2.5"></a> -### Expiring hidden service descriptors \[EXPIRE-DESC\] +### Expiring hidden service descriptors {#EXPIRE-DESC} Hidden services set their descriptor's "descriptor-lifetime" field to 180 minutes (3 hours). Hidden services ensure that their descriptor will remain @@ -381,7 +381,7 @@ the time period has changed). <a id="rend-spec-v3.txt-2.2.6"></a> -### URLs for anonymous uploading and downloading +### URLs for anonymous uploading and downloading {#urls} Hidden service descriptors conforming to this specification are uploaded with an HTTP POST request to the URL `/tor/hs/<version>/publish` relative to @@ -395,7 +395,7 @@ anything else. <a id="rend-spec-v3.txt-2.2.7"></a> -### Client-side validation of onion addresses +### Client-side validation of onion addresses {#addr-validation} When a Tor client receives a prop224 onion address from the user, it MUST first validate the onion address before attempting to connect or diff --git a/spec/rend-spec-v3/hsdesc-encrypt.md b/spec/rend-spec-v3/hsdesc-encrypt.md index 834aceb..10a7d77 100644 --- a/spec/rend-spec-v3/hsdesc-encrypt.md +++ b/spec/rend-spec-v3/hsdesc-encrypt.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-2.5"></a> -## Hidden service descriptors: encryption format \[HS-DESC-ENC\] +## Hidden service descriptors: encryption format {#HS-DESC-ENC} Hidden service descriptors are protected by two layers of encryption. Clients need to decrypt both layers to connect to the hidden service. @@ -12,7 +12,7 @@ and protects against entities that do not possess valid client credentials. <a id="rend-spec-v3.txt-2.5.1"></a> -### First layer of encryption \[HS-DESC-FIRST-LAYER\] +### First layer of encryption {#HS-DESC-FIRST-LAYER} The first layer of HS descriptor encryption is designed to protect descriptor confidentiality against entities who don't know the public @@ -20,7 +20,7 @@ identity key of the hidden service. <a id="rend-spec-v3.txt-2.5.1.1"></a> -#### First layer encryption logic +#### First layer encryption logic {#first-layer-logic} The encryption keys and format for the first layer of encryption are generated as specified in \[HS-DESC-ENCRYPTION-KEYS\] with customization @@ -43,7 +43,7 @@ multiple of 10k bytes. <a id="rend-spec-v3.txt-2.5.1.2"></a> -#### First layer plaintext format +#### First layer plaintext format {#first-layer-plaintext} After clients decrypt the first layer of encryption, they need to parse the plaintext to get to the second layer ciphertext which is contained in the @@ -138,7 +138,7 @@ Here are all the supported fields: <a id="rend-spec-v3.txt-2.5.1.3"></a> -#### Client behavior \[FIRST-LAYER-CLIENT-BEHAVIOR\] +#### Client behavior {#FIRST-LAYER-CLIENT-BEHAVIOR} ```text The goal of clients at this stage is to decrypt the "encrypted" field as @@ -160,7 +160,7 @@ Here are all the supported fields: <a id="rend-spec-v3.txt-2.5.1.4"></a> -#### Hiding client authorization data +#### Hiding client authorization data {#hiding-client-auth} ```text Hidden services should avoid leaking whether client authorization is @@ -183,7 +183,7 @@ Here are all the supported fields: <a id="rend-spec-v3.txt-2.5.2"></a> -### Second layer of encryption \[HS-DESC-SECOND-LAYER\] +### Second layer of encryption {#HS-DESC-SECOND-LAYER} The second layer of descriptor encryption is designed to protect descriptor confidentiality against unauthorized clients. If client authorization is @@ -196,7 +196,7 @@ does not offer any additional security, but is still used. <a id="rend-spec-v3.txt-2.5.2.1"></a> -#### Second layer encryption keys +#### Second layer encryption keys {#second-layer-keys} The encryption keys and format for the second layer of encryption are generated as specified in \[HS-DESC-ENCRYPTION-KEYS\] with customization @@ -213,7 +213,7 @@ parameters as follows: <a id="rend-spec-v3.txt-2.5.2.2"></a> -#### Second layer plaintext format +#### Second layer plaintext format {#second-layer-plaintext} After decrypting the second layer ciphertext, clients can finally learn the list of intro points etc. The plaintext has the following format: @@ -396,7 +396,7 @@ newline. <a id="rend-spec-v3.txt-2.5.3"></a> -### Deriving hidden service descriptor encryption keys \[HS-DESC-ENCRYPTION-KEYS\] +### Deriving hidden service descriptor encryption keys {#HS-DESC-ENCRYPTION-KEYS} In this section we present the generic encryption format for hidden service descriptors. We use the same encryption format in both encryption layers, @@ -439,7 +439,7 @@ Here is the key generation logic: <a id="rend-spec-v3.txt-2.5.4"></a> -### Number of introduction points \[NUM_INTRO_POINT\] +### Number of introduction points {#NUM_INTRO_POINT} This section defines how many introduction points an hidden service descriptor can have at minimum, by default and the maximum: diff --git a/spec/rend-spec-v3/introduction-protocol.md b/spec/rend-spec-v3/introduction-protocol.md index f4e6358..ebf51b2 100644 --- a/spec/rend-spec-v3/introduction-protocol.md +++ b/spec/rend-spec-v3/introduction-protocol.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-3"></a> -# The introduction protocol \[INTRO-PROTOCOL\] +# The introduction protocol {#INTRO-PROTOCOL} The introduction protocol proceeds in three steps. @@ -30,11 +30,11 @@ the introduction request to the client. <a id="rend-spec-v3.txt-3.1"></a> -## Registering an introduction point \[REG_INTRO_POINT\] +## Registering an introduction point {#REG_INTRO_POINT} <a id="rend-spec-v3.txt-3.1.1"></a> -### Extensible ESTABLISH_INTRO protocol. \[EST_INTRO\] +### Extensible ESTABLISH_INTRO protocol. {#EST_INTRO} When a hidden service is establishing a new introduction point, it sends an ESTABLISH_INTRO cell with the following contents: @@ -115,7 +115,7 @@ later in INTRODUCE1 cells. <a id="rend-spec-v3.txt-3.1.1.1"></a> -#### Denial-of-Service Defense Extension. \[EST_INTRO_DOS_EXT\] +#### Denial-of-Service Defense Extension. {#EST_INTRO_DOS_EXT} This extension can be used to send Denial-of-Service (DoS) parameters to the introduction point in order for it to apply them for the introduction @@ -215,7 +215,7 @@ authentication keys. <a id="rend-spec-v3.txt-3.1.3"></a> -### Acknowledging establishment of introduction point \[INTRO_ESTABLISHED\] +### Acknowledging establishment of introduction point {#INTRO_ESTABLISHED} After setting up an introduction circuit, the introduction point reports its status back to the hidden service host with an INTRO_ESTABLISHED cell. @@ -240,7 +240,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.2"></a> -## Sending an INTRODUCE1 cell to the introduction point. \[SEND_INTRO1\] +## Sending an INTRODUCE1 cell to the introduction point. {#SEND_INTRO1} In order to participate in the introduction protocol, a client must know the following: @@ -267,7 +267,7 @@ or that its request will not succeed. <a id="rend-spec-v3.txt-3.2.1"></a> -### INTRODUCE1 cell format \[FMT_INTRO1\] +### INTRODUCE1 cell format {#FMT_INTRO1} When a client is connecting to an introduction point, INTRODUCE1 cells should be of the form: @@ -310,7 +310,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.2.2"></a> -### INTRODUCE_ACK cell format. \[INTRO_ACK\] +### INTRODUCE_ACK cell format. {#INTRO_ACK} An INTRODUCE_ACK cell has the following fields: @@ -335,7 +335,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.3"></a> -## Processing an INTRODUCE2 cell at the hidden service. \[PROCESS_INTRO2\] +## Processing an INTRODUCE2 cell at the hidden service. {#PROCESS_INTRO2} Upon receiving an INTRODUCE2 cell, the hidden service host checks whether the AUTH_KEY or LEGACY_KEY_ID field matches the keys for this @@ -432,7 +432,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.3.1"></a> -### Introduction handshake encryption requirements \[INTRO-HANDSHAKE-REQS\] +### Introduction handshake encryption requirements {#INTRO-HANDSHAKE-REQS} When decoding the encrypted information in an INTRODUCE2 cell, a hidden service host must be able to: @@ -580,7 +580,7 @@ AES-128 and SHA1 for this hop, we use AES-256 and SHA3-256. <a id="rend-spec-v3.txt-3.4"></a> -## Authentication during the introduction phase. \[INTRO-AUTH\] +## Authentication during the introduction phase. {#INTRO-AUTH} Hidden services may restrict access only to authorized users. One mechanism to do so is the credential mechanism, where only users who @@ -590,7 +590,7 @@ There is one defined authentication type: `ed25519`. <a id="rend-spec-v3.txt-3.4.1"></a> -### Ed25519-based authentication `ed25519` +### Ed25519-based authentication `ed25519` {#ed25519-auth} (NOTE: This section is not implemented by Tor. It is likely that we would want to change its design substantially before diff --git a/spec/rend-spec-v3/keyblinding-scheme.md b/spec/rend-spec-v3/keyblinding-scheme.md index 8a7b1a2..b69a578 100644 --- a/spec/rend-spec-v3/keyblinding-scheme.md +++ b/spec/rend-spec-v3/keyblinding-scheme.md @@ -1,10 +1,10 @@ <a id="rend-spec-v3.txt-A"></a> -# Appendix A: Signature scheme with key blinding \[KEYBLIND\] +# Appendix A: Signature scheme with key blinding {#KEYBLIND} <a id="rend-spec-v3.txt-A.1"></a> -## Key derivation overview +## Key derivation overview {#overview} As described in \[IMD:DIST\] and \[SUBCRED\] above, we require a "key blinding" system that works (roughly) as follows: @@ -37,7 +37,7 @@ There is a master keypair (sk, pk). <a id="rend-spec-v3.txt-A.2"></a> -## Tor's key derivation scheme +## Tor's key derivation scheme {#scheme} We propose the following scheme for key blinding, based on Ed25519. diff --git a/spec/rend-spec-v3/overview.md b/spec/rend-spec-v3/overview.md index cf16ff4..61aa55a 100644 --- a/spec/rend-spec-v3/overview.md +++ b/spec/rend-spec-v3/overview.md @@ -34,7 +34,7 @@ Operator -- A person running a hidden service <a id="rend-spec-v3.txt-0.1"></a> -## Improvements over previous versions +## Improvements over previous versions {#improvements} Here is a list of improvements of this proposal over the legacy hidden services: @@ -49,7 +49,7 @@ g) Advanced client authorization <a id="rend-spec-v3.txt-0.2"></a> -## Notation and vocabulary +## Notation and vocabulary {#notation} Unless specified otherwise, all multi-octet integers are big-endian. @@ -76,7 +76,7 @@ INT_4(42) is 42 % 4294967296 (32 bit). <a id="rend-spec-v3.txt-0.3"></a> -## Cryptographic building blocks +## Cryptographic building blocks {#cryptography} This specification uses the following cryptographic building blocks: @@ -147,7 +147,7 @@ value. <a id="rend-spec-v3.txt-0.4"></a> -## Protocol building blocks \[BUILDING-BLOCKS\] +## Protocol building blocks {#BUILDING-BLOCKS} In sections below, we need to transmit the locations and identities of Tor nodes. We do so in the link identification format used by @@ -183,7 +183,7 @@ server's public key. <a id="rend-spec-v3.txt-0.5"></a> -## Assigned relay cell types +## Assigned relay cell types {#relay-cell-types} These relay cell types are reserved for use in the hidden service protocol. diff --git a/spec/rend-spec-v3/protocol-overview.md b/spec/rend-spec-v3/protocol-overview.md index 173240e..afc2dd1 100644 --- a/spec/rend-spec-v3/protocol-overview.md +++ b/spec/rend-spec-v3/protocol-overview.md @@ -8,7 +8,7 @@ fully below, when we specify the protocol in more detail. <a id="rend-spec-v3.txt-1.1"></a> -## View from 10,000 feet +## View from 10,000 feet {#10000-feet} A hidden service host prepares to offer a hidden service by choosing several Tor nodes to serve as its introduction points. It builds @@ -47,7 +47,7 @@ communicate data on those streams, and so forth. <a id="rend-spec-v3.txt-1.2"></a> -## In more detail: naming hidden services \[NAMING\] +## In more detail: naming hidden services {#NAMING} A hidden service's name is its long term master identity key. This is encoded as a hostname by encoding the entire key in Base 32, including a @@ -73,7 +73,7 @@ their length. An older name might look like: <a id="rend-spec-v3.txt-1.3"></a> -## In more detail: Access control \[IMD:AC\] +## In more detail: Access control {#IMD:AC} Access control for a hidden service is imposed at multiple points through the process above. Furthermore, there is also the option to impose @@ -108,7 +108,7 @@ require the client to prove knowledge of a pre-shared private key. <a id="rend-spec-v3.txt-1.4"></a> -## In more detail: Distributing hidden service descriptors. \[IMD:DIST\] +## In more detail: Distributing hidden service descriptors. {#IMD:DIST} Periodically, hidden service descriptors become stored at different locations to prevent a single directory or small set of directories @@ -153,7 +153,7 @@ until the new keys come online. <a id="rend-spec-v3.txt-1.5"></a> -## In more detail: Scaling to multiple hosts +## In more detail: Scaling to multiple hosts {#imd-scaling} This design is compatible with our current approaches for scaling hidden services. Specifically, hidden service operators can use onionbalance to @@ -175,7 +175,7 @@ introduction points. <a id="rend-spec-v3.txt-1.7"></a> -## In more detail: Keeping crypto keys offline +## In more detail: Keeping crypto keys offline {#imd-offline-keys} In this design, a hidden service's secret identity key may be stored offline. It's used only to generate blinded signing keys, @@ -202,7 +202,7 @@ implemented as of 0.3.2.1-alpha.) <a id="rend-spec-v3.txt-1.8"></a> -## In more detail: Encryption Keys And Replay Resistance +## In more detail: Encryption Keys And Replay Resistance {#imd-encryption-keys} To avoid replays of an introduction request by an introduction point, a hidden service host must never accept the same request @@ -213,7 +213,7 @@ discussion.) <a id="rend-spec-v3.txt-1.9"></a> -## In more detail: A menagerie of keys +## In more detail: A menagerie of keys {#imd-key-menagerie} \[In the text below, an "encryption keypair" is roughly "a keypair you can do Diffie-Hellman with" and a "signing keypair" is roughly "a @@ -292,7 +292,7 @@ Public/private keypairs defined in this document: <a id="rend-spec-v3.txt-1.9.1"></a> -### In even more detail: Client authorization keys \[CLIENT-AUTH\] +### In even more detail: Client authorization keys {#CLIENT-AUTH} When client authorization is enabled, each authorized client of a hidden service has two more asymmetric keypairs which are shared with the hidden diff --git a/spec/rend-spec-v3/rendezvous-protocol.md b/spec/rend-spec-v3/rendezvous-protocol.md index 683d9e4..d102111 100644 --- a/spec/rend-spec-v3/rendezvous-protocol.md +++ b/spec/rend-spec-v3/rendezvous-protocol.md @@ -21,7 +21,7 @@ but use an anonymous 3-hop circuit if: <a id="rend-spec-v3.txt-4.1"></a> -## Establishing a rendezvous point \[EST_REND_POINT\] +## Establishing a rendezvous point {#EST_REND_POINT} The client sends the rendezvous point a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell containing a 20-byte value. @@ -50,7 +50,7 @@ connect to a hidden service. <a id="rend-spec-v3.txt-4.2"></a> -## Joining to a rendezvous point \[JOIN_REND\] +## Joining to a rendezvous point {#JOIN_REND} To complete a rendezvous, the hidden service host builds a circuit to the rendezvous point and sends a RENDEZVOUS1 cell containing: @@ -118,7 +118,7 @@ should make it extensible.\] <a id="rend-spec-v3.txt-4.3"></a> -## Using legacy hosts as rendezvous points +## Using legacy hosts as rendezvous points {#legacy-rend-hosts} \[This section is obsolete and refers to a workaround for now-obsolete Tor relay versions. It is included for historical reasons.\] diff --git a/spec/rend-spec-v3/shared-random.md b/spec/rend-spec-v3/shared-random.md index 707c7da..b06558f 100644 --- a/spec/rend-spec-v3/shared-random.md +++ b/spec/rend-spec-v3/shared-random.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-2.3"></a> -## Publishing shared random values \[PUB-SHAREDRANDOM\] +## Publishing shared random values {#PUB-SHAREDRANDOM} Our design for limiting the predictability of HSDir upload locations relies on a shared random value (SRV) that isn't predictable in advance or @@ -19,7 +19,7 @@ According to proposal 250, we add two new lines in consensuses: <a id="rend-spec-v3.txt-2.3.1"></a> -### Client behavior in the absence of shared random values +### Client behavior in the absence of shared random values {#client-disaster} If the previous or current shared random value cannot be found in a consensus, then Tor clients and services need to generate their own random @@ -36,7 +36,7 @@ found originally. <a id="rend-spec-v3.txt-2.3.2"></a> -### Hidden services and changing shared random values +### Hidden services and changing shared random values {#service-problems} It's theoretically possible that the consensus shared random values will change or disappear in the middle of a time period because of directory diff --git a/spec/srv-spec/discussion.md b/spec/srv-spec/discussion.md index ea38318..59d26df 100644 --- a/spec/srv-spec/discussion.md +++ b/spec/srv-spec/discussion.md @@ -4,7 +4,7 @@ <a id="srv-spec.txt-6.1"></a> -## Why the added complexity from proposal 225? +## Why the added complexity from proposal 225? {#why-complexity} The complexity difference between this proposal and prop225 is in part because prop225 doesn't specify how the shared random value gets to the @@ -13,7 +13,7 @@ random values can always be readily accessible to clients. <a id="srv-spec.txt-6.2"></a> -## Why do you do a commit-and-reveal protocol in 24 rounds? +## Why do you do a commit-and-reveal protocol in 24 rounds? {#why-rounds} The reader might be wondering why we span the protocol over the course of a whole day (24 hours), when only 3 rounds would be sufficient to generate a @@ -32,7 +32,7 @@ recover and rejoin the protocol. <a id="srv-spec.txt-6.3"></a> -## Why can't we recover if the 00:00UTC consensus fails? +## Why can't we recover if the 00:00UTC consensus fails? {#why-no-recovery} If the 00:00UTC consensus fails, there will be no shared random value for the whole day. In theory, we could recover by calculating the shared diff --git a/spec/srv-spec/overview.md b/spec/srv-spec/overview.md index a9f4c99..b409e6c 100644 --- a/spec/srv-spec/overview.md +++ b/spec/srv-spec/overview.md @@ -12,7 +12,7 @@ in consensus documents so that clients who need it can get it. <a id="srv-spec.txt-2.1"></a> -## Introduction to our commit-and-reveal protocol +## Introduction to our commit-and-reveal protocol {#commit-and-reveal} Every day, before voting for the consensus at 00:00UTC each authority generates a new random value and keeps it for the whole day. The authority @@ -26,7 +26,7 @@ value. The construction of these values is specified in section \[COMMITREVEAL\] <a id="srv-spec.txt-2.1"></a> -## Ten thousand feet view of the protocol +## Ten thousand feet view of the protocol {#10000-feet} Our commit-and-reveal protocol aims to produce a fresh shared random value (denoted shared_random_value here and elsewhere) every day at 00:00UTC. The @@ -62,7 +62,7 @@ Commit phase: <a id="srv-spec.txt-2.3"></a> -## How we use the consensus \[CONS\] +## How we use the consensus {#CONS} The produced shared random values need to be readily available to clients. For this reason we include them in the consensus documents. @@ -86,7 +86,7 @@ authorities support this new protocol. <a id="srv-spec.txt-2.3.1"></a> -### Inserting Shared Random Values in the consensus +### Inserting Shared Random Values in the consensus {#inserting} After voting happens, we need to be careful on how we pick which shared random values (SRV) to put in the consensus, to avoid breaking the consensus @@ -124,7 +124,7 @@ reachability consequences for hidden service clients. <a id="srv-spec.txt-2.4"></a> -## Persistent State of the Protocol \[STATE\] +## Persistent State of the Protocol {#STATE} A directory authority needs to keep a persistent state on disk of the on going protocol run. This allows an authority to join the protocol seamlessly @@ -140,7 +140,7 @@ are available. <a id="srv-spec.txt-2.5"></a> -## Protocol Illustration +## Protocol Illustration {#illustration} An illustration for better understanding the protocol can be found here: diff --git a/spec/srv-spec/protocol.md b/spec/srv-spec/protocol.md index 683b65e..67aa493 100644 --- a/spec/srv-spec/protocol.md +++ b/spec/srv-spec/protocol.md @@ -10,7 +10,7 @@ Now we go through the phases of the protocol: <a id="srv-spec.txt-3.1"></a> -## Commitment Phase \[COMMITMENTPHASE\] +## Commitment Phase {#COMMITMENTPHASE} The commit phase lasts from 00:00UTC to 12:00UTC. @@ -23,7 +23,7 @@ included in Alice's vote. <a id="srv-spec.txt-3.1.1"></a> -### Voting During Commitment Phase +### Voting During Commitment Phase {#commitment-voting} During the commit phase, each authority includes in its votes: @@ -43,7 +43,7 @@ authorities. Any subsequent commitments MUST be ignored. <a id="srv-spec.txt-3.1.2"></a> -### Persistent State During Commitment Phase \[STATECOMMIT\] +### Persistent State During Commitment Phase {#STATECOMMIT} During the commitment phase, authorities save in their persistent state the authoritative commits they have received from each authority. Only one commit @@ -51,7 +51,7 @@ per authority must be considered trusted and active at a given time. <a id="srv-spec.txt-3.2"></a> -## Reveal Phase +## Reveal Phase {#reveal-phase} The reveal phase lasts from 12:00UTC to 00:00UTC. @@ -60,7 +60,7 @@ reveal their random values. <a id="srv-spec.txt-3.2.1"></a> -### Voting During Reveal Phase +### Voting During Reveal Phase {#reveal-voting} During the reveal phase, each authority includes in its votes: @@ -77,7 +77,7 @@ the new commitment MUST be ignored. <a id="srv-spec.txt-3.2.2"></a> -### Persistent State During Reveal Phase \[STATEREVEAL\] +### Persistent State During Reveal Phase {#STATEREVEAL} During the reveal phase, authorities keep the authoritative commits from the commit phase in their persistent state. They also save any received reveals @@ -90,7 +90,7 @@ its votes. <a id="srv-spec.txt-3.3"></a> -## Shared Random Value Calculation At 00:00UTC +## Shared Random Value Calculation At 00:00UTC {#midnight-utc} Finally, at 00:00UTC every day, authorities compute a fresh shared random value and this value must be added to the consensus so clients can use it. @@ -107,7 +107,7 @@ would in the first round of the commitment phase (section \[COMMITMENTPHASE\]). <a id="srv-spec.txt-3.3.1"></a> -### Shared Randomness Calculation \[SRCALC\] +### Shared Randomness Calculation {#SRCALC} An authority that wants to derive the shared random value SRV, should use the appropriate reveal values for that time period and calculate SRV as @@ -133,7 +133,7 @@ are ordered based on the R_a value in ascending order. <a id="srv-spec.txt-3.4"></a> -## Bootstrapping Procedure +## Bootstrapping Procedure {#bootstrapping} As described in \[CONS\], two shared random values are required for the HSDir overlay periods to work properly as specified in proposal 224. Hence @@ -144,7 +144,7 @@ produced, which takes 48 hours. <a id="srv-spec.txt-3.5"></a> -## Rebooting Directory Authorities \[REBOOT\] +## Rebooting Directory Authorities {#REBOOT} The shared randomness protocol must be able to support directory authorities who leave or join in the middle of the protocol execution. diff --git a/spec/srv-spec/security-analysis.md b/spec/srv-spec/security-analysis.md index a1cc72d..d3346f9 100644 --- a/spec/srv-spec/security-analysis.md +++ b/spec/srv-spec/security-analysis.md @@ -4,7 +4,7 @@ <a id="srv-spec.txt-5.1"></a> -## Security of commit-and-reveal and future directions +## Security of commit-and-reveal and future directions {#sec-commit-and-reveal} The security of commit-and-reveal protocols is well understood, and has certain flaws. Basically, the protocol is insecure to the extent that an @@ -28,7 +28,7 @@ also see the discussion at \[RNGMESSAGING\]. <a id="srv-spec.txt-5.2"></a> -## Predicting the shared random value during reveal phase +## Predicting the shared random value during reveal phase {#sec-predicting} The reveal phase lasts 12 hours, and most authorities will send their reveal value on the first round of the reveal phase. This means that an @@ -44,7 +44,7 @@ be aware of this property. <a id="srv-spec.txt-5.3"></a> -## Partition attacks +## Partition attacks {#sec-partition} This design is not immune to certain partition attacks. We believe they don't offer much gain to an attacker as they are very easy to detect and @@ -56,7 +56,7 @@ and how to detect them. <a id="srv-spec.txt-5.3.1"></a> -### Partition attacks during commit phase +### Partition attacks during commit phase {#sec-partition-commit} A malicious directory authority could send only its commit to one single authority which results in that authority having an extra commit value for @@ -74,7 +74,7 @@ so, this means an attack is ongoing or very bad bug (highly unlikely). <a id="srv-spec.txt-5.3.2"></a> -### Partition attacks during reveal phase +### Partition attacks during reveal phase {#sec-partition-reveal} Let's consider Alice, a malicious directory authority. Alice could wait until the last reveal round, and reveal its value to half of the diff --git a/spec/srv-spec/specification-spec.md b/spec/srv-spec/specification-spec.md index 63ffaff..8118f6d 100644 --- a/spec/srv-spec/specification-spec.md +++ b/spec/srv-spec/specification-spec.md @@ -1,6 +1,6 @@ <a id="srv-spec.txt-4"></a> -# Specification \[SPEC\] +# Specification {#spec} <a id="srv-spec.txt-4.1"></a> @@ -20,7 +20,7 @@ in their votes to announce that they take part in the protocol. <a id="srv-spec.txt-4.1.1"></a> -### Computing commitments and reveals \[COMMITREVEAL\] +### Computing commitments and reveals {#COMMITREVEAL} A directory authority that wants to participate in this protocol needs to create a new pair of commitment/reveal values for every protocol @@ -48,7 +48,7 @@ REVEAL = base64-encode( TIMESTAMP || H(RN) ) <a id="srv-spec.txt-4.1.2"></a> -### Validating commitments and reveals \[VALIDATEVALUES\] +### Validating commitments and reveals {#VALIDATEVALUES} Given a COMMIT message and a REVEAL message it should be possible to verify that they indeed correspond. To do so, the client extracts the random value @@ -64,7 +64,7 @@ correspond to commit values published during the Commitment Phase. <a id="srv-spec.txt-4.1.4"></a> -### Encoding commit/reveal values in votes \[COMMITVOTE\] +### Encoding commit/reveal values in votes {#COMMITVOTE} An authority puts in its vote the commitments and reveals it has produced and seen from the other authorities. To do so, it includes the following in its @@ -82,7 +82,7 @@ REVEAL which is "sha3-256" for version 1. <a id="srv-spec.txt-4.1.5"></a> -### Shared Random Value \[SRVOTE\] +### Shared Random Value {#SRVOTE} Authorities include a shared random value (SRV) in their votes using the following encoding for the previous and current value respectively: @@ -101,14 +101,14 @@ period should be listed before the values of the current period. <a id="srv-spec.txt-4.2"></a> -## Encoding Shared Random Values in the consensus \[SRCONSENSUS\] +## Encoding Shared Random Values in the consensus {#SRCONSENSUS} Authorities insert the two active shared random values in the consensus following the same encoding format as in \[SRVOTE\]. <a id="srv-spec.txt-4.3"></a> -## Persistent state format \[STATEFORMAT\] +## Persistent state format {#STATEFORMAT} As a way to keep ground truth state in this protocol, an authority MUST keep a persistent state of the protocol. The next sub-section suggest a diff --git a/spec/tor-spec/create-created-cells.md b/spec/tor-spec/create-created-cells.md index 4574f03..2cc5f9d 100644 --- a/spec/tor-spec/create-created-cells.md +++ b/spec/tor-spec/create-created-cells.md @@ -71,7 +71,7 @@ DESTROY cell to tear down the circuit. <a id="tor-spec.txt-5.1.1"></a> -### Choosing circuit IDs in create cells +### Choosing circuit IDs in create cells {#choosing-circid} The CircID for a CREATE/CREATE2 cell is a nonzero integer, selected by the node (OP or OR) that sends the CREATE/CREATED2 cell. @@ -206,7 +206,7 @@ use the format with 'client handshake type tag'. <a id="tor-spec.txt-5.1.3"></a> -### The "TAP" handshake +### The "TAP" handshake {#TAP} This handshake uses Diffie-Hellman in Z_p and RSA to compute a set of shared keys which the client knows are shared only with a particular @@ -260,7 +260,7 @@ and 'derivative key data' value via the KDF-TOR function in 5.2.1. <a id="tor-spec.txt-5.1.4"></a> -### The "ntor" handshake +### The "ntor" handshake {#ntor} This handshake uses a set of DH handshakes to compute a set of shared keys which the client knows are shared only with a particular @@ -339,7 +339,7 @@ described in 5.2.2 and the tag m_expand. <a id="tor-spec.txt-5.1.4.1"></a> -#### The "ntor-v3" handshake +#### The "ntor-v3" handshake {#ntor-v3} This handshake extends the ntor handshake to include support for extra data transmitted as part of the handshake. Both @@ -495,7 +495,7 @@ their circuit keys. <a id="tor-spec.txt-5.1.5"></a> -### CREATE_FAST/CREATED_FAST cells +### CREATE_FAST/CREATED_FAST cells {#create_fast} When initializing the first hop of a circuit, the OP has already established the OR's identity and negotiated a secret key using TLS. @@ -529,7 +529,7 @@ networkstatus parameter as described in dir-spec.txt. <a id="tor-spec.txt-5.1.6"></a> -### Additional data in CREATE/CREATED cells +### Additional data in CREATE/CREATED cells {#additional-data} Some handshakes (currently ntor-v3 defined above) allow the client or the relay to send additional data as part of the handshake. When used in a diff --git a/spec/tor-spec/negotiating-channels.md b/spec/tor-spec/negotiating-channels.md index 2b8ebd6..ee5e974 100644 --- a/spec/tor-spec/negotiating-channels.md +++ b/spec/tor-spec/negotiating-channels.md @@ -37,7 +37,7 @@ the in-protocol handshake.\] <a id="tor-spec.txt-4.1"></a> -## Negotiating versions with VERSIONS cells +## Negotiating versions with VERSIONS cells {#VERSIONS-cells} There are multiple instances of the Tor link connection protocol. Any connection negotiated using the "certificates up front" handshake (see @@ -90,7 +90,7 @@ Link protocols differences are: <a id="tor-spec.txt-4.2"></a> -## CERTS cells +## CERTS cells {#CERTS-cells} The CERTS cell describes the keys that a Tor instance is claiming to have. It is a variable-length cell. Its payload format is: @@ -272,7 +272,7 @@ cell, and authenticated the responder. <a id="tor-spec.txt-4.4.1"></a> -### Link authentication type 1: RSA-SHA256-TLSSecret +### Link authentication type 1: RSA-SHA256-TLSSecret {#RSA-SHA256-TLSSecret} If AuthType is 1 (meaning "RSA-SHA256-TLSSecret"), then the Authentication field of the AUTHENTICATE cell contains the following: @@ -322,7 +322,7 @@ claimed to have an Ed25519 identity. <a id="tor-spec.txt-4.4.2"></a> -### Link authentication type 3: Ed25519-SHA256-RFC5705 +### Link authentication type 3: Ed25519-SHA256-RFC5705 {#Ed25519-SHA256-RFC5705} If AuthType is 3, meaning "Ed25519-SHA256-RFC5705", the Authentication field of the AuthType cell is as below: diff --git a/spec/tor-spec/preliminaries.md b/spec/tor-spec/preliminaries.md index 7967fcd..f5dce7d 100644 --- a/spec/tor-spec/preliminaries.md +++ b/spec/tor-spec/preliminaries.md @@ -128,7 +128,7 @@ source, unless otherwise noted. <a id="tor-spec.txt-0.4"></a> -## A bad hybrid encryption algorithm, for legacy purposes +## A bad hybrid encryption algorithm, for legacy purposes {#legacy-hybrid-encryption} Some specifications will refer to the "legacy hybrid encryption" of a byte sequence M with a public key KP. It is computed as follows: diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md index 364d2d2..a40f06a 100644 --- a/spec/tor-spec/relay-cells.md +++ b/spec/tor-spec/relay-cells.md @@ -116,7 +116,7 @@ still count with respect to the digests and flow control windows, though. <a id="tor-spec.txt-6.1.1"></a> -### Calculating the 'Digest' field +### Calculating the 'Digest' field {#digest-field} The 'Digest' field itself serves the purpose to check if a cell has been fully decrypted, that is, all onion layers have been removed. Having a |