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/

The chapter structure as a whole is defined in a special file called 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 ./ script. (You will need to have mdbook installed to do this.)

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>.

Additionally, these URLs at are intended to be long-term permalinks.

TODO: I'd like to revise these to point somewhere sensible again. The site is currently deprecated.

/address-spec (Special Hostnames in Tor)
/bandwidth-file-spec (Directory Authority Bandwidth File spec)
/bridgedb-spec (BridgeDB specification)
/cert-spec (Ed25519 certificates in Tor)
/collector-protocol (Protocol of CollecTor's File Structure)
/control-spec (Tor control protocol, version 1)
/dir-spec (Tor directory protocol, version 3)
/dir-list-spec (Tor Directory List file format)
/ext-orport-spec (Extended ORPort for pluggable transports)
/gettor-spec (GetTor specification)
/padding-spec (Tor Padding Specification)
/path-spec (Tor Path Specification)
/pt-spec (Tor Pluggable Transport Specification, version 1)
/rend-spec (Tor Onion Service Rendezvous Specification, Version 2)
/rend-spec-v2 (Tor Onion Service Rendezvous Specification, Version 2)
/rend-spec-v3 (Tor Onion Service Rendezvous Specification, Version 3)
/socks-extensions (Tor's extensions to the SOCKS protocol)
/srv-spec (Tor Shared Random Subsystem Specification)
/tor-fw-helper-spec (Tor's (little) Firewall Helper specification)
/tor-spec (Tor Protocol Specification)
/torbrowser-design (The Design and Implementation of the Tor Browser)
/version-spec (How Tor Version Numbers Work)
/tor-design (Tor: The Second-Generation Onion Router)
/walking-onions (Walking Onions specifications (work in progress))