Server descriptor format
Server descriptors consist of the following items.
In lines that take multiple arguments, extra arguments SHOULD be accepted and ignored. Many of the nonterminals below are defined in section 2.1.3.
Note that many versions of Tor will generate an extra newline at the end of their descriptors. Implementations MUST tolerate one or more blank lines at the end of a single descriptor or a list of concatenated descriptors. New implementations SHOULD NOT generate such blank lines.
Server descriptor items
router
— Introduce a router descriptor
router
nickname address ORPort SOCKSPort DirPort ..- At start, exactly once.
Indicates the beginning of a server descriptor.
nickname must be a valid router nickname as specified in section 2.1.3. address must be an IPv4 address in dotted-quad format.
The last three numbers indicate the TCP ports at which this OR exposes functionality. ORPort is a port at which this OR accepts TLS connections for the main OR protocol; SOCKSPort is deprecated and should always be 0; and DirPort is the port at which this OR accepts directory-related HTTP connections. If any port is not supported, the value 0 is given instead of a port number. (At least one of DirPort and ORPort SHOULD be set; authorities MAY reject any descriptor with both DirPort and ORPort of 0.)
identity-ed25519
— Specify the router’s ed25519 identity
identity-ed25519
- certificate Object,
ED25519 CERT
- Exactly once, in second position in document.
- No extra arguments.
certificate is an Ed25519 certificate on KP_relaysign_ed by KP_relayid_ed with terminating =s removed from its base64-encoding.
When this element is present, it MUST appear as the first or second element in the router descriptor.
certificate has CERT_TYPE of [04]. It must include a signed-with-ed25519-key extension so that we can extract the master identity key.
[Before Tor 0.4.5.1-alpha, this field was optional.]
master-key-ed25519
— Redundantly specify the router’s ed25519 identity
master-key-ed25519
MasterKey ..- Exactly once.
Contains the base-64 encoded ed25519 master key
as a single argument.
If it is present,
it MUST match the identity key in identity-ed25519
.
[Before Tor 0.4.5.1-alpha, this field was optional.]
bandwidth
— Report router’s network bandwidth
bandwidth
bandwidth-avg bandwidth-burst bandwidth-observed ..- Exactly once.
- Each argument is a number in decimal, in bytes per second.
Estimated bandwidth for this router. bandwidth-avg is the volume that the OR is willing to sustain over long periods; bandwidth-burst is the volume that the OR is willing to sustain in very short intervals.
bandwidth-observed is an estimate of the capacity this relay can handle: The relay remembers the max bandwidth sustained output over any ten second period in the past 5 days, and another sustained input. bandwidth-observed value is the lesser of these two numbers.
Tor versions released before 2018 only kept bandwidth-observed for one day. These versions are no longer supported or recommended.
platform
— Describe the platform on which this relay is running
platform
string…- string is the whole rest of the line
- At most once
A human-readable string describing the system on which this OR is running. This MAY include the operating system, and SHOULD include the name and version of the software implementing the Tor protocol.
published
— Time this descriptor (and extra-info) was generated
published
date time ..- date time is YYYY-MM-DD HH:MM:SS and is in UTC
- Exactly once
When this descriptor (and its corresponding extra-info document if any) was generated.
fingerprint
– Redundant hash of ASN-1-encoding of router identity key
fingerprint
fingerprint ..- fingerprint is multiple arguments — see below.
- At most once
fingerprint is
the hash SHA1(DER(KP_relayid_rsa))
,
encoded in hex,
with a single space after every 4 characters.
A descriptor is considered invalid
(and MUST be rejected)
if the fingerprint line does not match the public key.
hibernating
— Whether the relay is hibernating
hibernating
bool ..- At most once
If the value is 1, then the Tor relay was hibernating when the descriptor was published, and shouldn’t be used to build circuits.
uptime
— How long this relay has been continuously running
uptime
number- At most once
The number of seconds that this OR process has been running.
onion-key
— Relay’s obsolete RSA TAP key
onion-key
- key Object,
RSA PUBLIC KEY
- At most once
- No extra arguments
This element MUST be present if onion-key-crosscert
is present.
Relays MUST generate this element
unless the publish-dummy-tap-key
network parameter is set to 0.
This obsolete RSA key was once used used to encrypt CREATE cells. It is no longer used. The key, if present, MUST be 1024 bits. Clients SHOULD validate this element if it is provided.
key is a DER PKCS#1 RSAPublicKey structure encoded as an Object.
onion-key-crosscert
— Reverse signature by obsolete TAP key
onion-key-crosscert
- signature cert NL a RSA signature in PEM format.
- At most once
- No extra arguments
This element MUST be present if onion-key is present. Clients SHOULD validate this element if it is provided.
This element contains an RSA signature, generated using the onion-key, of the following:
A SHA1 hash of the RSA identity key KP_relayid_rsa
from "signing-key" (see below) [20 bytes]
The Ed25519 identity key KP_relayid_ed
from "master-key-ed25519" [32 bytes]
If there is no Ed25519 identity key, or if in some future version there is no RSA identity key, the corresponding field must be zero-filled.
Parties verifying this signature MUST allow additional data beyond the 52 bytes listed above.
This signature proves that the party creating the descriptor had control over the secret key corresponding to the onion-key.
[Before Tor 0.4.5.1-alpha, this field was optional whenever identity-ed25519 was absent.]
ntor-onion-key
– KP_ntor, the circuit extension key
ntor-onion-key
KP_ntor ..- KP_ntor is base64 (and MAY have the
=
-padding). - Exactly once
KP_ntor is the curve25519 public key used for the ntor circuit extended handshake.
The key MUST be accepted for at least 1 week after any new key is published in a subsequent descriptor.
[Before Tor 0.4.5.1-alpha, this field was optional.]
ntor-onion-key-crosscert
— Reverse cert by K_ntor on KP_relayid_ed
ntor-onion-key-crosscert
Bit ..- certificate, Object
ED25519 CERT
- Exactly once
- No extra arguments
certificate is an Ed25519 certificate created with the ntor-onion-key, with type [0a]. The signed key here is the master identity key.
Bit must be “0” or “1”. It indicates the sign of the ed25519 public key corresponding to the ntor onion key. If Bit is “0”, then implementations MUST guarantee that the x-coordinate of the resulting ed25519 public key is positive. Otherwise, if Bit is “1”, then the sign of the x-coordinate MUST be negative.
To compute the ed25519 public key corresponding to a curve25519 key, and for further explanation on key formats, see appendix C.
This signature proves that the party creating the descriptor had control over the secret key corresponding to the ntor-onion-key.
[Before Tor 0.4.5.1-alpha, this field was optional whenever identity-ed25519 was absent.]
signing-key
— KP_relayid_rsa, relay’s obsolete RSA identity key
signing-key
- KP_relayid_rsa, Object
RSA PUBLIC KEY
- Exactly once
- No extra arguments
KP_relayid_rsa is the OR’s long-term RSA identity key. It MUST be 1024 bits.
The encoding is as for “onion-key” above.
accept
, reject
— Exit policy
accept
exitpatternreject
“ exitpattern- Any number
These lines describe the “exit policy”: the rules that this OR follows when deciding whether to allow a new stream to a given address.
There MUST be at least one such entry. The rules are considered in order; if no rule matches, the address will be accepted. For clarity, the last such entry SHOULD be accept : or reject :.
The syntax is as follows:
exitpattern ::= addrspec “:” portspec
portspec ::= “*” | port | port “-” port
port ::= an integer between 1 and 65535, inclusive.
(Some implementations incorrectly generate ports with value 0. Implementations SHOULD accept this, and SHOULD NOT generate it. Connections to port 0 are never permitted.)
addrspec ::= “*” | ip4spec | ip6spec
ipv4spec ::= ip4 | ip4 “/” num_ip4_bits | ip4 “/” ip4mask
ip4 ::= an IPv4 address in dotted-quad format
ip4mask ::= an IPv4 mask in dotted-quad format
num_ip4_bits ::= an integer between 0 and 32
ip6spec ::= ip6 | ip6 “/” num_ip6_bits
ip6 ::= an IPv6 address, surrounded by square brackets.
num_ip6_bits ::= an integer between 0 and 128
ipv6-policy
— Exit policy summary for IPv6
ipv6-policy
accept
|reject
PortList- At most once
An exit-policy summary
summarizing
the router’s rules for connecting to IPv6 addresses.
A missing ipv6-policy
line is equivalent to
ipv6-policy reject 1-65535
.
overload-general
— Relay is overloaded
overload-general
version YYYY-MM-DD HH:MM:SS- At most once
Indicates that a relay has reached an “overloaded state” which can be one or many of the following load metrics:
- Any OOM invocation due to memory pressure
- Any ntor onionskins are dropped
- TCP port exhaustion
The timestamp is when overload was detected by at least one metric.
It should always be on the hour;
so for example 2020-01-10 13:00:00
is an expected timestamp.
Because this is a binary state, if the line is present,
we consider that it was hit at the very least once
somewhere between the overload-general
timestamp,
and the server descriptor’s published
timestamp
which is when the document was generated.
The overload-general
line should remain in place
for 72 hours after last triggered.
If the limits are reached again in this period,
the timestamp is updated, and this 72 hour period restarts.
The version
field is set to 1
for now.
(Introduced in tor-0.4.6.1-alpha, but moved from extra-info to general descriptor in tor-0.4.6.2-alpha)
contact
— Server administrator contact information
contact
INFO….- INFO is the whole rest of the line
- At most once
Describes a way to contact the relay’s administrator, preferably including an email address and a PGP key fingerprint.
INFO is starts with the first non-whitespace
after the whitespace after contact
,
and is the whole rest of the line up to but not including the newline.
bridge-distribution-request
— Request distribution method
bridge-distribution-request
Method ..- At most once
- Bridges only
Method describes how a Bridge address is distributed. Recognized methods are:
none
— The distributor will avoid distributing your bridge address;- `any`` — The distributor will choose how to distribute your bridge address;
https
— specifies distribution via the web interface at https://bridges.torproject.org;email
— specifies distribution via the email autoresponder at bridges@torproject.org;moat
— specifies distribution via an interactive menu inside Tor Browser.
Potential future Methods must be as follows:
Method = (KeywordChar | "_") +
All bridges SHOULD include this line. Non-bridges MUST NOT include it.
The bridge distributor SHOULD treat unrecognized Method values as if they were “none”.
(Default: “any”)
[This line was introduced in 0.3.2.3-alpha, with a minimal backport to 0.2.5.16, 0.2.8.17, 0.2.9.14, 0.3.0.13, 0.3.1.9, and later.]
As of 2025, the bridge database is rdsys, which chooses from among many distribution methods. Previously, we used BridgeDB.
family
— Group relays for the purposes of path selectdion
family
name name ..- One or more name arguments
- At most once
Each name_is a relay nickname,
or hexdigest.
If two ORs list one another in their family
entries,
then OPs should treat them as a single OR for the purpose of path selection.
For example, if node A’s descriptor contains family B
,
and node B’s descriptor contains family A
,
then node A and node B should never be used on the same circuit.
Relays should omit this entry if the
publish-family-list
parameter
is 0.
family-cert
— Prove membership in a relay family
family-cert
- cert Object,
FAMILY CERT
. - Any number of times
The cert object is a family certificate, an ed25519 certificate proving this relay’s membership in the family corresponding to the certificate’s signing key.
In addition to regular validity and liveness constraints, the certificate must have these properties:
- It must have its
CERT_TYPE
field set toFAMILY_V_IDENTITY
. - It must include its signing key (KP_familyid_ed) in a signed-with-ed25519-key extension.
- Its certified key must be the same as the relay’s KP_relayid_ed key, as listed in the identity-ed25519 entry.
A certificate meeting these constraints proves that the relay
is a member of a family with the family ID ed25519:
FID,
where FID
is the unpadded base-64 encoding
of the certificate’s KP_relayid_ed key.
eventdns
— Declare support for non-obsolete DNS logic
“eventdns” bool NL
[At most once]
Declare whether this version of Tor is using the newer enhanced dns logic. Versions of Tor with this field set to false SHOULD NOT be used for reverse hostname lookups.
[This option is obsolete. All Tor current relays should be presumed
to have the evdns backend.]
"caches-extra-info" NL
[At most once.] [No extra arguments]
Present only if this router is a directory cache that provides extra-info documents.
[Versions before 0.2.0.1-alpha don’t recognize this]
extra-info-digest
— Hash of the extra-info document
extra-info-digest
sha1-digest [ sha256-digest ] ..- At most once
sha1-digest is the SHA1 digest, hex-encoded using upper-case characters, of the router’s extra-info document, as signed in the router’s extra-info (that is, not including the signature).
If this Item is absent, the router does not have an extra-info document.
sha256-digest is the SHA256 digest, base64-encoded, of the extra-info document. Unlike the sha1-digest, this digest is calculated over the entire document, including the signature.
The difference in the inputs to the two digests is due to a long-lived bug in the tor implementation that it would be difficult to roll out an incremental fix for, not a design choice. Future digest algorithms specified should not include the signature in the data used to compute the digest.
[Versions before 0.2.7.2-alpha did not include a SHA256 digest.] [Versions before 0.2.0.1-alpha don’t recognize this field at all.]
hidden-service-dir
— Declares this router to be a Hidden Service directory
hidden-service-dir
..- At most once
Present only if this router stores and serves hidden service descriptors. This router supports the descriptor versions declared in the HSDir “proto” entry. If there is no “proto” entry, this router supports version 2 descriptors.
allow-single-hop-exits
— Declare support for single-hop exit circuits
“allow-single-hop-exits” NL
[At most once.] [No extra arguments]
Present only if the router allows single-hop circuits to make exit connections. Most Tor relays do not support this: this is included for specialized controllers designed to support perspective access and such. This is obsolete in tor version >= 0.3.1.0-alpha.
or-address
– Alternative ORport address and port
“or-address” SP ADDRESS “:” PORT NL
[Any number]
ADDRESS = IP6ADDR | IP4ADDR IPV6ADDR = an ipv6 address, surrounded by square brackets. IPV4ADDR = an ipv4 address, represented as a dotted quad. PORT = a number between 1 and 65535 inclusive.
An alternative for the address and ORPort of the “router” line, but with two added capabilities:
* or-address can be either an IPv4 or IPv6 address
* or-address allows for multiple ORPorts and addresses
A descriptor SHOULD NOT include an or-address line that does nothing but duplicate the address:port pair from its “router” line.
The ordering of or-address lines and their PORT entries matter because Tor MAY accept a limited number of address/port pairs. As of Tor 0.2.3.x only the first address/port pair is advertised and used.
tunnelled-dir-server
— Accepts BEGIN_DIR relay message via ORport
“tunnelled-dir-server” NL
[At most once.] [No extra arguments]
Present if the router accepts "tunneled" directory requests using a
BEGIN_DIR relay message over the router's OR port.
(Added in 0.2.8.1-alpha. Before this, Tor relays accepted
tunneled directory requests only if they had a DirPort open,
or if they were bridges.)
proto
- Subprotocols supported
proto
entry entry ..- Exactly once.
- Zero or more entry arguments.
Syntax of each entry:
entry = Keyword "=" Values
Values =
Values = Value
Values = Value "," Values
Value = Int
Value = Int "-" Int
Int = NON_ZERO_DIGIT
Int = Int DIGIT
Each entry indicates that the Tor relay supports all of the subprotocols in question. (See Subprotocol-based versioning for a definition of recognized keywords and values.) Entries should be sorted by keyword. Values should be numerically ascending within each entry. (This implies that there should be no overlapping ranges.) Ranges should be represented as compactly as possible. _Int_s must be no larger than 63.
This field was first added in Tor 0.2.9.x.
[Before Tor 0.4.5.1-alpha, this field was optional.]
router-sig-ed25519
— Signature
router-sig-ed25519
Signature- Exactly once, at end, just before
router-signature
Ed25519 signature
by K_relaysign_ed (as certified in identity-ed25519
)
on the SHA256 digest of the document, as follows:
This digest is computed over:
- the fixed string
Tor router descriptor signature v1
; - the contents of the document, starting at the beginning,
- but, only up to and including the first space
after the
router-sig-ed25519
keyword.
Note that this differs in several respects from the definition of a signature item.
The signature is encoded in Base64, with terminating =s removed.
[Before Tor 0.4.5.1-alpha, this field was optional whenever identity-ed25519 was absent.]
router-signature
— RSA signature
router-signature
- SIGNATURE Object,
SIGNATURE
- At end, exactly once
- No extra arguments
- RSA signature of the document by KP_relayid_rsa
The digest includes the router-sig-ed25519
item.