From e1555daaaaaa406210763f0b65f8dfbd11d58586 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 12 Oct 2023 14:29:30 -0400 Subject: Merge INTRO and README; fix more titles. --- mdbook/proposals/book.toml | 2 +- mdbook/spec/book.toml | 2 +- proposals/000-index.txt | 1 - spec/INTRO.md | 77 ------------------ spec/README.md | 194 +++++++++++++++++++++++++++++---------------- spec/SUMMARY.md | 3 +- 6 files changed, 131 insertions(+), 148 deletions(-) delete mode 100644 spec/INTRO.md diff --git a/mdbook/proposals/book.toml b/mdbook/proposals/book.toml index d7b5981..f3e8688 100644 --- a/mdbook/proposals/book.toml +++ b/mdbook/proposals/book.toml @@ -3,7 +3,7 @@ authors = ["The Tor Project"] language = "en" multilingual = false src = "../../proposals" -title = "Tor proposals (draft mdbook port)" +title = "Tor design proposals" use-default-preprocessors = false [build] diff --git a/mdbook/spec/book.toml b/mdbook/spec/book.toml index de2ad99..74a34b7 100644 --- a/mdbook/spec/book.toml +++ b/mdbook/spec/book.toml @@ -3,7 +3,7 @@ authors = ["The Tor Project"] language = "en" multilingual = false src = "../../spec" -title = "Tor specifications (draft mdbook port)" +title = "Tor Specifications" [build] build-dir = "../../html" diff --git a/proposals/000-index.txt b/proposals/000-index.txt index d81a0e2..8cb962f 100644 --- a/proposals/000-index.txt +++ b/proposals/000-index.txt @@ -534,4 +534,3 @@ Proposals by status: INFORMATIONAL: 159 Exit Scanning 300 Walking Onions: Scaling and Saving Bandwidth -``` diff --git a/spec/INTRO.md b/spec/INTRO.md deleted file mode 100644 index ddfe886..0000000 --- a/spec/INTRO.md +++ /dev/null @@ -1,77 +0,0 @@ -# Tor specifications - -These documents describe how Tor works, and try to do so in enough -detail to allow other compatible implementations of the Tor protocols. - -They were once a separate set of text files, but in late 2023 we -migrated to use [`mdbook`](https://rust-lang.github.io/mdBook/). -We're in the process of updating these documents to improve their quality. - -In addition to these specifications, you should look at the set of `FINISHED` -Tor proposals: They are the ones that have been implemented, but -not yet merged into these documents. - -You can also see all the Tor -proposals here. - ----- - -# Permalinks - -Additionally, these URLs at `spec.toprorject.org` are intended to be -long-term permalinks. - -TODO: Revise them to point somewhere sensible again. - -
-
/address-spec
-
https://gitweb.torproject.org/torspec.git/tree/address-spec.txt (Special Hostnames in Tor) -
/bandwidth-file-spec
-
https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt (Directory Authority Bandwidth File spec) -
/bridgedb-spec
-
https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt (BridgeDB specification) -
/cert-spec
-
https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt (Ed25519 certificates in Tor) -
/collector-protocol
-
https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL (Protocol of CollecTor's File Structure) -
/control-spec
-
https://gitweb.torproject.org/torspec.git/tree/control-spec.txt (Tor control protocol, version 1) -
/dir-spec
-
https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt (Tor directory protocol, version 3) -
/dir-list-spec
-
https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt (Tor Directory List file format) -
/ext-orport-spec
-
https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt (Extended ORPort for pluggable transports) -
/gettor-spec
-
https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt (GetTor specification) -
/padding-spec
-
https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt (Tor Padding Specification) -
/path-spec
-
https://gitweb.torproject.org/torspec.git/tree/path-spec.txt (Tor Path Specification) -
/pt-spec
-
https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt (Tor Pluggable Transport Specification, version 1) -
/rend-spec
-
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt (Tor Onion Service Rendezvous Specification, Version 2) -
/rend-spec-v2
-
https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt (Tor Onion Service Rendezvous Specification, Version 2) -
/rend-spec-v3
-
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt (Tor Onion Service Rendezvous Specification, Version 3) -
/socks-extensions
-
https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt (Tor's extensions to the SOCKS protocol) -
/srv-spec
-
https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt (Tor Shared Random Subsystem Specification) -
/tor-fw-helper-spec
-
https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt (Tor's (little) Firewall Helper specification) -
/tor-spec
-
https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt (Tor Protocol Specification) -
/torbrowser-design
-
https://2019.www.torproject.org/projects/torbrowser/design/ (The Design and Implementation of the Tor Browser) -
/version-spec
-
https://gitweb.torproject.org/torspec.git/tree/version-spec.txt (How Tor Version Numbers Work) -
/tor-design
-
https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf (Tor: The Second-Generation Onion Router) -
/walking-onions
-
https://github.com/nmathewson/walking-onions-wip/tree/master/specs (Walking Onions specifications (work in progress)) - -
diff --git a/spec/README.md b/spec/README.md index 944f029..ffc1061 100644 --- a/spec/README.md +++ b/spec/README.md @@ -1,69 +1,129 @@ # Tor specifications -This repository holds the specifications that describe how Tor works. -They try to present Tor's protocols in sufficient detail to allow -the reader to implement a compatible implementation of Tor without ever -having to read the Tor source code. - -The [proposals](/proposals) directory holds our design proposals. These -include historical documents that have now been merged into the main -specifications. For more information on the proposal process, including an -explanation of how to make new proposals, see -[001-process.txt](/proposals/001-process.txt). - -## What you can find here - -Tor's specification is pretty big, and we've broken it into a bunch of -files. - -* General interest - * [tor-spec.txt](tor-spec.txt) - contains the specification for the core Tor protocol - itself; this is a good place to start reading. - * [cert-spec.txt](cert-spec.txt) describes a certificate format used - in the other parts of the protocol. - * [dir-spec.txt](dir-spec.txt) specifies the operations and formats used to - maintain a view of the network directory. - * [padding-spec.txt](padding-spec.txt) describes a set of padding mechanisms - used to impede traffic analysis. - * [version-spec.txt](version-spec.txt) explains how to parse Tor - version numbers. - * [glossary.txt](glossary.txt) is a glossary of terms used - in the other specifications. -* Client operations - * [address-spec.txt](address-spec.txt) lists a set of special - addresses that Tor handles differently from the regular DNS system. - * [guard-spec.txt](guard-spec.txt) explains the "guard node" algorithm - that Tor clients use to avoid sampling attacks. - * [path-spec.txt](path-spec.txt) explains how clients choose their paths - through the Tor network. - * [socks-extensions](socks-extensions.txt) specifies Tor-specific - extensions to the SOCKS protocol. -* Onion services - * [rend-spec-v2.txt](rend-spec-v2.txt) is the old, deprecated version - of the onion service protocol. - * [rend-spec-v3.txt](rend-spec-v3.txt) is the current version of the - onion service protocol. -* Censorship resistance - * [bridgedb-spec.txt](bridgedb-spec.txt) explains how the `bridgedb` - server gives out bridges to censored clients. - * [gettor-spec.txt](gettor-spec.txt) describes the `gettor` tool, - which is used to download Tor in censored areas. - * [pt-spec.txt](pt-spec.txt) describes the protocol that Tor clients - and relays use to communicate with pluggable transports used for - traffic obfuscation. -* Directory authorities - * [bandwidth-file-spec.txt](bandwidth-file-spec.txt) specifies the - file format used by bandwidth-measuring tools to report their - observations to directory authorities. - * [srv-spec.txt](srv-spec.txt) specifies the protocol that - directory authorities use to securely compute shared random values - for the network. -* Controller protocol - * [control-spec.txt](control-spec.txt) explains the protocol used by - controllers to communicate with a running Tor process. -* Miscellaneous - * [dir-list-spec.txt](dir-list-spec.txt) explains the format used by - tools like the fallback directory scripts to output a list of - Tor directories for inclusion in the Tor source code. - * The [attic](attic) directory has obsolete or historical documents. +These specifications describe how Tor works. They try to present +Tor's protocols in sufficient detail to allow the reader to implement +a compatible implementation of Tor without ever having to read the Tor +source code. + +They were once a separate set of text files, but in late 2023 we +migrated to use [`mdbook`](https://rust-lang.github.io/mdBook/). +We're in the process of updating these documents to improve their quality. + +This is a living document: we are always changing and improving them +in order to make them easier and more accurate, and to improve the +quality of the Tor protocols. They are maintained as a set of +documents in a +[gitlab repository](https://gitlab.torproject.org/tpo/core/torspec/); +you can use that repository to see their history. + +Additionally, the proposals +directory holds our design proposals. These include historical +documents that have now been merged into the main specifications, and +new proposals that are still under discussion. Of particular +interrest are the +`FINISHED` +Tor proposals: They are the ones that have been implemented, but +not yet merged into these documents. + +## Getting started + +There's a lot of material here, and it's not always as well organized +as we like. We have broken it into a few major sections. + +For a table of contents, click on the menu icon to the top-left of +your browser scene. You should probably start by reading [the core +tor protocol specification](./tor-spec-intro), which describes how our +protocol works. After that, you should be able to jump around to +the topics that interest you most. The introduction of each top-level +chapter should provide an introduction. + +## How to edit these specifications + +These specifications are displayed using a tool called +[`mdbook`](https://rust-lang.github.io/mdBook/); we recommend reading +its documentation. + +To edit these specs, clone the [git repository] and edit the +appropriate file in the [`spec` directory]. These files will match +the URLs of their corresponding pages, so if you want to edit +[`tor-spec-intro.html`](./tor-spec-intro), you'll be looking for a file +called [`spec/tor-spec-intro.md`]. + +The chapter structure as a whole is defined in a special file called +[`SUMMARY.md`]. Its format is pretty restrictive; see +[the mdbook documentation](https://rust-lang.github.io/mdBook/format/summary.html) +for more information. + +You can build the website locally to see how it renders. To do this, +just install mdbook and run the `./build_html.sh` script. (You will +need to have mdbook installed to do this.) + +> TODO: Add a note about trying not to break links. + +[git repository]: https://gitlab.torproject.org/tpo/core/torspec/ +[`spec` directory]: https://gitlab.torproject.org/tpo/core/torspec/-/tree/main/spec?ref_type=heads +[`spec/tor-spec-intro.md`]: https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/spec/tor-spec-intro.md?ref_type=heads +[`SUMMARY.md`]: https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/spec/SUMMARY.md?ref_type=heads + + +---- + +## Permalinks + +Additionally, these URLs at `spec.toprorject.org` are intended to be +long-term permalinks. + +> TODO: I'd like to revise these to point somewhere sensible again. +> The `gitweb.torproject.org` site is currently deprecated. + +
+
/address-spec
+
https://gitweb.torproject.org/torspec.git/tree/address-spec.txt (Special Hostnames in Tor) +
/bandwidth-file-spec
+
https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt (Directory Authority Bandwidth File spec) +
/bridgedb-spec
+
https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt (BridgeDB specification) +
/cert-spec
+
https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt (Ed25519 certificates in Tor) +
/collector-protocol
+
https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL (Protocol of CollecTor's File Structure) +
/control-spec
+
https://gitweb.torproject.org/torspec.git/tree/control-spec.txt (Tor control protocol, version 1) +
/dir-spec
+
https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt (Tor directory protocol, version 3) +
/dir-list-spec
+
https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt (Tor Directory List file format) +
/ext-orport-spec
+
https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt (Extended ORPort for pluggable transports) +
/gettor-spec
+
https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt (GetTor specification) +
/padding-spec
+
https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt (Tor Padding Specification) +
/path-spec
+
https://gitweb.torproject.org/torspec.git/tree/path-spec.txt (Tor Path Specification) +
/pt-spec
+
https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt (Tor Pluggable Transport Specification, version 1) +
/rend-spec
+
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt (Tor Onion Service Rendezvous Specification, Version 2) +
/rend-spec-v2
+
https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt (Tor Onion Service Rendezvous Specification, Version 2) +
/rend-spec-v3
+
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt (Tor Onion Service Rendezvous Specification, Version 3) +
/socks-extensions
+
https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt (Tor's extensions to the SOCKS protocol) +
/srv-spec
+
https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt (Tor Shared Random Subsystem Specification) +
/tor-fw-helper-spec
+
https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt (Tor's (little) Firewall Helper specification) +
/tor-spec
+
https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt (Tor Protocol Specification) +
/torbrowser-design
+
https://2019.www.torproject.org/projects/torbrowser/design/ (The Design and Implementation of the Tor Browser) +
/version-spec
+
https://gitweb.torproject.org/torspec.git/tree/version-spec.txt (How Tor Version Numbers Work) +
/tor-design
+
https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf (Tor: The Second-Generation Onion Router) +
/walking-onions
+
https://github.com/nmathewson/walking-onions-wip/tree/master/specs (Walking Onions specifications (work in progress)) + +
diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md index e478e08..f1288ff 100644 --- a/spec/SUMMARY.md +++ b/spec/SUMMARY.md @@ -1,6 +1,7 @@ # Summary -[Introduction](./INTRO.md) +[Introduction](./README.md) + # The core Tor protocol - [`Tor Protocol Specification`](./tor-spec-intro.md) -- cgit v1.2.3-54-g00ecf