Tor Protocol Specification

Roger Dingledine

Nick Mathewson

Table of Contents

0. Preliminaries

0.1. Notation and encoding

0.2. Security parameters

0.3. Ciphers

0.4. A bad hybrid encryption algorithm, for legacy purposes

1. System overview

1.1. Keys and names

2. Connections

2.1. Picking TLS ciphersuites

2.2. TLS security considerations

3. Cell Packet format

4. Negotiating and initializing connections

4.1. Negotiating versions with VERSIONS cells

4.2. CERTS cells

4.3. AUTH_CHALLENGE cells

4.4. AUTHENTICATE cells

4.4.1. Link authentication type 1: RSA-SHA256-TLSSecret

4.4.2. Link authentication type 3: Ed25519-SHA256-RFC5705

4.5. NETINFO cells

5. Circuit management

5.1. CREATE and CREATED cells

5.1.1. Choosing circuit IDs in create cells

5.1.2. EXTEND and EXTENDED cells

5.1.3. The "TAP" handshake

5.1.4. The "ntor" handshake

5.1.5. CREATE_FAST/CREATED_FAST cells

5.2. Setting circuit keys

5.2.1. KDF-TOR

5.2.2. KDF-RFC5869

5.3. Creating circuits

5.3.1. Canonical connections

5.4. Tearing down circuits

5.5. Routing relay cells

5.5.1. Circuit ID Checks

5.5.2. Forward Direction

5.5.2.1. Routing from the Origin

5.5.2.2. Relaying Forward at Onion Routers

5.5.3. Backward Direction

5.5.3.1. Relaying Backward at Onion Routers

5.5.4. Routing to the Origin

5.6. Handling relay_early cells

6. Application connections and stream management

6.1. Relay cells

6.2. Opening streams and transferring data

6.2.1. Opening a directory stream

6.3. Closing streams

6.4. Remote hostname lookup

7. Flow control

7.1. Link throttling

7.2. Link padding

7.3. Circuit-level flow control

7.3.1. SENDME Cell Format

7.4. Stream-level flow control

8. Handling resource exhaustion

8.1. Memory exhaustion

9. Subprotocol versioning

9.1. "Link"

9.2. "LinkAuth"

9.3. "Relay"

9.4. "HSIntro"

9.5. "HSRend"

9.6. "HSDir"

9.7. "DirCache"

9.8. "Desc"

9.9. "Microdesc"

9.10. "Cons"

9.11. "Padding"

9.12. "FlowCtrl"

Note: This document aims to specify Tor as currently implemented, though it

may take it a little time to become fully up to date. Future versions of Tor

may implement improved protocols, and compatibility is not guaranteed.

We may or may not remove compatibility notes for other obsolete versions of

Tor as they become obsolete.

This specification is not a design document; most design criteria

are not examined. For more information on why Tor acts as it does,

see tor-design.pdf.

0. Preliminaries

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.

0.1. Notation and encoding

KP -- a public key for an asymmetric cipher.

KS -- a private key for an asymmetric cipher.

K -- a key for a symmetric cipher.

N -- a "nonce", a random value, usually deterministically chosen

from other inputs using hashing.

a|b -- concatenation of 'a' and 'b'.

[A0 B1 C2] -- a three-byte sequence, containing the bytes with

hexadecimal values A0, B1, and C2, in that order.

H(m) -- a cryptographic hash of m.

We use "byte" and "octet" interchangeably. Possibly we shouldn't.

Some specs mention "base32". This means RFC4648, without "=" padding.

0.1.1. Encoding integers

Unless we explicitly say otherwise below, all numeric values in the

Tor protocol are encoded in network (big-endian) order. So a "32-bit

integer" means a big-endian 32-bit integer; a "2-byte" integer means

a big-endian 16-bit integer, and so forth.

0.2. Security parameters

Tor uses a stream cipher, a public-key cipher, the Diffie-Hellman

protocol, and a hash function.

KEY_LEN -- the length of the stream cipher's key, in bytes.

KP_ENC_LEN -- the length of a public-key encrypted message, in bytes.

KP_PAD_LEN -- the number of bytes added in padding for public-key

encryption, in bytes. (The largest number of bytes that can be encrypted

in a single public-key operation is therefore KP_ENC_LEN-KP_PAD_LEN.)

DH_LEN -- the number of bytes used to represent a member of the

Diffie-Hellman group.

DH_SEC_LEN -- the number of bytes used in a Diffie-Hellman private key (x).

HASH_LEN -- the length of the hash function's output, in bytes.

PAYLOAD_LEN -- The longest allowable cell payload, in bytes. (509)

CELL_LEN(v) -- The length of a Tor cell, in bytes, for link protocol

version v.

CELL_LEN(v) = 512 if v is less than 4;

= 514 otherwise.

0.3. Ciphers

These are the ciphers we use _unless otherwise specified_. Several of

them are deprecated for new use.

For a stream cipher, unless otherwise specified, we use 128-bit AES in

counter mode, with an IV of all 0 bytes. (We also require AES256.)

For a public-key cipher, unless otherwise specified, we use RSA with

1024-bit keys and a fixed exponent of 65537. We use OAEP-MGF1

padding, with SHA-1 as its digest function. We leave the optional

"Label" parameter unset. (For OAEP padding, see

ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/pkcs-1v2-1.pdf)

We also use the Curve25519 group and the Ed25519 signature format in

several places.

For Diffie-Hellman, unless otherwise specified, we use a generator

(g) of 2. For the modulus (p), we use the 1024-bit safe prime from

rfc2409 section 6.2 whose hex representation is:

"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E08"

"8A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B"

"302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9"

"A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE6"

"49286651ECE65381FFFFFFFFFFFFFFFF"

As an optimization, implementations SHOULD choose DH private keys (x) of

320 bits. Implementations that do this MUST never use any DH key more

than once.

[May other implementations reuse their DH keys?? -RD]

[Probably not. Conceivably, you could get away with changing DH keys once

per second, but there are too many oddball attacks for me to be

comfortable that this is safe. -NM]

For a hash function, unless otherwise specified, we use SHA-1.

KEY_LEN=16.

DH_LEN=128; DH_SEC_LEN=40.

KP_ENC_LEN=128; KP_PAD_LEN=42.

HASH_LEN=20.

We also use SHA256 and SHA3-256 in some places.

When we refer to "the hash of a public key", unless otherwise

specified, we mean the SHA-1 hash of the DER encoding of an ASN.1 RSA

public key (as specified in PKCS.1).

All "random" values MUST be generated with a cryptographically

strong pseudorandom number generator seeded from a strong entropy

source, unless otherwise noted.

0.4. A bad hybrid encryption algorithm, for legacy purposes.

Some specifications will refer to the "legacy hybrid encryption" of a

byte sequence M with a public key KP. It is computed as follows:

1. If the length of M is no more than KP_ENC_LEN-KP_PAD_LEN,

pad and encrypt M with KP.

2. Otherwise, generate a KEY_LEN byte random key K.

Let M1 = the first KP_ENC_LEN-KP_PAD_LEN-KEY_LEN bytes of M,

and let M2 = the rest of M.

Pad and encrypt K|M1 with KP. Encrypt M2 with our stream cipher,

using the key K. Concatenate these encrypted values.

Note that this "hybrid encryption" approach does not prevent

an attacker from adding or removing bytes to the end of M. It also

allows attackers to modify the bytes not covered by the OAEP --

see Goldberg's PET2006 paper for details. Do not use it as the basis

for new protocols! Also note that as used in Tor's protocols, case 1

never occurs.

1. System overview

Tor is a distributed overlay network designed to anonymize

low-latency TCP-based applications such as web browsing, secure shell,

and instant messaging. Clients choose a path through the network and

build a ``circuit'', in which each node (or ``onion router'' or ``OR'')

in the path knows its predecessor and successor, but no other nodes in

the circuit. Traffic flowing down the circuit is sent in fixed-size

``cells'', which are unwrapped by a symmetric key at each node (like

the layers of an onion) and relayed downstream.

1.1. Keys and names

Every Tor relay has multiple public/private keypairs:

These are 1024-bit RSA keys:

- A long-term signing-only "Identity key" used to sign documents and

certificates, and used to establish relay identity.

KP_relayid_rsa, KS_relayid_rsa.

- A medium-term TAP "Onion key" used to decrypt onion skins when accepting

circuit extend attempts. (See 5.1.) Old keys MUST be accepted for a

while after they are no longer advertised. Because of this,

relays MUST retain old keys for a while after they're rotated. (See

"onion key lifetime parameters" in dir-spec.txt.)

KP_onion_tap, KS_onion_tap.

- A short-term "Connection key" used to negotiate TLS connections.

Tor implementations MAY rotate this key as often as they like, and

SHOULD rotate this key at least once a day.

KP_conn_tls, KS_conn_tls.

This is Curve25519 key:

- A medium-term ntor "Onion key" used to handle onion key handshakes when

accepting incoming circuit extend requests. As with TAP onion keys,

old ntor keys MUST be accepted for at least one week after they are no

longer advertised. Because of this, relays MUST retain old keys for a

while after they're rotated. (See "onion key lifetime parameters" in

dir-spec.txt.)

KP_ntor, KS_ntor.

These are Ed25519 keys:

- A long-term "master identity" key. This key never

changes; it is used only to sign the "signing" key below. It may be

kept offline.

KP_relayid_ed, KS_relayid_ed.

- A medium-term "signing" key. This key is signed by the master identity

key, and must be kept online. A new one should be generated

periodically. It signs nearly everything else.

KP_relaysign_ed, KS_relaysign_ed.

- A short-term "link authentication" key, used to authenticate

the link handshake: see section 4 below. This key is signed

by the "signing" key, and should be regenerated frequently.

KP_link_ed, KS_link_ed.

KP_relayid_* together identify a router uniquely. Once a router

has used a KP_relayid_ed (an Ed25519 master identity key)

together with a given KP_relayid_rsa (RSA identity key), neither of

those keys may ever be used with a different key.

We write KP_relayid to refer to a key which is either

KP_relayid_rsa or KP_relayid_ed.

The same key or keypair should never be used for separate roles within

the Tor protocol suite, unless specifically stated. For example,

a relay's identity keys K_relayid should not also be used as the

identity keypair for a hidden service K_hs_id (see rend-spec-v3.txt).

2. Connections

Connections between two Tor relays, or between a client and a relay,

use TLS/SSLv3 for link authentication and encryption. All

implementations MUST support the SSLv3 ciphersuite

"TLS_DHE_RSA_WITH_AES_128_CBC_SHA" if it is available. They SHOULD

support better ciphersuites if available.

There are three ways to perform TLS handshakes with a Tor server. In

the first way, "certificates-up-front", both the initiator and

responder send a two-certificate chain as part of their initial

handshake. (This is supported in all Tor versions.) In the second

way, "renegotiation", the responder provides a single certificate,

and the initiator immediately performs a TLS renegotiation. (This is

supported in Tor 0.2.0.21 and later.) And in the third way,

"in-protocol", the initial TLS negotiation completes, and the

parties bootstrap themselves to mutual authentication via use of the

Tor protocol without further TLS handshaking. (This is supported in

0.2.3.6-alpha and later.)

Each of these options provides a way for the parties to learn it is

available: a client does not need to know the version of the Tor

server in order to connect to it properly.

In "certificates up-front" (a.k.a "the v1 handshake"),

the connection initiator always sends a

two-certificate chain, consisting of an X.509 certificate using a

short-term connection public key and a second, self-signed X.509

certificate containing its identity key. The other party sends a similar

certificate chain. The initiator's ClientHello MUST NOT include any

ciphersuites other than:

TLS_DHE_RSA_WITH_AES_256_CBC_SHA

TLS_DHE_RSA_WITH_AES_128_CBC_SHA

SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA

In "renegotiation" (a.k.a. "the v2 handshake"),

the connection initiator sends no certificates, and

the responder sends a single connection certificate. Once the TLS

handshake is complete, the initiator renegotiates the handshake, with each

party sending a two-certificate chain as in "certificates up-front".

The initiator's ClientHello MUST include at least one ciphersuite not in

the list above -- that's how the initiator indicates that it can

handle this handshake. For other considerations on the initiator's

ClientHello, see section 2.1 below.

In "in-protocol" (a.k.a. "the v3 handshake"), the initiator sends no

certificates, and the

responder sends a single connection certificate. The choice of

ciphersuites must be as in a "renegotiation" handshake. There are

additionally a set of constraints on the connection certificate,

which the initiator can use to learn that the in-protocol handshake

is in use. Specifically, at least one of these properties must be

true of the certificate:

* The certificate is self-signed

* Some component other than "commonName" is set in the subject or

issuer DN of the certificate.

* The commonName of the subject or issuer of the certificate ends

with a suffix other than ".net".

* The certificate's public key modulus is longer than 1024 bits.

The initiator then sends a VERSIONS cell to the responder, which then

replies with a VERSIONS cell; they have then negotiated a Tor

protocol version. Assuming that the version they negotiate is 3 or higher

(the only ones specified for use with this handshake right now), the

responder sends a CERTS cell, an AUTH_CHALLENGE cell, and a NETINFO

cell to the initiator, which may send either CERTS, AUTHENTICATE,

NETINFO if it wants to authenticate, or just NETINFO if it does not.

For backward compatibility between later handshakes and "certificates

up-front", the ClientHello of an initiator that supports a later

handshake MUST include at least one ciphersuite other than those listed

above. The connection responder examines the initiator's ciphersuite list

to see whether it includes any ciphers other than those included in the

list above. If extra ciphers are included, the responder proceeds as in

"renegotiation" and "in-protocol": it sends a single certificate and

does not request

client certificates. Otherwise (in the case that no extra ciphersuites

are included in the ClientHello) the responder proceeds as in

"certificates up-front": it requests client certificates, and sends a

two-certificate chain. In either case, once the responder has sent its

certificate or certificates, the initiator counts them. If two

certificates have been sent, it proceeds as in "certificates up-front";

otherwise, it proceeds as in "renegotiation" or "in-protocol".

To decide whether to do "renegotiation" or "in-protocol", the

initiator checks whether the responder's initial certificate matches

the criteria listed above.

All new relay implementations of the Tor protocol MUST support

backwards-compatible renegotiation; clients SHOULD do this too. If

this is not possible, new client implementations MUST support both

"renegotiation" and "in-protocol" and use the router's

published link protocols list (see dir-spec.txt on the "protocols" entry)

to decide which to use.

In all of the above handshake variants, certificates sent in the clear

SHOULD NOT include any strings to identify the host as a Tor relay. In

the "renegotiation" and "backwards-compatible renegotiation" steps, the

initiator SHOULD choose a list of ciphersuites and TLS extensions

to mimic one used by a popular web browser.

Even though the connection protocol is identical, we will think of the

initiator as either an onion router (OR) if it is willing to relay

traffic for other Tor users, or an onion proxy (OP) if it only handles

local requests. Onion proxies SHOULD NOT provide long-term-trackable

identifiers in their handshakes.

In all handshake variants, once all certificates are exchanged, all

parties receiving certificates must confirm that the identity key is as

expected. If the key is not as expected, the party must close the

connection.

(When initiating a connection, if a reasonably live consensus is

available, then the expected identity key is taken from that

consensus. But when initiating a connection otherwise, the expected

identity key is the one given in the hard-coded authority or

fallback list. Finally, when creating a connection because of an

EXTEND/EXTEND2 cell, the expected identity key is the one given in

the cell.)

When connecting to an OR, all parties SHOULD reject the connection if that

OR has a malformed or missing certificate. When accepting an incoming

connection, an OR SHOULD NOT reject incoming connections from parties with

malformed or missing certificates. (However, an OR should not believe

that an incoming connection is from another OR unless the certificates

are present and well-formed.)

[Before version 0.1.2.8-rc, ORs rejected incoming connections from ORs and

OPs alike if their certificates were missing or malformed.]

Once a TLS connection is established, the two sides send cells

(specified below) to one another. Cells are sent serially. Standard

cells are CELL_LEN(link_proto) bytes long, but variable-length cells

also exist; see Section 3. Cells may be sent embedded in TLS records

of any size or divided across TLS records, but the framing of TLS

records MUST NOT leak information about the type or contents of the

cells.

TLS connections are not permanent. Either side MAY close a connection

if there are no circuits running over it and an amount of time

(KeepalivePeriod, defaults to 5 minutes) has passed since the last time

any traffic was transmitted over the TLS connection. Clients SHOULD

also hold a TLS connection with no circuits open, if it is likely that a

circuit will be built soon using that connection.

Client-only Tor instances are encouraged to avoid using handshake

variants that include certificates, if those certificates provide

any persistent tags to the relays they contact. If clients do use

certificates, they SHOULD NOT keep using the same certificates when

their IP address changes. Clients MAY send certificates using any

of the above handshake variants.

2.1. Picking TLS ciphersuites

Clients SHOULD send a ciphersuite list chosen to emulate some popular

web browser or other program common on the internet. Clients may send

the "Fixed Cipheruite List" below. If they do not, they MUST NOT

advertise any ciphersuite that they cannot actually support, unless that

cipher is one not supported by OpenSSL 1.0.1.

The fixed ciphersuite list is:

TLS1_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

TLS1_ECDHE_RSA_WITH_AES_256_CBC_SHA

TLS1_DHE_RSA_WITH_AES_256_SHA

TLS1_DHE_DSS_WITH_AES_256_SHA

TLS1_ECDH_RSA_WITH_AES_256_CBC_SHA

TLS1_ECDH_ECDSA_WITH_AES_256_CBC_SHA

TLS1_RSA_WITH_AES_256_SHA

TLS1_ECDHE_ECDSA_WITH_RC4_128_SHA

TLS1_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

TLS1_ECDHE_RSA_WITH_RC4_128_SHA

TLS1_ECDHE_RSA_WITH_AES_128_CBC_SHA

TLS1_DHE_RSA_WITH_AES_128_SHA

TLS1_DHE_DSS_WITH_AES_128_SHA

TLS1_ECDH_RSA_WITH_RC4_128_SHA

TLS1_ECDH_RSA_WITH_AES_128_CBC_SHA

TLS1_ECDH_ECDSA_WITH_RC4_128_SHA

TLS1_ECDH_ECDSA_WITH_AES_128_CBC_SHA

SSL3_RSA_RC4_128_MD5

SSL3_RSA_RC4_128_SHA

TLS1_RSA_WITH_AES_128_SHA

TLS1_ECDHE_ECDSA_WITH_DES_192_CBC3_SHA

TLS1_ECDHE_RSA_WITH_DES_192_CBC3_SHA

SSL3_EDH_RSA_DES_192_CBC3_SHA

SSL3_EDH_DSS_DES_192_CBC3_SHA

TLS1_ECDH_RSA_WITH_DES_192_CBC3_SHA

TLS1_ECDH_ECDSA_WITH_DES_192_CBC3_SHA

SSL3_RSA_FIPS_WITH_3DES_EDE_CBC_SHA

SSL3_RSA_DES_192_CBC3_SHA

[*] The "extended renegotiation is supported" ciphersuite, 0x00ff, is

not counted when checking the list of ciphersuites.

If the client sends the Fixed Ciphersuite List, the responder MUST NOT

select any ciphersuite besides TLS_DHE_RSA_WITH_AES_256_CBC_SHA,

TLS_DHE_RSA_WITH_AES_128_CBC_SHA, and SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA:

such ciphers might not actually be supported by the client.

If the client sends a v2+ ClientHello with a list of ciphers other then

the Fixed Ciphersuite List, the responder can trust that the client

supports every cipher advertised in that list, so long as that ciphersuite

is also supported by OpenSSL 1.0.1.

Responders MUST NOT select any TLS ciphersuite that lacks ephemeral keys,

or whose symmetric keys are less then KEY_LEN bits, or whose digests are

less than HASH_LEN bits. Responders SHOULD NOT select any SSLv3

ciphersuite other than the DHE+3DES suites listed above.

2.2. TLS security considerations

Implementations MUST NOT allow TLS session resumption -- it can

exacerbate some attacks (e.g. the "Triple Handshake" attack from

Feb 2013), and it plays havoc with forward secrecy guarantees.

Implementations SHOULD NOT allow TLS compression -- although we don't

know a way to apply a CRIME-style attack to current Tor directly,

it's a waste of resources.

3. Cell Packet format

The basic unit of communication for onion routers and onion

proxies is a fixed-width "cell".

On a version 1 connection, each cell contains the following

fields:

CircID [CIRCID_LEN bytes]

Command [1 byte]

Payload (padded with padding bytes) [PAYLOAD_LEN bytes]

On a version 2 or higher connection, all cells are as in version 1

connections, except for variable-length cells, whose format is:

CircID [CIRCID_LEN octets]

Command [1 octet]

Length [2 octets; big-endian integer]

Payload (some commands MAY pad) [Length bytes]

Most variable-length cells MAY be padded with padding bytes, except

for VERSIONS cells, which MUST NOT contain any additional bytes.

(The payload of VPADDING cells consists of padding bytes.)

On a version 2 connection, variable-length cells are indicated by a

command byte equal to 7 ("VERSIONS"). On a version 3 or

higher connection, variable-length cells are indicated by a command

byte equal to 7 ("VERSIONS"), or greater than or equal to 128.

CIRCID_LEN is 2 for link protocol versions 1, 2, and 3. CIRCID_LEN

is 4 for link protocol version 4 or higher. The first VERSIONS cell,

and any cells sent before the first VERSIONS cell, always have

CIRCID_LEN == 2 for backward compatibility.

The CircID field determines which circuit, if any, the cell is

associated with.

The 'Command' field of a fixed-length cell holds one of the following

values:

0 -- PADDING (Padding) (See Sec 7.2)

1 -- CREATE (Create a circuit) (See Sec 5.1)

2 -- CREATED (Acknowledge create) (See Sec 5.1)

3 -- RELAY (End-to-end data) (See Sec 5.5 and 6)

4 -- DESTROY (Stop using a circuit) (See Sec 5.4)

5 -- CREATE_FAST (Create a circuit, no KP) (See Sec 5.1)

6 -- CREATED_FAST (Circuit created, no KP) (See Sec 5.1)

8 -- NETINFO (Time and address info) (See Sec 4.5)

9 -- RELAY_EARLY (End-to-end data; limited)(See Sec 5.6)

10 -- CREATE2 (Extended CREATE cell) (See Sec 5.1)

11 -- CREATED2 (Extended CREATED cell) (See Sec 5.1)

12 -- PADDING_NEGOTIATE (Padding negotiation) (See Sec 7.2)

Variable-length command values are:

7 -- VERSIONS (Negotiate proto version) (See Sec 4)

128 -- VPADDING (Variable-length padding) (See Sec 7.2)

129 -- CERTS (Certificates) (See Sec 4.2)

130 -- AUTH_CHALLENGE (Challenge value) (See Sec 4.3)

131 -- AUTHENTICATE (Client authentication)(See Sec 4.5)

132 -- AUTHORIZE (Client authorization) (Not yet used)

The interpretation of 'Payload' depends on the type of the cell.

VPADDING/PADDING:

Payload contains padding bytes.

CREATE/CREATE2: Payload contains the handshake challenge.

CREATED/CREATED2: Payload contains the handshake response.

RELAY/RELAY_EARLY: Payload contains the relay header and relay body.

DESTROY: Payload contains a reason for closing the circuit.

(see 5.4)

Upon receiving any other value for the command field, an OR must

drop the cell. Since more cell types may be added in the future, ORs

should generally not warn when encountering unrecognized commands.

The cell is padded up to the cell length with padding bytes.

Senders set padding bytes depending on the cell's command:

VERSIONS: Payload MUST NOT contain padding bytes.

AUTHORIZE: Payload is unspecified and reserved for future use.

Other variable-length cells:

Payload MAY contain padding bytes at the end of the cell.

Padding bytes SHOULD be set to NUL.

RELAY/RELAY_EARLY: Payload MUST be padded to PAYLOAD_LEN with padding

bytes. Padding bytes SHOULD be set to random values.

Other fixed-length cells:

Payload MUST be padded to PAYLOAD_LEN with padding bytes.

Padding bytes SHOULD be set to NUL.

We recommend random padding in RELAY/RELAY_EARLY cells, so that the cell

content is unpredictable. See the format of relay cells in section 6.1

for detail.

For other cells, TLS authenticates cell content, so randomized padding

bytes are redundant.

Receivers MUST ignore padding bytes.

PADDING cells are currently used to implement connection keepalive.

If there is no other traffic, ORs and OPs send one another a PADDING

cell every few minutes.

CREATE, CREATE2, CREATED, CREATED2, and DESTROY cells are used to

manage circuits; see section 5 below.

RELAY cells are used to send commands and data along a circuit; see

section 6 below.

VERSIONS and NETINFO cells are used to set up connections in link

protocols v2 and higher; in link protocol v3 and higher, CERTS,

AUTH_CHALLENGE, and AUTHENTICATE may also be used. See section 4

below.

4. Negotiating and initializing connections

After Tor instances negotiate handshake with either the "renegotiation" or

"in-protocol" handshakes, they must exchange a set of cells to set up

the Tor connection and make it "open" and usable for circuits.

When the renegotiation handshake is used, both parties immediately

send a VERSIONS cell (4.1 below), and after negotiating a link

protocol version (which will be 2), each send a NETINFO cell (4.5

below) to confirm their addresses and timestamps. No other intervening

cell types are allowed.

When the in-protocol handshake is used, the initiator sends a

VERSIONS cell to indicate that it will not be renegotiating. The

responder sends a VERSIONS cell, a CERTS cell (4.2 below) to give the

initiator the certificates it needs to learn the responder's

identity, an AUTH_CHALLENGE cell (4.3) that the initiator must include

as part of its answer if it chooses to authenticate, and a NETINFO

cell (4.5). As soon as it gets the CERTS cell, the initiator knows

whether the responder is correctly authenticated. At this point the

initiator behaves differently depending on whether it wants to

authenticate or not. If it does not want to authenticate, it MUST

send a NETINFO cell. If it does want to authenticate, it MUST send a

CERTS cell, an AUTHENTICATE cell (4.4), and a NETINFO. When this

handshake is in use, the first cell must be VERSIONS, VPADDING, or

AUTHORIZE, and no other cell type is allowed to intervene besides

those specified, except for VPADDING cells.

The AUTHORIZE cell type is reserved for future use by scanning-resistance

designs.

[Tor versions before 0.2.3.11-alpha did not recognize the AUTHORIZE cell,

and did not permit any command other than VERSIONS as the first cell of

the in-protocol handshake.]

4.1. Negotiating versions with VERSIONS cells

There are multiple instances of the Tor link connection protocol. Any

connection negotiated using the "certificates up front" handshake (see

section 2 above) is "version 1". In any connection where both parties

have behaved as in the "renegotiation" handshake, the link protocol

version must be 2. In any connection where both parties have behaved

as in the "in-protocol" handshake, the link protocol must be 3 or higher.

To determine the version, in any connection where the "renegotiation"

or "in-protocol" handshake was used (that is, where the responder

sent only one certificate at first and where the initiator did not

send any certificates in the first negotiation), both parties MUST

send a VERSIONS cell. In "renegotiation", they send a VERSIONS cell

right after the renegotiation is finished, before any other cells are

sent. In "in-protocol", the initiator sends a VERSIONS cell

immediately after the initial TLS handshake, and the responder

replies immediately with a VERSIONS cell. (As an exception to this rule,

if both sides support the "in-protocol" handshake, either side may send

VPADDING cells at any time.)

The payload in a VERSIONS cell is a series of big-endian two-byte

integers. Both parties MUST select as the link protocol version the

highest number contained both in the VERSIONS cell they sent and in the

versions cell they received. If they have no such version in common,

they cannot communicate and MUST close the connection. Either party MUST

close the connection if the versions cell is not well-formed (for example,

if the payload contains an odd number of bytes).

Any VERSIONS cells sent after the first VERSIONS cell MUST be ignored.

(To be interpreted correctly, later VERSIONS cells MUST have a CIRCID_LEN

matching the version negotiated with the first VERSIONS cell.)

Since the version 1 link protocol does not use the "renegotiation"

handshake, implementations MUST NOT list version 1 in their VERSIONS

cell. When the "renegotiation" handshake is used, implementations

MUST list only the version 2. When the "in-protocol" handshake is

used, implementations MUST NOT list any version before 3, and SHOULD

list at least version 3.

Link protocols differences are:

1 -- The "certs up front" handshake.

2 -- Uses the renegotiation-based handshake. Introduces

variable-length cells.

3 -- Uses the in-protocol handshake.

4 -- Increases circuit ID width to 4 bytes.

5 -- Adds support for link padding and negotiation (padding-spec.txt).

4.2. CERTS cells

The CERTS cell describes the keys that a Tor instance is claiming

to have. It is a variable-length cell. Its payload format is:

N: Number of certs in cell [1 octet]

N times:

CertType [1 octet]

CLEN [2 octets]

Certificate [CLEN octets]

Any extra octets at the end of a CERTS cell MUST be ignored.

Relevant certType values are:

1: Link key certificate certified by RSA1024 identity

2: RSA1024 Identity certificate, self-signed.

3: RSA1024 AUTHENTICATE cell link certificate, signed with RSA1024 key.

4: Ed25519 signing key, signed with identity key.

5: TLS link certificate, signed with ed25519 signing key.

6: Ed25519 AUTHENTICATE cell key, signed with ed25519 signing key.

7: Ed25519 identity, signed with RSA identity.

The certificate format for certificate types 1-3 is DER encoded

X509. For others, the format is as documented in cert-spec.txt.

Note that type 7 uses a different format from types 4-6.

A CERTS cell may have no more than one certificate of each CertType.

To authenticate the responder as having a given Ed25519,RSA identity key

combination, the initiator MUST check the following.

* The CERTS cell contains exactly one CertType 2 "ID" certificate.

* The CERTS cell contains exactly one CertType 4 Ed25519

"Id->Signing" cert.

* The CERTS cell contains exactly one CertType 5 Ed25519

"Signing->link" certificate.

* The CERTS cell contains exactly one CertType 7 "RSA->Ed25519"

cross-certificate.

* All X.509 certificates above have validAfter and validUntil dates;

no X.509 or Ed25519 certificates are expired.

* All certificates are correctly signed.

* The certified key in the Signing->Link certificate matches the

SHA256 digest of the certificate that was used to

authenticate the TLS connection.

* The identity key listed in the ID->Signing cert was used to

sign the ID->Signing Cert.

* The Signing->Link cert was signed with the Signing key listed

in the ID->Signing cert.

* The RSA->Ed25519 cross-certificate certifies the Ed25519

identity, and is signed with the RSA identity listed in the

"ID" certificate.

* The certified key in the ID certificate is a 1024-bit RSA key.

* The RSA ID certificate is correctly self-signed.

To authenticate the responder as having a given RSA identity only,

the initiator MUST check the following:

* The CERTS cell contains exactly one CertType 1 "Link" certificate.

* The CERTS cell contains exactly one CertType 2 "ID" certificate.

* Both certificates have validAfter and validUntil dates that

are not expired.

* The certified key in the Link certificate matches the

link key that was used to negotiate the TLS connection.

* The certified key in the ID certificate is a 1024-bit RSA key.

* The certified key in the ID certificate was used to sign both

certificates.

* The link certificate is correctly signed with the key in the

ID certificate

* The ID certificate is correctly self-signed.

In both cases above, checking these conditions is sufficient to

authenticate that the initiator is talking to the Tor node with the

expected identity, as certified in the ID certificate(s).

To authenticate the initiator as having a given Ed25519,RSA

identity key combination, the responder MUST check the following:

* The CERTS cell contains exactly one CertType 2 "ID" certificate.

* The CERTS cell contains exactly one CertType 4 Ed25519

"Id->Signing" certificate.

* The CERTS cell contains exactly one CertType 6 Ed25519

"Signing->auth" certificate.

* The CERTS cell contains exactly one CertType 7 "RSA->Ed25519"

cross-certificate.

* All X.509 certificates above have validAfter and validUntil dates;

no X.509 or Ed25519 certificates are expired.

* All certificates are correctly signed.

* The identity key listed in the ID->Signing cert was used to

sign the ID->Signing Cert.

* The Signing->AUTH cert was signed with the Signing key listed

in the ID->Signing cert.

* The RSA->Ed25519 cross-certificate certifies the Ed25519

identity, and is signed with the RSA identity listed in the

"ID" certificate.

* The certified key in the ID certificate is a 1024-bit RSA key.

* The RSA ID certificate is correctly self-signed.

To authenticate the initiator as having an RSA identity key only,

the responder MUST check the following:

* The CERTS cell contains exactly one CertType 3 "AUTH" certificate.

* The CERTS cell contains exactly one CertType 2 "ID" certificate.

* Both certificates have validAfter and validUntil dates that

are not expired.

* The certified key in the AUTH certificate is a 1024-bit RSA key.

* The certified key in the ID certificate is a 1024-bit RSA key.

* The certified key in the ID certificate was used to sign both

certificates.

* The auth certificate is correctly signed with the key in the

ID certificate.

* The ID certificate is correctly self-signed.

Checking these conditions is NOT sufficient to authenticate that the

initiator has the ID it claims; to do so, the cells in 4.3 and 4.4

below must be exchanged.

4.3. AUTH_CHALLENGE cells

An AUTH_CHALLENGE cell is a variable-length cell with the following

fields:

Challenge [32 octets]

N_Methods [2 octets]

Methods [2 * N_Methods octets]

It is sent from the responder to the initiator. Initiators MUST

ignore unexpected bytes at the end of the cell. Responders MUST

generate every challenge independently using a strong RNG or PRNG.

The Challenge field is a randomly generated string that the

initiator must sign (a hash of) as part of authenticating. The

methods are the authentication methods that the responder will

accept. Only two authentication methods are defined right now:

see 4.4.1 and 4.4.2 below.

4.4. AUTHENTICATE cells

If an initiator wants to authenticate, it responds to the

AUTH_CHALLENGE cell with a CERTS cell and an AUTHENTICATE cell.

The CERTS cell is as a server would send, except that instead of

sending a CertType 1 (and possibly CertType 5) certs for arbitrary link

certificates, the initiator sends a CertType 3 (and possibly

CertType 6) cert for an RSA/Ed25519 AUTHENTICATE key.

This difference is because we allow any link key type on a TLS

link, but the protocol described here will only work for specific key

types as described in 4.4.1 and 4.4.2 below.

An AUTHENTICATE cell contains the following:

AuthType [2 octets]

AuthLen [2 octets]

Authentication [AuthLen octets]

Responders MUST ignore extra bytes at the end of an AUTHENTICATE

cell. Recognized AuthTypes are 1 and 3, described in the next

two sections.

Initiators MUST NOT send an AUTHENTICATE cell before they have

verified the certificates presented in the responder's CERTS

cell, and authenticated the responder.

4.4.1. Link authentication type 1: RSA-SHA256-TLSSecret

If AuthType is 1 (meaning "RSA-SHA256-TLSSecret"), then the

Authentication field of the AUTHENTICATE cell contains the following:

TYPE: The characters "AUTH0001" [8 octets]

CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets]

SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets]

SLOG: A SHA256 hash of all bytes sent from the responder to the

initiator as part of the negotiation up to and including the

AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell,

the AUTH_CHALLENGE cell, and any padding cells. [32 octets]

CLOG: A SHA256 hash of all bytes sent from the initiator to the

responder as part of the negotiation so far; that is, the

VERSIONS cell and the CERTS cell and any padding cells. [32

octets]

SCERT: A SHA256 hash of the responder's TLS link certificate. [32

octets]

TLSSECRETS: A SHA256 HMAC, using the TLS master secret as the

secret key, of the following:

- client_random, as sent in the TLS Client Hello

- server_random, as sent in the TLS Server Hello

- the NUL terminated ASCII string:

"Tor V3 handshake TLS cross-certification"

[32 octets]

RAND: A 24 byte value, randomly chosen by the initiator. (In an

imitation of SSL3's gmt_unix_time field, older versions of Tor

sent an 8-byte timestamp as the first 8 bytes of this field;

new implementations should not do that.) [24 octets]

SIG: A signature of a SHA256 hash of all the previous fields

using the initiator's "Authenticate" key as presented. (As

always in Tor, we use OAEP-MGF1 padding; see tor-spec.txt

section 0.3.)

[variable length]

To check the AUTHENTICATE cell, a responder checks that all fields

from TYPE through TLSSECRETS contain their unique

correct values as described above, and then verifies the signature.

The server MUST ignore any extra bytes in the signed data after

the RAND field.

Responders MUST NOT accept this AuthType if the initiator has

claimed to have an Ed25519 identity.

(There is no AuthType 2: It was reserved but never implemented.)

4.4.2. Link authentication type 3: Ed25519-SHA256-RFC5705.

If AuthType is 3, meaning "Ed25519-SHA256-RFC5705", the

Authentication field of the AuthType cell is as below:

Modified values and new fields below are marked with asterisks.

TYPE: The characters "AUTH0003" [8 octets]

CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets]

SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets]

CID_ED: The initiator's Ed25519 identity key [32 octets]

SID_ED: The responder's Ed25519 identity key, or all-zero. [32 octets]

SLOG: A SHA256 hash of all bytes sent from the responder to the

initiator as part of the negotiation up to and including the

AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell,

the AUTH_CHALLENGE cell, and any padding cells. [32 octets]

CLOG: A SHA256 hash of all bytes sent from the initiator to the

responder as part of the negotiation so far; that is, the

VERSIONS cell and the CERTS cell and any padding cells. [32

octets]

SCERT: A SHA256 hash of the responder's TLS link certificate. [32

octets]

TLSSECRETS: The output of an RFC5705 Exporter function on the

TLS session, using as its inputs:

- The label string "EXPORTER FOR TOR TLS CLIENT BINDING AUTH0003"

- The context value equal to the initiator's Ed25519 identity key.

- The length 32.

[32 octets]

RAND: A 24 byte value, randomly chosen by the initiator. [24 octets]

SIG: A signature of all previous fields using the initiator's

Ed25519 authentication key (as in the cert with CertType 6).

[variable length]

To check the AUTHENTICATE cell, a responder checks that all fields

from TYPE through TLSSECRETS contain their unique

correct values as described above, and then verifies the signature.

The server MUST ignore any extra bytes in the signed data after

the RAND field.

4.5. NETINFO cells

If version 2 or higher is negotiated, each party sends the other a

NETINFO cell. The cell's payload is:

TIME (Timestamp) [4 bytes]

OTHERADDR (Other OR's address) [variable]

ATYPE (Address type) [1 byte]

ALEN (Address length) [1 byte]

AVAL (Address value in NBO) [ALEN bytes]

NMYADDR (Number of this OR's addresses) [1 byte]

NMYADDR times:

ATYPE (Address type) [1 byte]

ALEN (Address length) [1 byte]

AVAL (Address value in NBO)) [ALEN bytes]

Recognized address types (ATYPE) are:

[04] IPv4.

[06] IPv6.

ALEN MUST be 4 when ATYPE is 0x04 (IPv4) and 16 when ATYPE is 0x06

(IPv6). If the ALEN value is wrong for the given ATYPE value, then

the provided address should be ignored.

The timestamp is a big-endian unsigned integer number of seconds

since the Unix epoch. Implementations MUST ignore unexpected bytes

at the end of the cell. Clients SHOULD send "0" as their timestamp, to

avoid fingerprinting.

Implementations MAY use the timestamp value to help decide if their

clocks are skewed. Initiators MAY use "other OR's address" to help

learn which address their connections may be originating from, if they do

not know it; and to learn whether the peer will treat the current

connection as canonical. Implementations SHOULD NOT trust these

values unconditionally, especially when they come from non-authorities,

since the other party can lie about the time or IP addresses it sees.

Initiators SHOULD use "this OR's address" to make sure

that they have connected to another OR at its canonical address.

(See 5.3.1 below.)

5. Circuit management