Tor specifications
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.
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; 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, 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; 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, 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 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.)
Managing links
We're in the early stages of this spec organization, but we should still be thinking about long term maintainability.
Please think about how to keep links working in the long term. If you are going to add a link to a file, make sure that the file's name is reasonable. Before you rename a file, consider adding a redirect from the file's old name. (See the mdbook documentation for more information about how.)
If you want to link to a specific section within a file, make sure that the section has a defined anchor that makes sense. The syntax to define heading ids in mdbook looks like this:
## Heading with a long title that you want shorter name for { #shortname }
If you need to change a heading, make sure that you keep its
id the same as it was before, so that links will still work.
Finally, when you're looking for specific sections (e.g., to fix
references that say "See section 5.2.3") you can look for the HTML
anchors that our conversion process added. For example,
if you want to find dir-spec.txt section 2.1.3, look for
the anchor that says <a id="dir-spec.txt-2.1.3"></a>.
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.orgsite is currently deprecated.
/address-spechttps://gitweb.torproject.org/torspec.git/tree/address-spec.txt(Special Hostnames in Tor)/bandwidth-file-spechttps://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt(Directory Authority Bandwidth File spec)/bridgedb-spechttps://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt(BridgeDB specification)/cert-spechttps://gitweb.torproject.org/torspec.git/tree/cert-spec.txt(Ed25519 certificates in Tor)/collector-protocolhttps://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL(Protocol of CollecTor's File Structure)/control-spechttps://gitweb.torproject.org/torspec.git/tree/control-spec.txt(Tor control protocol, version 1)/dir-spechttps://gitweb.torproject.org/torspec.git/tree/dir-spec.txt(Tor directory protocol, version 3)/dir-list-spechttps://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt(Tor Directory List file format)/ext-orport-spechttps://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt(Extended ORPort for pluggable transports)/gettor-spechttps://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt(GetTor specification)/padding-spechttps://gitweb.torproject.org/torspec.git/tree/padding-spec.txt(Tor Padding Specification)/path-spechttps://gitweb.torproject.org/torspec.git/tree/path-spec.txt(Tor Path Specification)/pt-spechttps://gitweb.torproject.org/torspec.git/tree/pt-spec.txt(Tor Pluggable Transport Specification, version 1)/rend-spechttps://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt(Tor Onion Service Rendezvous Specification, Version 2)/rend-spec-v2https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt(Tor Onion Service Rendezvous Specification, Version 2)/rend-spec-v3https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt(Tor Onion Service Rendezvous Specification, Version 3)/socks-extensionshttps://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt(Tor's extensions to the SOCKS protocol)/srv-spechttps://gitweb.torproject.org/torspec.git/tree/srv-spec.txt(Tor Shared Random Subsystem Specification)/tor-fw-helper-spechttps://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt(Tor's (little) Firewall Helper specification)/tor-spechttps://gitweb.torproject.org/torspec.git/tree/tor-spec.txt(Tor Protocol Specification)/torbrowser-designhttps://2019.www.torproject.org/projects/torbrowser/design/(The Design and Implementation of the Tor Browser)/version-spechttps://gitweb.torproject.org/torspec.git/tree/version-spec.txt(How Tor Version Numbers Work)/tor-designhttps://svn.torproject.org/svn/projects/design-paper/tor-design.pdf(Tor: The Second-Generation Onion Router)/walking-onionshttps://github.com/nmathewson/walking-onions-wip/tree/master/specs(Walking Onions specifications (work in progress))