diff options
-rw-r--r-- | README.md | 56 | ||||
-rwxr-xr-x | build_html.sh | 15 | ||||
-rw-r--r-- | mdbook/proposals/book.toml | 22 | ||||
-rw-r--r-- | mdbook/spec/book.toml | 41 | ||||
-rw-r--r-- | spec/INTRO.md | 77 |
5 files changed, 211 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..b7ba56a --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# DRAFT DRAFT DRAFT + +This is a demonstration, showing what the torspec.git repository +might look like after a conversion to use +[mdBook](https://rust-lang.github.io/mdBook/). + +For an example of what people will see when they look at the +_rendered_ version of this repository, see +[this temporary URL](https://people.torproject.org/~nickm/volatile/mdbook-specs/index.html). + +If and when we deploy this conversion, we should delete this section, +and have the rest of this document become the new `README.md`. + +—nickm + + + + +------------------------------ + +# Tor specification repository + +**IF YOU WANT TO READ THESE SPECS, +[GO HERE](https://people.torproject.org/~nickm/volatile/mdbook-specs/index.html).** + +This is the central location for editing and maintaining the Tor +specifications and proposals for feature changes. + +The specification is rendered at +[better-url-here](https://people.torproject.org/~nickm/volatile/mdbook-specs/index.html); +if you want to _read_ the specifications, that is the place to start. + +The official site for this repository is on +[gitlab.torproject.org](https://gitlab.torproject.org/tpo/core/torspec/) + +We use mdBook to convert these specifications into the webpages you see above. +For more information about editing them, start with the +[mdBook manual]([mdBook]((https://rust-lang.github.io/mdBook/)). + +The core of this repository is: + * `spec` — A set of markdown files which contain the specifications. + The file `src/SUMAMRY.md` controls their ordering within the + rendered specification. + * `proposals` — A directory of change proposals for the Tor protocols. + +Additionally, this repository contains: + * `mdbook` — A configuration file controlling how the specifications + are rendered. + * `attic` — Obsolete specifications describing no-longer-in-use + pieces of the Tor specification, and obsolete formats of the + existing specifications. + + + + + diff --git a/build_html.sh b/build_html.sh new file mode 100755 index 0000000..ae78080 --- /dev/null +++ b/build_html.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +set -e -u -o pipefail + +TOPLEVEL=$(realpath $(dirname "$0")) +cd "${TOPLEVEL}/proposals" +./reindex.py + +cd "${TOPLEVEL}/mdbook/spec" +mdbook build + +cd "${TOPLEVEL}/mdbook/proposals" +mdbook build + + diff --git a/mdbook/proposals/book.toml b/mdbook/proposals/book.toml new file mode 100644 index 0000000..d7b5981 --- /dev/null +++ b/mdbook/proposals/book.toml @@ -0,0 +1,22 @@ +[book] +authors = ["The Tor Project"] +language = "en" +multilingual = false +src = "../../proposals" +title = "Tor proposals (draft mdbook port)" +use-default-preprocessors = false + +[build] +build-dir = "../../html/proposals" + +[preprocessor.links] + +# [preprocessor.pagetoc] + +[output.html] +# additional-css = ["theme/pagetoc.css"] +# additional-js = ["theme/pagetoc.js"] +no-section-label = true + +[output.html.search] +enable = false
\ No newline at end of file diff --git a/mdbook/spec/book.toml b/mdbook/spec/book.toml new file mode 100644 index 0000000..de2ad99 --- /dev/null +++ b/mdbook/spec/book.toml @@ -0,0 +1,41 @@ +[book] +authors = ["The Tor Project"] +language = "en" +multilingual = false +src = "../../spec" +title = "Tor specifications (draft mdbook port)" + +[build] +build-dir = "../../html" + +# [preprocessor.pagetoc] + +[output.html] +# additional-css = ["theme/pagetoc.css"] +# additional-js = ["theme/pagetoc.js"] + +[output.html.redirect] +"/address-spec" = "https://gitweb.torproject.org/torspec.git/tree/address-spec.txt" +# "/bandwidth-file-spec" = "https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt" +"/bridgedb-spec" = "https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt" +"/cert-spec" = "https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt" +"/collector-protocol" = "https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL" +# "/control-spec" = "https://gitweb.torproject.org/torspec.git/tree/control-spec.txt" +# "/dir-spec" = "https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt" +"/dir-list-spec" = "https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt" +"/ext-orport-spec" = "https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt" +"/gettor-spec" = "https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt" +# "/padding-spec" = "https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt" +# "/path-spec" = "https://gitweb.torproject.org/torspec.git/tree/path-spec.txt" +# "/pt-spec" = "https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt" +"/rend-spec" = "https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt" +"/rend-spec-v2" = "https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt" +# "/rend-spec-v3" = "https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt" +"/socks-extensions" = "https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt" +# "/srv-spec" = "https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt" +"/tor-fw-helper-spec" = "https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt" +# "/tor-spec" = "https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt" +"/torbrowser-design" = "https://2019.www.torproject.org/projects/torbrowser/design/" +"/version-spec" = "https://gitweb.torproject.org/torspec.git/tree/version-spec.txt" +"/tor-design" = "https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf" +"/walking-onions" = "https://github.com/nmathewson/walking-onions-wip/tree/master/specs" diff --git a/spec/INTRO.md b/spec/INTRO.md new file mode 100644 index 0000000..ddfe886 --- /dev/null +++ b/spec/INTRO.md @@ -0,0 +1,77 @@ +# 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 <a +href="./proposals/BY_STATUS.html#finished-proposals-implemented-specs-not-merged">`FINISHED` +Tor proposals</a>: They are the ones that have been implemented, but +not yet merged into these documents. + +<a href="./proposals/index.html">You can also see all the Tor +proposals here.</a> + +---- + +# Permalinks + +Additionally, these URLs at `spec.toprorject.org` are intended to be +long-term permalinks. + +TODO: Revise them to point somewhere sensible again. + +<dl> +<dt><a href="/address-spec"><code>/address-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/address-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/address-spec.txt</code> (Special Hostnames in Tor)</a></dt> +<dt><a href="/bandwidth-file-spec"><code>/bandwidth-file-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt</code> (Directory Authority Bandwidth File spec)</a></dt> +<dt><a href="/bridgedb-spec"><code>/bridgedb-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt</code> (BridgeDB specification)</a></dt> +<dt><a href="/cert-spec"><code>/cert-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt</code> (Ed25519 certificates in Tor)</a></dt> +<dt><a href="/collector-protocol"><code>/collector-protocol</code></a></dt> +<dd><a href="https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL"><code>https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL</code> (Protocol of CollecTor's File Structure)</a></dt> +<dt><a href="/control-spec"><code>/control-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/control-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/control-spec.txt</code> (Tor control protocol, version 1)</a></dt> +<dt><a href="/dir-spec"><code>/dir-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt</code> (Tor directory protocol, version 3)</a></dt> +<dt><a href="/dir-list-spec"><code>/dir-list-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt</code> (Tor Directory List file format)</a></dt> +<dt><a href="/ext-orport-spec"><code>/ext-orport-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt</code> (Extended ORPort for pluggable transports)</a></dt> +<dt><a href="/gettor-spec"><code>/gettor-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt</code> (GetTor specification)</a></dt> +<dt><a href="/padding-spec"><code>/padding-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt</code> (Tor Padding Specification)</a></dt> +<dt><a href="/path-spec"><code>/path-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/path-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/path-spec.txt</code> (Tor Path Specification)</a></dt> +<dt><a href="/pt-spec"><code>/pt-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt</code> (Tor Pluggable Transport Specification, version 1)</a></dt> +<dt><a href="/rend-spec"><code>/rend-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt"><code>https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt</code> (Tor Onion Service Rendezvous Specification, Version 2)</a></dt> +<dt><a href="/rend-spec-v2"><code>/rend-spec-v2</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt"><code>https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt</code> (Tor Onion Service Rendezvous Specification, Version 2)</a></dt> +<dt><a href="/rend-spec-v3"><code>/rend-spec-v3</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt"><code>https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt</code> (Tor Onion Service Rendezvous Specification, Version 3)</a></dt> +<dt><a href="/socks-extensions"><code>/socks-extensions</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt"><code>https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt</code> (Tor's extensions to the SOCKS protocol)</a></dt> +<dt><a href="/srv-spec"><code>/srv-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt</code> (Tor Shared Random Subsystem Specification)</a></dt> +<dt><a href="/tor-fw-helper-spec"><code>/tor-fw-helper-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt</code> (Tor's (little) Firewall Helper specification)</a></dt> +<dt><a href="/tor-spec"><code>/tor-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt</code> (Tor Protocol Specification)</a></dt> +<dt><a href="/torbrowser-design"><code>/torbrowser-design</code></a></dt> +<dd><a href="https://2019.www.torproject.org/projects/torbrowser/design/"><code>https://2019.www.torproject.org/projects/torbrowser/design/</code> (The Design and Implementation of the Tor Browser)</a></dt> +<dt><a href="/version-spec"><code>/version-spec</code></a></dt> +<dd><a href="https://gitweb.torproject.org/torspec.git/tree/version-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/version-spec.txt</code> (How Tor Version Numbers Work)</a></dt> +<dt><a href="/tor-design"><code>/tor-design</code></a></dt> +<dd><a href="https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf"><code>https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf</code> (Tor: The Second-Generation Onion Router)</a></dt> +<dt><a href="/walking-onions"><code>/walking-onions</code></a></dt> +<dd><a href="https://github.com/nmathewson/walking-onions-wip/tree/master/specs"><code>https://github.com/nmathewson/walking-onions-wip/tree/master/specs</code> (Walking Onions specifications (work in progress))</a></dt> + +</dl> |