From 3457b0720834c8347d8318c1080ebc9486d77300 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Sat, 14 Oct 2023 18:52:20 -0400 Subject: Add short IDs for most long section names I've left off sections that are headings for their whole document. --- spec/bandwidth-file-spec/implementation-details.md | 6 +-- spec/bandwidth-file-spec/relay-line-format.md | 2 +- spec/bandwidth-file-spec/sample-data.md | 12 ++--- spec/bandwidth-file-spec/scaling-bandwidths.md | 2 +- spec/bridgedb-spec.md | 42 ++++------------ spec/cert-spec.md | 35 +++---------- spec/control-spec/implementation-notes.md | 18 +++---- spec/control-spec/message-format.md | 6 +-- spec/control-spec/replies.md | 58 +++++++++++----------- spec/dir-spec-intro.md | 8 +-- spec/dir-spec/client-operation.md | 29 ++--------- spec/dir-spec/directory-cache-operation.md | 16 +++--- spec/dir-spec/outline.md | 6 +-- spec/dir-spec/serving-bandwidth-list-files.md | 18 +++---- spec/dos-spec.md | 8 +-- spec/ext-orport-spec.md | 49 +++++++----------- spec/gettor-spec.md | 19 ++----- spec/glossary.md | 38 +++----------- spec/guard-spec/algorithm.md | 22 ++++---- spec/guard-spec/appendices.md | 8 +-- spec/guard-spec/guard-selection-intro.md | 10 ++-- spec/padding-spec/circuit-level-padding.md | 16 +++--- spec/padding-spec/connection-level-padding.md | 6 +-- spec/param-spec.md | 37 ++++---------- spec/path-spec/detecting-route-manipulation.md | 12 ++--- spec/path-spec/general-operation.md | 2 +- spec/path-spec/guard-nodes.md | 2 +- spec/path-spec/learning-timeouts.md | 12 ++--- spec/path-spec/old-notes.md | 7 +-- spec/pt-spec/configuration-environment.md | 8 +-- spec/pt-spec/ipc.md | 8 +-- spec/rend-spec-v3/deriving-keys.md | 26 +++++----- spec/rend-spec-v3/hsdesc-encrypt.md | 22 ++++---- spec/rend-spec-v3/introduction-protocol.md | 24 ++++----- spec/rend-spec-v3/keyblinding-scheme.md | 6 +-- spec/rend-spec-v3/overview.md | 10 ++-- spec/rend-spec-v3/protocol-overview.md | 18 +++---- spec/rend-spec-v3/rendezvous-protocol.md | 6 +-- spec/rend-spec-v3/shared-random.md | 6 +-- spec/srv-spec/discussion.md | 6 +-- spec/srv-spec/overview.md | 12 ++--- spec/srv-spec/protocol.md | 20 ++++---- spec/srv-spec/security-analysis.md | 10 ++-- spec/srv-spec/specification-spec.md | 14 +++--- spec/tor-spec/create-created-cells.md | 12 ++--- spec/tor-spec/negotiating-channels.md | 8 +-- spec/tor-spec/preliminaries.md | 2 +- spec/tor-spec/relay-cells.md | 2 +- 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 @@ -### 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. -### Additional KeyValue pair definitions +### Additional KeyValue pair definitions { #key-value-pairs } KeyValue pairs in RelayLines that current implementations generate. -#### 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 @@ -## 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. -## 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= -## 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 -## 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 -### 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 -## 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 -## 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 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 -# 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. -# 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. -## 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. -## 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. -## 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. -# 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. -# 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. -# 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: -# 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: -# 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) -``` - - - -# 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). -### 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. -## 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." -## 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. -## List of extension types +## List of extension types { #list-ext-types } \[04\] - signed-with-ed25519-key (section 2.2.1) -## 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: -## 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. -## 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. -## 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. -## 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. -## 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. -### 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 -### Phases in Bootstrap Stage 1 +### Phases in Bootstrap Stage 1 { #bootstrap-stage1 } Phase 0: tag=starting summary="Starting" @@ -321,7 +321,7 @@ established. -### Phases in Bootstrap Stage 2 +### Phases in Bootstrap Stage 2 { #bootstrap-stage2 } ```text Phase 20: @@ -408,7 +408,7 @@ indicate partial steps. -### Phases in Bootstrap Stage 3 +### Phases in Bootstrap Stage 3 { #bootstrap-stage3 } ```text Phase 76: @@ -521,7 +521,7 @@ application connections now. -## 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. -## 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. -## 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.\] -## 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". -### Circuit status changed +### Circuit status changed { #CIRC } The syntax is: @@ -301,7 +301,7 @@ The syntax is: -### Stream status changed +### Stream status changed { #STREAM } The syntax is: @@ -457,7 +457,7 @@ to talk to itself. -### OR Connection status changed +### OR Connection status changed { #ORCONN } The syntax is: @@ -530,7 +530,7 @@ events. -### 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).\] -### Log messages +### Log messages { #LOG } The syntax is: @@ -570,7 +570,7 @@ events, to avoid modifying control output when debugging. -### 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: -### 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. -### 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.) -### Our descriptor changed +### Our descriptor changed { #DESCCHANGED } Syntax: @@ -666,7 +666,7 @@ Syntax: -### 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: -### Our set of guard nodes has changed +### Our set of guard nodes has changed { #GUARD } Syntax: @@ -1147,7 +1147,7 @@ The Status values are: -### 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. -### 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. -### Per-country client stats +### Per-country client stats { #CLIENTS_SEEN } The syntax is: @@ -1229,7 +1229,7 @@ in dir-spec.txt. -### 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. -### 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. -### Signal received +### Signal received { #SIGNAL } The syntax is: @@ -1313,7 +1313,7 @@ generate any event. -### Configuration changed +### Configuration changed { #CONF_CHANGED } The syntax is: @@ -1331,7 +1331,7 @@ Undefined configuration options contain only the KEYWORD. -### 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. -### Pluggable transport launched +### Pluggable transport launched { #TRANSPORT_LAUNCHED } The syntax is: @@ -1378,7 +1378,7 @@ The syntax is: -### 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. -### 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\] -### 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. -### Token buckets refilled +### Token buckets refilled { #TB_EMPTY } The syntax is: @@ -1607,7 +1607,7 @@ These events are only generated if TestingTorNetwork is set. -### HiddenService descriptors +### HiddenService descriptors { #HS_DESC } The syntax is: @@ -1681,7 +1681,7 @@ The syntax is: -### 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. -### Network liveness has changed +### Network liveness has changed { #NETWORK_LIVENESS } Syntax: @@ -1735,7 +1735,7 @@ Syntax: -### Pluggable Transport Logs +### Pluggable Transport Logs { #PT_LOG } Syntax: @@ -1764,7 +1764,7 @@ Syntax: -### 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. -### 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: -## 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. -## 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 -## 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. -## 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. -## 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.) -### 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. ``` - - -### Managing naming - -(This section is removed; authorities no longer assign the 'Named' flag.) - - - -### 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. - - - -### Warning about a router's status - -(This section is removed; authorities no longer assign the 'Named' flag.) - ## 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. -## 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. -## 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.) -## 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.) -## 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. -## 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.) -### Consensus diff format +### Consensus diff format { #diff-format } Consensus diffs are formatted as follows: @@ -134,7 +134,7 @@ in appendix E. -### 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. -## 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. -## 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. -## 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 -## 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 @@ -### 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. -## Downloading missing certificates from other directory authorities +## Downloading missing certificates from other directory authorities { #download-missing-certs } XXX when to download certificates. -## 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. -## 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. -## 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. -### 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. -#### 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. -### 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.\] -## 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 ``` -# 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. -# 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. -## 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 `` is a filesystem path. -### Cookie-file format +#### Cookie-file format { #SAFE_COOKIE_file } The format of the cookie-file is: @@ -113,11 +100,13 @@ authentication protocol. -### 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\] -# 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. -## Protocol +### Protocol The extended server port protocol is as follows: @@ -213,11 +202,11 @@ MUST close the connection to the client. -## Command descriptions +### Command descriptions { #ext-orport-commands} -### 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. -### 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. -# 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 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 -``` @@ -44,24 +22,24 @@ RFC 2119. -## Commonly used Tor configuration terms +## Commonly used Tor configuration terms { #configuration } ORPort - Onion Router Port DirPort - Directory Port -## Tor network components +## Tor network components { #network-compoennts } -## Relays, aka OR (onion router) +## Relays, aka OR (onion router) { #relay} \[Style guide: prefer the term "Relay"\] -### 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. -## Client, aka OP (onion proxy) +## Client, aka OP (onion proxy) { #client } \[Style: the "OP" and "onion proxy" terms are deprecated.\] -## 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.) -## 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 @@ -## 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. -## 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. -## 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. -## The confirmed-guard list. \[Section:CONFIRMED\] +## The confirmed-guard list. {#CONFIRMED} \[formerly USED_GUARDS\] @@ -247,7 +247,7 @@ traffic. -## 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. -## 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). -## 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. -## 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. -## 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 `` circuit might be ready to be called @@ -516,7 +516,7 @@ them after all if the `` circuit goes down before -### 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: -## 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. -## 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. -## 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. -## 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. -## 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 @@ -# 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\]. -## 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. -## 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. -## 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. -### 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. -### 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). -### 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. -### 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. -## 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.) -## 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. -## 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. -## 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 - -# 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. -# 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 -# 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. -# Circuit-build-timeout parameters +# Circuit-build-timeout parameters {#cbt} "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts", "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq", @@ -172,7 +157,7 @@ consensus parameters. -# 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) -# 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) -# 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. -# 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. -# 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. -# 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 -# 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 @@ -# 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). -## 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. -## 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. -## 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. -## Parametrization +## Parametrization {#parameters} The following consensus parameters tune various aspects of the defense. @@ -189,7 +189,7 @@ defense. -## 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 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. -## 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 @@ -## 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. -### 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: -### 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. -### 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. -### 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. -### 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 @@ -## 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 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? -## 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 @@ -## 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. -### 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\] -### 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: -### 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 -### 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: -### 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. -### 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: -### 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 @@ -## 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: -### 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 + -### 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. -#### 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. -### 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. -### 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: -#### 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. -#### 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: -##### 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. -##### 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). -### 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). -### 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//publish` relative to @@ -395,7 +395,7 @@ anything else. -### 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 @@ -## 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. -### 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. -#### 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. -#### 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: -#### 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: -#### 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: -### 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. -#### 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: -#### 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. -### 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: -### 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 @@ -# 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. -## Registering an introduction point \[REG_INTRO_POINT\] +## Registering an introduction point {#REG_INTRO_POINT} -### 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. -#### 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. -### 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. -## 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. -### 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. -### 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. -## 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. -### 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. -## 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`. -### 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 @@ -# Appendix A: Signature scheme with key blinding \[KEYBLIND\] +# Appendix A: Signature scheme with key blinding {#KEYBLIND} -## 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). -## 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 -## 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 -## 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). -## Cryptographic building blocks +## Cryptographic building blocks {#cryptography} This specification uses the following cryptographic building blocks: @@ -147,7 +147,7 @@ value. -## 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. -## 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. -## 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. -## 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: -## 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. -## 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. -## 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. -## 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.) -## 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.) -## 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: -### 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: -## 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. -## 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.\] -## 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 @@ -## 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: -### 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. -### 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 @@ -## 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. -## 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. -## 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. -## 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\] -## 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: -## 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. -### 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. -## 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. -## 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: -## 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. -### 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. -### 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. -## Reveal Phase +## Reveal Phase {#reveal-phase} The reveal phase lasts from 12:00UTC to 00:00UTC. @@ -60,7 +60,7 @@ reveal their random values. -### 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. -### 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. -## 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\]). -### 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. -## 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. -## 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 @@ -## 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\]. -## 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. -## 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. -### 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). -### 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 @@ -# Specification \[SPEC\] +# Specification {#spec} @@ -20,7 +20,7 @@ in their votes to announce that they take part in the protocol. -### 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) ) -### 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. -### 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. -### 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. -## 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\]. -## 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. -### 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'. -### 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. -### 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. -#### 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. -### 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. -### 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.\] -## 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: -## 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. -### 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. -### 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 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. -### 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 -- cgit v1.2.3-54-g00ecf