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

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 exitpattern
  • reject“ 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

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 to FAMILY_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

The digest includes the router-sig-ed25519 item.