From 334ddfe3d057ea71055e7416187b2d3f41313bef Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Sat, 14 Oct 2023 17:18:16 -0400 Subject: Remove more TOCs and merge in introductions. --- spec/SUMMARY.md | 3 - spec/bandwidth-file-spec-intro.md | 40 ++--- spec/bandwidth-file-spec/scope-preliminaries.md | 12 -- spec/control-spec-intro.md | 108 +++---------- spec/control-spec/scope.md | 22 --- spec/dir-spec-intro.md | 201 ++++++++++++++++-------- spec/dir-spec/scope-preliminaries.md | 140 ----------------- spec/guard-spec-intro.md | 81 +++++----- spec/guard-spec/introduction-motivation.md | 45 ------ spec/path-spec-intro.md | 53 +------ 10 files changed, 219 insertions(+), 486 deletions(-) delete mode 100644 spec/control-spec/scope.md delete mode 100644 spec/dir-spec/scope-preliminaries.md delete mode 100644 spec/guard-spec/introduction-motivation.md diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md index 08ae2c3..b0b4a10 100644 --- a/spec/SUMMARY.md +++ b/spec/SUMMARY.md @@ -27,7 +27,6 @@ - [Subprotocol versioning](./tor-spec/subprotocol-versioning.md) - [`Ed25519 certificates in Tor`](./cert-spec.md) - [`Tor directory protocol, version 3`](./dir-spec-intro.md) - - [Scope and preliminaries](./dir-spec/scope-preliminaries.md) - [Outline](./dir-spec/outline.md) - [Router operation and formats](./dir-spec/router-operation-formats.md) - [Uploading server descriptors and extra-info documents](./dir-spec/uploading-relay-documents.md) @@ -73,7 +72,6 @@ - [Detecting route manipulation by Guard nodes (Path Bias)](./path-spec/detecting-route-manipulation.md) - [Old notes](./path-spec/old-notes.md) - [`Tor Guard Specification`](./guard-spec-intro.md) - - [Introduction and motivation](./guard-spec/introduction-motivation.md) - [State instances](./guard-spec/state-instances.md) - [Circuit Creation, Entry Guard Selection (1000 foot view)](./guard-spec/guard-selection-intro.md) - [The algorithm.](./guard-spec/algorithm.md) @@ -139,7 +137,6 @@ # For C Tor only - [`The Tor Control Protocol`](./control-spec-intro.md) - - [Scope](./control-spec/scope.md) - [Protocol outline](./control-spec/protocol-outline.md) - [Message format](./control-spec/message-format.md) - [Commands](./control-spec/commands.md) diff --git a/spec/bandwidth-file-spec-intro.md b/spec/bandwidth-file-spec-intro.md index 93d812e..86563fa 100644 --- a/spec/bandwidth-file-spec-intro.md +++ b/spec/bandwidth-file-spec-intro.md @@ -1,32 +1,18 @@ +# Tor Bandwidth File Format + ```text - Tor Bandwidth File Format juga teor +``` -Table of Contents +This document describes the format of Tor's Bandwidth File, version +1.0.0 and later. - 1. Scope and preliminaries - 1.2. Acknowledgements - 1.3. Outline - 1.4. Format Versions - 2. Format details - 2.1. Definitions - 2.2. Header List format - 2.3. Relay Line format - 2.4. Implementation details - 2.4.1. Writing bandwidth files atomically - 2.4.2. Additional KeyValue pair definitions - 2.4.2.1. Simple Bandwidth Scanner - 2.4.2.2. Torflow - A. Sample data - A.1. Generated by Torflow - A.2. Generated by sbws version 0.1.0 - A.3. Generated by sbws version 1.0.3 - A.4. Headers generated by sbws version 1.0.4 - A.5 Generated by sbws version 1.1.0 - B. Scaling bandwidths - B.1. Scaling requirements - B.2. A linear scaling method - B.3. Quota changes - B.4. Torflow aggregation -``` +It is a new specification for the existing bandwidth file format, +which we call version 1.0.0. It also specifies new format versions +1.1.0 and later, which are backwards compatible with 1.0.0 parsers. + +Since Tor version 0.2.4.12-alpha, the directory authorities use +the Bandwidth File file called "V3BandwidthsFile" generated by +Torflow \[1\]. The details of this format are described in Torflow's +README.spec.txt. We also summarise the format in this specification. diff --git a/spec/bandwidth-file-spec/scope-preliminaries.md b/spec/bandwidth-file-spec/scope-preliminaries.md index dd17d56..0215514 100644 --- a/spec/bandwidth-file-spec/scope-preliminaries.md +++ b/spec/bandwidth-file-spec/scope-preliminaries.md @@ -2,18 +2,6 @@ # Scope and preliminaries -This document describes the format of Tor's Bandwidth File, version -1.0.0 and later. - -It is a new specification for the existing bandwidth file format, -which we call version 1.0.0. It also specifies new format versions -1.1.0 and later, which are backwards compatible with 1.0.0 parsers. - -Since Tor version 0.2.4.12-alpha, the directory authorities use -the Bandwidth File file called "V3BandwidthsFile" generated by -Torflow \[1\]. The details of this format are described in Torflow's -README.spec.txt. We also summarise the format in this specification. - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in diff --git a/spec/control-spec-intro.md b/spec/control-spec-intro.md index 08ea28e..8ce17b3 100644 --- a/spec/control-spec-intro.md +++ b/spec/control-spec-intro.md @@ -1,92 +1,24 @@ -TC: A Tor control protocol (Version 1) +# TC: A Tor control protocol (Version 1) -Table of Contents + + +## Scope + +This document describes an implementation-specific protocol that is used +for other programs (such as frontend user-interfaces) to communicate with a +locally running Tor process. It is not part of the Tor onion routing +protocol. + +This protocol replaces version 0 of TC, which is now deprecated. For +reference, TC is described in "control-spec-v0.txt". Implementors are +recommended to avoid using TC directly, but instead to use a library that +can easily be updated to use the newer protocol. (Version 0 is used by Tor +versions 0.1.0.x; the protocol in this document only works with Tor +versions in the 0.1.1.x series and later.) ```text - 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 + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC 2119. ``` diff --git a/spec/control-spec/scope.md b/spec/control-spec/scope.md deleted file mode 100644 index 9d5b3d3..0000000 --- a/spec/control-spec/scope.md +++ /dev/null @@ -1,22 +0,0 @@ - - -# Scope - -This document describes an implementation-specific protocol that is used -for other programs (such as frontend user-interfaces) to communicate with a -locally running Tor process. It is not part of the Tor onion routing -protocol. - -This protocol replaces version 0 of TC, which is now deprecated. For -reference, TC is described in "control-spec-v0.txt". Implementors are -recommended to avoid using TC directly, but instead to use a library that -can easily be updated to use the newer protocol. (Version 0 is used by Tor -versions 0.1.0.x; the protocol in this document only works with Tor -versions in the 0.1.1.x series and later.) - -```text - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL - NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - RFC 2119. -``` diff --git a/spec/dir-spec-intro.md b/spec/dir-spec-intro.md index 71b1090..0f4cafd 100644 --- a/spec/dir-spec-intro.md +++ b/spec/dir-spec-intro.md @@ -1,69 +1,140 @@ -Tor directory protocol, version 3 +# Tor directory protocol, version 3 -Table of Contents + + +This directory protocol is used by Tor version 0.2.0.x-alpha and later. +See dir-spec-v1.txt for information on the protocol used up to the +0.1.0.x series, and dir-spec-v2.txt for information on the protocol +used by the 0.1.1.x and 0.1.2.x series. + +This document merges and supersedes the following proposals: + +- 101 Voting on the Tor Directory System +- 103 Splitting identity key from regularly used signing key +- 104 Long and Short Router Descriptors + +XXX timeline +XXX fill in XXXXs + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in +RFC 2119. + + + +## History + +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 + +Early versions of Tor (0.0.2) introduced "Directory authorities": servers +that served signed "directory" documents containing a list of signed +"server descriptors", along with short summary of the status of each +router. Thus, clients could get up-to-date information on the state of +the network automatically, and be certain that the list they were getting +was attested by a trusted directory authority. + +Later versions (0.0.8) added directory caches, which download +directories from the authorities and serve them to clients. Non-caches +fetch from the caches in preference to fetching from the authorities, thus +distributing bandwidth requirements. + +Also added during the version 1 directory protocol were "router status" +documents: short documents that listed only the up/down status of the +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 + +During the Tor 0.1.1.x series, Tor revised its handling of directory +documents in order to address two major problems: ```text - 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 + * Directories had grown quite large (over 1MB), and most directory + downloads consisted mainly of server descriptors that clients + already had. + + * Every directory authority was a trust bottleneck: if a single + directory authority lied, it could make clients believe for a time + an arbitrarily distorted view of the Tor network. (Clients + trusted the most recent signed document they downloaded.) Thus, + adding more authorities would make the system less secure, not + more. ``` + +To address these, we extended the directory protocol so that +authorities now published signed "network status" documents. Each +network status listed, for every router in the network: a hash of its +identity key, a hash of its most recent descriptor, and a summary of +what the authority believed about its status. Clients would download +the authorities' network status documents in turn, and believe +statements about routers iff they were attested to by more than half of +the authorities. + +Instead of downloading all server descriptors at once, clients +downloaded only the descriptors that they did not have. Descriptors +were indexed by their digests, in order to prevent malicious caches +from giving different versions of a server descriptor to different +clients. + +Routers began working harder to upload new descriptors only when their +contents were substantially changed. + + + +### Goals of the version 3 protocol + +Version 3 of the Tor directory protocol tries to solve the following +issues: + +```text + * A great deal of bandwidth used to transmit server descriptors was + used by two fields that are not actually used by Tor routers + (namely read-history and write-history). We save about 60% by + moving them into a separate document that most clients do not + fetch or use. + + * It was possible under certain perverse circumstances for clients + to download an unusual set of network status documents, thus + partitioning themselves from clients who have a more recent and/or + typical set of documents. Even under the best of circumstances, + clients were sensitive to the ages of the network status documents + they downloaded. Therefore, instead of having the clients + correlate multiple network status documents, we have the + authorities collectively vote on a single consensus network status + document. + + * The most sensitive data in the entire network (the identity keys + of the directory authorities) needed to be stored unencrypted so + that the authorities can sign network-status documents on the fly. + Now, the authorities' identity keys are stored offline, and used + to certify medium-term signing keys that can be rotated. +``` + + + +## Some Remaining questions + +Things we could solve on a v3 timeframe: + +The SHA-1 hash is showing its age. We should do something about our +dependency on it. We could probably future-proof ourselves here in +this revision, at least so far as documents from the authorities are +concerned. + +Too many things about the authorities are hardcoded by IP. + +Perhaps we should start accepting longer identity keys for routers +too. + +Things to solve eventually: + +Requiring every client to know about every router won't scale forever. + +Requiring every directory cache to know every router won't scale +forever. diff --git a/spec/dir-spec/scope-preliminaries.md b/spec/dir-spec/scope-preliminaries.md deleted file mode 100644 index 1025c04..0000000 --- a/spec/dir-spec/scope-preliminaries.md +++ /dev/null @@ -1,140 +0,0 @@ - - -# Scope and preliminaries - -This directory protocol is used by Tor version 0.2.0.x-alpha and later. -See dir-spec-v1.txt for information on the protocol used up to the -0.1.0.x series, and dir-spec-v2.txt for information on the protocol -used by the 0.1.1.x and 0.1.2.x series. - -This document merges and supersedes the following proposals: - -- 101 Voting on the Tor Directory System -- 103 Splitting identity key from regularly used signing key -- 104 Long and Short Router Descriptors - -XXX timeline -XXX fill in XXXXs - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and -"OPTIONAL" in this document are to be interpreted as described in -RFC 2119. - - - -## History - -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 - -Early versions of Tor (0.0.2) introduced "Directory authorities": servers -that served signed "directory" documents containing a list of signed -"server descriptors", along with short summary of the status of each -router. Thus, clients could get up-to-date information on the state of -the network automatically, and be certain that the list they were getting -was attested by a trusted directory authority. - -Later versions (0.0.8) added directory caches, which download -directories from the authorities and serve them to clients. Non-caches -fetch from the caches in preference to fetching from the authorities, thus -distributing bandwidth requirements. - -Also added during the version 1 directory protocol were "router status" -documents: short documents that listed only the up/down status of the -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 - -During the Tor 0.1.1.x series, Tor revised its handling of directory -documents in order to address two major problems: - -```text - * Directories had grown quite large (over 1MB), and most directory - downloads consisted mainly of server descriptors that clients - already had. - - * Every directory authority was a trust bottleneck: if a single - directory authority lied, it could make clients believe for a time - an arbitrarily distorted view of the Tor network. (Clients - trusted the most recent signed document they downloaded.) Thus, - adding more authorities would make the system less secure, not - more. -``` - -To address these, we extended the directory protocol so that -authorities now published signed "network status" documents. Each -network status listed, for every router in the network: a hash of its -identity key, a hash of its most recent descriptor, and a summary of -what the authority believed about its status. Clients would download -the authorities' network status documents in turn, and believe -statements about routers iff they were attested to by more than half of -the authorities. - -Instead of downloading all server descriptors at once, clients -downloaded only the descriptors that they did not have. Descriptors -were indexed by their digests, in order to prevent malicious caches -from giving different versions of a server descriptor to different -clients. - -Routers began working harder to upload new descriptors only when their -contents were substantially changed. - - - -### Goals of the version 3 protocol - -Version 3 of the Tor directory protocol tries to solve the following -issues: - -```text - * A great deal of bandwidth used to transmit server descriptors was - used by two fields that are not actually used by Tor routers - (namely read-history and write-history). We save about 60% by - moving them into a separate document that most clients do not - fetch or use. - - * It was possible under certain perverse circumstances for clients - to download an unusual set of network status documents, thus - partitioning themselves from clients who have a more recent and/or - typical set of documents. Even under the best of circumstances, - clients were sensitive to the ages of the network status documents - they downloaded. Therefore, instead of having the clients - correlate multiple network status documents, we have the - authorities collectively vote on a single consensus network status - document. - - * The most sensitive data in the entire network (the identity keys - of the directory authorities) needed to be stored unencrypted so - that the authorities can sign network-status documents on the fly. - Now, the authorities' identity keys are stored offline, and used - to certify medium-term signing keys that can be rotated. -``` - - - -## Some Remaining questions - -Things we could solve on a v3 timeframe: - -The SHA-1 hash is showing its age. We should do something about our -dependency on it. We could probably future-proof ourselves here in -this revision, at least so far as documents from the authorities are -concerned. - -Too many things about the authorities are hardcoded by IP. - -Perhaps we should start accepting longer identity keys for routers -too. - -Things to solve eventually: - -Requiring every client to know about every router won't scale forever. - -Requiring every directory cache to know every router won't scale -forever. diff --git a/spec/guard-spec-intro.md b/spec/guard-spec-intro.md index e94a4f2..b7d1836 100644 --- a/spec/guard-spec-intro.md +++ b/spec/guard-spec-intro.md @@ -1,39 +1,48 @@ -Tor Guard Specification +# Tor Guard Specification + + + +## Introduction and motivation + +Tor uses entry guards to prevent an attacker who controls some +fraction of the network from observing a fraction of every user's +traffic. If users chose their entries and exits uniformly at +random from the list of servers every time they build a circuit, +then an adversary who had (k/N) of the network would deanonymize +F=(k/N)^2 of all circuits... and after a given user had built C +circuits, the attacker would see them at least once with +probability 1-(1-F)^C. With large C, the attacker would get a +sample of every user's traffic with probability 1. + +To prevent this from happening, Tor clients choose a small number +of guard nodes (e.g. 3). These guard nodes are the only +nodes that the client will connect to directly. If they are not +compromised, the user's paths are not compromised. + +This specification outlines Tor's guard housekeeping algorithm, +which tries to meet the following goals: ```text - Isis Lovecruft - George Kadianakis - Ola Bini - Nick Mathewson - -Table of Contents - - 1. Introduction and motivation - 2. State instances - 3. Circuit Creation, Entry Guard Selection (1000 foot view) - 3.1 Path selection - 3.1.1 Managing entry guards - 3.1.2 Middle and exit node selection - 3.2 Circuit Building - 4. The algorithm. - 4.0. The guards listed in the current consensus. [Section:GUARDS] - 4.1. The Sampled Guard Set. [Section:SAMPLED] - 4.2. The Usable Sample [Section:FILTERED] - 4.3. The confirmed-guard list. [Section:CONFIRMED] - 4.4. The Primary guards [Section:PRIMARY] - 4.5. Retrying guards. [Section:RETRYING] - 4.6. Selecting guards for circuits. [Section:SELECTING] - 4.7. When a circuit fails. [Section:ON_FAIL] - 4.8. When a circuit succeeds [Section:ON_SUCCESS] - 4.9. Updating the list of waiting circuits [Section:UPDATE_WAITING] - 4.10. Whenever we get a new consensus. [Section:ON_CONSENSUS] - 4.11. Deciding whether to generate a new circuit. - 4.12. When we are missing descriptors. - A. Appendices - A.0. Acknowledgements - A.1. Parameters with suggested values. [Section:PARAM_VALS] - A.2. Random values [Section:RANDOM] - A.3. Why not a sliding scale of primaryness? [Section:CVP] - A.4. Controller changes - A.5. Persistent state format + - Heuristics and algorithms for determining how and which guards + are chosen should be kept as simple and easy to understand as + possible. + + - Clients in censored regions or who are behind a fascist + firewall who connect to the Tor network should not experience + any significant disadvantage in terms of reachability or + usability. + + - Tor should make a best attempt at discovering the most + appropriate behavior, with as little user input and + configuration as possible. + + - Tor clients should discover usable guards without too much + delay. + + - Tor clients should resist (to the extent possible) attacks + that try to force them onto compromised guards. + + - Should maintain the load-balancing offered by the path selection + algorithm ``` + diff --git a/spec/guard-spec/introduction-motivation.md b/spec/guard-spec/introduction-motivation.md deleted file mode 100644 index 628cf1a..0000000 --- a/spec/guard-spec/introduction-motivation.md +++ /dev/null @@ -1,45 +0,0 @@ - - -# Introduction and motivation - -Tor uses entry guards to prevent an attacker who controls some -fraction of the network from observing a fraction of every user's -traffic. If users chose their entries and exits uniformly at -random from the list of servers every time they build a circuit, -then an adversary who had (k/N) of the network would deanonymize -F=(k/N)^2 of all circuits... and after a given user had built C -circuits, the attacker would see them at least once with -probability 1-(1-F)^C. With large C, the attacker would get a -sample of every user's traffic with probability 1. - -To prevent this from happening, Tor clients choose a small number -of guard nodes (e.g. 3). These guard nodes are the only -nodes that the client will connect to directly. If they are not -compromised, the user's paths are not compromised. - -This specification outlines Tor's guard housekeeping algorithm, -which tries to meet the following goals: - -```text - - Heuristics and algorithms for determining how and which guards - are chosen should be kept as simple and easy to understand as - possible. - - - Clients in censored regions or who are behind a fascist - firewall who connect to the Tor network should not experience - any significant disadvantage in terms of reachability or - usability. - - - Tor should make a best attempt at discovering the most - appropriate behavior, with as little user input and - configuration as possible. - - - Tor clients should discover usable guards without too much - delay. - - - Tor clients should resist (to the extent possible) attacks - that try to force them onto compromised guards. - - - Should maintain the load-balancing offered by the path selection - algorithm -``` diff --git a/spec/path-spec-intro.md b/spec/path-spec-intro.md index db16f60..107d640 100644 --- a/spec/path-spec-intro.md +++ b/spec/path-spec-intro.md @@ -1,4 +1,4 @@ -Tor Path Specification +# Tor Path Specification ```text Roger Dingledine @@ -15,51 +15,8 @@ of their choices. THIS SPEC ISN'T DONE YET. -```text - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL - NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - RFC 2119. - -Tables of Contents +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in +RFC 2119. - 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. -``` -- cgit v1.2.3-54-g00ecf