- tor-commits - lists.torproject.org

[torspec/main] path-spec: Fix a typo
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit c5fc1b1ddea4ba8275732cbf9e8a794b14208055 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:21:03 2021 +0300 path-spec: Fix a typo --- path-spec.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/path-spec.txt b/path-spec.txt index eb7d6e6..90c4d96 100644 --- a/path-spec.txt +++ b/path-spec.txt @@ -90,7 +90,7 @@ of their choices. is unknown (usually its target IP), but we believe the path probably supports the request according to the rules given below. -1.1. A relay's bandwidth +1.2. A relay's bandwidth Old versions of Tor did not report bandwidths in network status documents, so clients had to learn them from the routers' advertised

1 0

[torspec/main] control-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit e583d522acc39c59bb39d2f91a4e1e9e974248dc Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:29:27 2021 +0300 control-spec: Add 'Table of contents' --- control-spec.txt | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/control-spec.txt b/control-spec.txt index 25977b9..1feb250 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1,6 +1,95 @@ TC: A Tor control protocol (Version 1) +Table of Contents + + 0. Scope + 1. Protocol outline + 1.1. Forward-compatibility + 2. Message format + 2.1. Description format + 2.1.1. Notes on an escaping bug + 2.2. Commands from controller to Tor + 2.3. Replies from Tor to the controller + 2.4. General-use tokens + 3. Commands + 3.1. SETCONF + 3.2. RESETCONF + 3.3. GETCONF + 3.4. SETEVENTS + 3.5. AUTHENTICATE + 3.6. SAVECONF + 3.7. SIGNAL + 3.8. MAPADDRESS + 3.9. GETINFO + 3.10. EXTENDCIRCUIT + 3.11. SETCIRCUITPURPOSE + 3.12. SETROUTERPURPOSE + 3.13. ATTACHSTREAM + 3.14. POSTDESCRIPTOR + 3.15. REDIRECTSTREAM + 3.16. CLOSESTREAM + 3.17. CLOSECIRCUIT + 3.18. QUIT + 3.19. USEFEATURE + 3.20. RESOLVE + 3.21. PROTOCOLINFO + 3.22. LOADCONF + 3.23. TAKEOWNERSHIP + 3.24. AUTHCHALLENGE + 3.25. DROPGUARDS + 3.26. HSFETCH + 3.27. ADD_ONION + 3.28. DEL_ONION + 3.29. HSPOST + 3.30. ONION_CLIENT_AUTH_ADD + 3.31. ONION_CLIENT_AUTH_REMOVE + 3.32. ONION_CLIENT_AUTH_VIEW + 3.33. DROPOWNERSHIP + 3.34. DROPTIMEOUTS + 4. Replies + 4.1. Asynchronous events + 4.1.1. Circuit status changed + 4.1.2. Stream status changed + 4.1.3. OR Connection status changed + 4.1.4. Bandwidth used in the last second + 4.1.5. Log messages + 4.1.6. New descriptors available + 4.1.7. New Address mapping + 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver + 4.1.9. Our descriptor changed + 4.1.10. Status events + 4.1.11. Our set of guard nodes has changed + 4.1.12. Network status has changed + 4.1.13. Bandwidth used on an application stream + 4.1.14. Per-country client stats + 4.1.15. New consensus networkstatus has arrived + 4.1.16. New circuit buildtime has been set + 4.1.17. Signal received + 4.1.18. Configuration changed + 4.1.19. Circuit status changed slightly + 4.1.20. Pluggable transport launched + 4.1.21. Bandwidth used on an OR or DIR or EXIT connection + 4.1.22. Bandwidth used by all streams attached to a circuit + 4.1.23. Per-circuit cell stats + 4.1.24. Token buckets refilled + 4.1.25. HiddenService descriptors + 4.1.26. HiddenService descriptors content + 4.1.27. Network liveness has changed + 4.1.28. Pluggable Transport Logs + 4.1.29. Pluggable Transport Status + 5. Implementation notes + 5.1. Authentication + 5.2. Don't let the buffer get too big + 5.3. Backward compatibility with v0 control protocol + 5.4. Tor config options for use by controllers + 5.5. Phases from the Bootstrap status event + 5.5.1. Overview of Bootstrap reporting. + 5.5.2. Phases in Bootstrap Stage 1 + 5.5.3. Phases in Bootstrap Stage 2 + 5.5.4. Phases in Bootstrap Stage 3 + 5.6 Bootstrap phases reported by older versions of Tor + 0. Scope This document describes an implementation-specific protocol that is used

1 0

[torspec/main] dir-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit 4d4feeab4d4f873fc8533bf987e447175b12ef05 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:30:02 2021 +0300 dir-spec: Add 'Table of contents' --- dir-spec.txt | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/dir-spec.txt b/dir-spec.txt index 7ba11c0..873225d 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1,6 +1,72 @@ Tor directory protocol, version 3 +Table of Contents + + 0. Scope and preliminaries + 0.1. History + 0.2. Goals of the version 3 protoc + 0.3. Some Remaining questions + 1. Outline + 1.1. What's different from version 2? + 1.2. Document meta-format + 1.3. Signing documents + 1.4. Voting timeline + 2. Router operation and formats + 2.1. Uploading server descriptors and extra-info documents + 2.1.1. Server descriptor format + 2.1.2. Extra-info document format + 2.1.3. Nonterminals in server descriptors + 3. Directory authority operation and formats + 3.1. Creating key certificates + 3.2. Accepting server descriptor and extra-info document uploads + 3.3. Computing microdescriptors + 3.4. Exchanging votes + 3.4.1. Vote and consensus status document formats + 3.4.2. Assigning flags in a vote + 3.4.3. Serving bandwidth list files + 3.5. Downloading missing certificates from other directory authorities + 3.6. Downloading server descriptors from other directory authorities + 3.7. Downloading extra-info documents from other directory authorities + 3.8. Computing a consensus from a set of votes + 3.8.0.1. Deciding which Ids to include. + 3.8.0.2. Deciding which descriptors to include + 3.8.1. Forward compatibility + 3.8.2. Encoding port lists + 3.8.3. Computing Bandwidth Weights + 3.9. Computing consensus flavors + 3.9.1. ns consensus + 3.9.2. Microdescriptor consensus + 3.10. Exchanging detached signatures + 3.11. Publishing the signed consensus + 4. Directory cache operation + 4.1. Downloading consensus status documents from directory authorities + 4.2. Downloading server descriptors from directory authorities + 4.3. Downloading microdescriptors from directory authorities + 4.4. Downloading extra-info documents from directory authorities + 4.5. Consensus diffs + 4.5.1. Consensus diff format + 4.5.2. Serving and requesting diff + 4.6 Retrying failed downloads + 5. Client operation + 5.1. Downloading network-status documents + 5.2. Downloading server descriptors or microdescriptors + 5.3. Downloading extra-info documents + 5.4. Using directory information + 5.4.1. Choosing routers for circuits. + 5.4.2. Managing naming + 5.4.3. Software versions + 5.4.4. Warning about a router's status. + 5.5. Retrying failed downloads + 6. Standards compliance + 6.1. HTTP headers + 6.2. HTTP status codes + A. Consensus-negotiation timeline. + B. General-use HTTP URLs + C. Converting a curve25519 public key to an ed25519 public key + D. Inferring missing proto lines. + E. Limited ed diff format + 0. Scope and preliminaries This directory protocol is used by Tor version 0.2.0.x-alpha and later.

1 0

[torspec/main] version-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit 6c02a45c8d5b7dc673f7f0fb4cf58e0bef393716 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:32:06 2021 +0300 version-spec: Add 'Table of contents' --- version-spec.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/version-spec.txt b/version-spec.txt index 63782b6..615f6f2 100644 --- a/version-spec.txt +++ b/version-spec.txt @@ -1,6 +1,12 @@ HOW TOR VERSION NUMBERS WORK +Table of Contents + + 1. The Old Way + 2. The New Way + 3. Version status. + 1. The Old Way Before 0.1.0, versions were of the format:

1 0

[torspec/main] path-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit 8f906ed1c5d009e7c5180dbffef111f983dda097 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:30:36 2021 +0300 path-spec: Add 'Table of contents' --- path-spec.txt | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/path-spec.txt b/path-spec.txt index 90c4d96..b1c9fde 100644 --- a/path-spec.txt +++ b/path-spec.txt @@ -19,6 +19,48 @@ of their choices. "OPTIONAL" in this document are to be interpreted as described in RFC 2119. +Tables of Contents + + 1. General operation + 1.1. Terminology + 1.2. A relay's bandwidth + 2. Building circuits + 2.1. When we build + 2.1.0. We don't build circuits until we have enough directory info + 2.1.1. Clients build circuits preemptively + 2.1.2. Clients build circuits on demand + 2.1.3. Relays build circuits for testing reachability and bandwidth + 2.1.4. Hidden-service circuits + 2.1.5. Rate limiting of failed circuits + 2.1.6. When to tear down circuits + 2.2. Path selection and constraints + 2.2.1. Choosing an exit + 2.2.2. User configuration + 2.3. Cannibalizing circuits + 2.4. Learning when to give up ("timeout") on circuit construction + 2.4.1 Distribution choice and parameter estimation + 2.4.2. How much data to record + 2.4.3. How to record timeouts + 2.4.4. Detecting Changing Network Conditions + 2.4.5. Consensus parameters governing behavior + 2.4.6. Consensus parameters governing behavior + 2.5. Handling failure + 3. Attaching streams to circuits + 4. Hidden-service related circuits + 5. Guard nodes + 5.1. How consensus bandwidth weights factor into entry guard selection + 6. Server descriptor purposes + 7. Detecting route manipulation by Guard nodes (Path Bias) + 7.1. Measuring path construction success rates + 7.2. Measuring path usage success rates + 7.3. Scaling success counts + 7.4. Parametrization + 7.5. Known barriers to enforcement + X. Old notes + X.1. Do we actually do this? + X.2. A thing we could do to deal with reachability. + X.3. Some stuff that worries me about entry guards. 2006 Jun, Nickm. + 1. General operation Tor begins building circuits as soon as it has enough directory

1 0

[torspec/main] tor-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit fc55af27004ba1fc45fdb9196f1655806ca932f9 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:31:32 2021 +0300 tor-spec: Add 'Table of contents' --- tor-spec.txt | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/tor-spec.txt b/tor-spec.txt index de95acb..4b2c7f2 100644 --- a/tor-spec.txt +++ b/tor-spec.txt @@ -4,6 +4,77 @@ Roger Dingledine Nick Mathewson +Table of Contents + + 0. Preliminaries + 0.1. Notation and encoding + 0.2. Security parameters + 0.3. Ciphers + 0.4. A bad hybrid encryption algorithm, for legacy purposes + 1. System overview + 1.1. Keys and names + 2. Connections + 2.1. Picking TLS ciphersuites + 2.2. TLS security considerations + 3. Cell Packet format + 4. Negotiating and initializing connections + 4.1. Negotiating versions with VERSIONS cells + 4.2. CERTS cells + 4.3. AUTH_CHALLENGE cells + 4.4. AUTHENTICATE cells + 4.4.1. Link authentication type 1: RSA-SHA256-TLSSecret + 4.4.2. Link authentication type 3: Ed25519-SHA256-RFC5705 + 4.5. NETINFO cells + 5. Circuit management + 5.1. CREATE and CREATED cells + 5.1.1. Choosing circuit IDs in create cells + 5.1.2. EXTEND and EXTENDED cells + 5.1.3. The "TAP" handshake + 5.1.4. The "ntor" handshake + 5.1.5. CREATE_FAST/CREATED_FAST cells + 5.2. Setting circuit keys + 5.2.1. KDF-TOR + 5.2.2. KDF-RFC5869 + 5.3. Creating circuits + 5.3.1. Canonical connections + 5.4. Tearing down circuits + 5.5. Routing relay cells + 5.5.1. Circuit ID Checks + 5.5.2. Forward Direction + 5.5.2.1. Routing from the Origin + 5.5.2.2. Relaying Forward at Onion Routers + 5.5.3. Backward Direction + 5.5.3.1. Relaying Backward at Onion Routers + 5.5.4. Routing to the Origin + 5.6. Handling relay_early cells + 6. Application connections and stream management + 6.1. Relay cells + 6.2. Opening streams and transferring data + 6.2.1. Opening a directory stream + 6.3. Closing streams + 6.4. Remote hostname lookup + 7. Flow control + 7.1. Link throttling + 7.2. Link padding + 7.3. Circuit-level flow control + 7.3.1. SENDME Cell Format + 7.4. Stream-level flow control + 8. Handling resource exhaustion + 8.1. Memory exhaustion + 9. Subprotocol versioning + 9.1. "Link" + 9.2. "LinkAuth" + 9.3. "Relay" + 9.4. "HSIntro" + 9.5. "HSRend" + 9.6. "HSDir" + 9.7. "DirCache" + 9.8. "Desc" + 9.9. "Microdesc" + 9.10. "Cons" + 9.11. "Padding" + 9.12. "FlowCtrl" + Note: This document aims to specify Tor as currently implemented, though it may take it a little time to become fully up to date. Future versions of Tor may implement improved protocols, and compatibility is not guaranteed.

1 0

[torspec/main] address-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit 31a4d28693db46cadbf243763c0c95fbedf99608 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:27:53 2021 +0300 address-spec: Add 'Table of contents' --- address-spec.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/address-spec.txt b/address-spec.txt index 2a6f7db..98e7068 100644 --- a/address-spec.txt +++ b/address-spec.txt @@ -2,6 +2,13 @@ Special Hostnames in Tor Nick Mathewson +Table of Contents + + 1. Overview + 2. .exit + 3. .onion + 4. .noconnect + 1. Overview Most of the time, Tor treats user-specified hostnames as opaque: When

1 0

[torspec/main] socks-extensions: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit 5af83a2afd7a4490d5f1d55ff905a113169b1c7a Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Mon Aug 23 19:31:00 2021 +0300 socks-extensions: Add 'Table of contents' --- socks-extensions.txt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/socks-extensions.txt b/socks-extensions.txt index 5fd1f82..0107856 100644 --- a/socks-extensions.txt +++ b/socks-extensions.txt @@ -1,6 +1,15 @@ Tor's extensions to the SOCKS protocol +Table of Contents + + 1. Overview + 1.1. Extent of support + 2. Name lookup + 3. Other command extensions. + 4. HTTP-resistance + 5. Optimistic data + 1. Overview The SOCKS protocol provides a generic interface for TCP proxies. Client

1 0

[torspec/main] bridgedb-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit 686be04ce55da073a788aa99691c527b4c72203d Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Wed Aug 25 16:26:11 2021 +0300 bridgedb-spec: Add 'Table of contents' --- bridgedb-spec.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/bridgedb-spec.txt b/bridgedb-spec.txt index a4c4708..5ccce92 100644 --- a/bridgedb-spec.txt +++ b/bridgedb-spec.txt @@ -4,6 +4,21 @@ 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 + 0. Preliminaries This document specifies how BridgeDB processes bridge descriptor files

1 0

[torspec/main] cert-spec: Add 'Table of contents'
by dgoulet＠torproject.org 27 Sep '21

27 Sep '21

commit b5494af92f12291f80b9441e67c4ea0071bb6cd5 Author: Oleh Franchuk <0x00.gear(a)gmail.com> Date: Wed Aug 25 16:31:59 2021 +0300 cert-spec: Add 'Table of contents' --- cert-spec.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/cert-spec.txt b/cert-spec.txt index 08d754d..1782141 100644 --- a/cert-spec.txt +++ b/cert-spec.txt @@ -1,6 +1,21 @@ Ed25519 certificates in Tor +Table of Contents + + 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) + 1. Scope and Preliminaries This document describes a certificate format that Tor uses for

1 0