diff options
Diffstat (limited to 'spec/dir-spec/server-descriptor-format.md')
| -rw-r--r-- | spec/dir-spec/server-descriptor-format.md | 509 |
1 files changed, 509 insertions, 0 deletions
diff --git a/spec/dir-spec/server-descriptor-format.md b/spec/dir-spec/server-descriptor-format.md new file mode 100644 index 0000000..ddd7fb2 --- /dev/null +++ b/spec/dir-spec/server-descriptor-format.md @@ -0,0 +1,509 @@ +<a id="dir-spec.txt-2.1.1"></a> + +# 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. + +"router" nickname address ORPort SOCKSPort DirPort NL + +\[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.) + +```text + "identity-ed25519" NL "-----BEGIN ED25519 CERT-----" NL certificate + "-----END ED25519 CERT-----" NL +``` + +\[Exactly once, in second position in document.\] +\[No extra arguments\] + +The certificate is a base64-encoded Ed25519 certificate (see +cert-spec.txt) with terminating =s removed. When this element +is present, it MUST appear as the first or second element in +the router descriptor. + +The certificate has CERT_TYPE of \[04\]. It must include a +signed-with-ed25519-key extension (see cert-spec.txt, +section 2.2.1), so that we can extract the master identity key. + +\[Before Tor 0.4.5.1-alpha, this field was optional.\] + +"master-key-ed25519" SP MasterKey NL + +\[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 the identity-ed25519 entry. + +\[Before Tor 0.4.5.1-alpha, this field was optional.\] + +"bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL + +\[Exactly once\] + +Estimated bandwidth for this router, in bytes per second. The +"average" bandwidth is the volume per second that the OR is willing to +sustain over long periods; the "burst" bandwidth is the volume that +the OR is willing to sustain in very short intervals. The "observed" +value 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. The +"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" string NL + +\[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" YYYY-MM-DD HH:MM:SS NL + +\[Exactly once\] + +The time, in UTC, when this descriptor (and its corresponding +extra-info document if any) was generated. + +"fingerprint" fingerprint NL + +\[At most once\] + +A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in +hex, with a single space after every 4 characters) for this router's +identity key. A descriptor is considered invalid (and MUST be +rejected) if the fingerprint line does not match the public key. + +```text + [We didn't start parsing this line until Tor 0.1.0.6-rc; it should + be marked with "opt" until earlier versions of Tor are obsolete.] + + "hibernating" bool NL + + [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. + +```text + [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be + marked with "opt" until earlier versions of Tor are obsolete.] + + "uptime" number NL + + [At most once] + + The number of seconds that this OR process has been running. + + "onion-key" NL a public key in PEM format +``` + +\[Exactly once\] +\[No extra arguments\] + +This key is used to encrypt CREATE cells for this OR. The key MUST be +accepted for at least 1 week after any new key is published in a +subsequent descriptor. It MUST be 1024 bits. + +The key encoding is the encoding of the key as a PKCS#1 RSAPublicKey +structure, encoded in base64, and wrapped in "-----BEGIN RSA PUBLIC +KEY-----" and "-----END RSA PUBLIC KEY-----". + +"onion-key-crosscert" NL a RSA signature in PEM format. + +\[Exactly once\] +\[No extra arguments\] + +This element contains an RSA signature, generated using the +onion-key, of the following: + +```text + A SHA1 hash of the RSA identity key, + i.e. RSA key from "signing-key" (see below) [20 bytes] + The Ed25519 identity key, + i.e. Ed25519 key 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" base-64-encoded-key + +\[Exactly once\] + +A curve25519 public key used for the ntor circuit extended +handshake. It's the standard encoding of the OR's curve25519 +public key, encoded in base 64. The trailing '=' sign MAY be +omitted from the base64 encoding. 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.\] + +<a id="ntor-onion-key-crosscert"></a> +```text + "ntor-onion-key-crosscert" SP Bit NL + "-----BEGIN ED25519 CERT-----" NL certificate + "-----END ED25519 CERT-----" NL +``` + +\[Exactly once\] +\[No extra arguments\] + +A signature created with the ntor-onion-key, using the +certificate format documented in cert-spec.txt, 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" NL a public key in PEM format + +\[Exactly once\] +\[No extra arguments\] + +The OR's long-term RSA identity key. It MUST be 1024 bits. + +The encoding is as for "onion-key" above. + +"accept" exitpattern NL +"reject" exitpattern NL + +\[Any number\] + +These lines describe an "exit policy": the rules that an OR follows +when deciding whether to allow a new stream to a given address. The +'exitpattern' syntax is described below. 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 *:*. + +"ipv6-policy" SP ("accept" / "reject") SP PortList NL + +\[At most once.\] + +An exit-policy summary as specified in sections 3.4.1 and 3.8.2, +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" SP version SP YYYY-MM-DD HH:MM:SS NL + +\[At most once.\] + +Indicates that a relay has reached an "overloaded state" which can be +one or many of the following load metrics: + +```text + - Any OOM invocation due to memory pressure + - Any ntor onionskins are dropped + - TCP port exhaustion +``` + +The timestamp is when at least one metrics was detected. It should always +be at the hour and thus, as an 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 provided timestamp and the "published" timestamp of the +document which is when the document was generated. + +The overload-general line should remain in place for 72 hours since 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. + +```text + (Introduced in tor-0.4.6.1-alpha, but moved from extra-info to general + descriptor in tor-0.4.6.2-alpha) + + "router-sig-ed25519" SP Signature NL + + [Exactly once.] +``` + +It MUST be the next-to-last element in the descriptor, appearing +immediately before the RSA signature. It MUST contain an Ed25519 +signature of a SHA256 digest of the entire document. This digest is +taken from the first character up to and including the first space +after the "router-sig-ed25519" string. Before computing the digest, +the string "Tor router descriptor signature v1" is prefixed to the +document. + +The signature is encoded in Base64, with terminating =s removed. + +The signing key in the identity-ed25519 certificate MUST +be the one used to sign the document. + +\[Before Tor 0.4.5.1-alpha, this field was optional whenever +identity-ed25519 was absent.\] + +"router-signature" NL Signature NL + +\[At end, exactly once\] +\[No extra arguments\] + +The "SIGNATURE" object contains a signature of the PKCS1-padded +hash of the entire server descriptor, taken from the beginning of the +"router" line, through the newline after the "router-signature" line. +The server descriptor is invalid unless the signature is performed +with the router's identity key. + +"contact" info NL + +\[At most once\] + +Describes a way to contact the relay's administrator, preferably +including an email address and a PGP key fingerprint. + +"bridge-distribution-request" SP Method NL + +\[At most once, bridges only.\] + +The "Method" describes how a Bridge address is distributed by +BridgeDB. Recognized methods are: "none", "any", "https", "email", +"moat". If set to "none", BridgeDB will avoid distributing your bridge +address. If set to "any", BridgeDB will choose how to distribute your +bridge address. Choosing any of the other methods will tell BridgeDB to +distribute your bridge via a specific method: + +```text + - "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; and + + Potential future "Method" specifiers must be as follows: + Method = (KeywordChar | "_") + +``` + +All bridges SHOULD include this line. Non-bridges MUST NOT include +it. + +BridgeDB 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.\] + +"family" names NL + +\[At most once\] + +'Names' is a space-separated list of relay nicknames or +hexdigests. 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. + +```text + "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL + [At most once] + "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL + [At most once] +``` + +(These fields once appeared in router descriptors, but have +appeared in extra-info descriptors since 0.2.0.x.) + +"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. + +```text + [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" SP sha1-digest \[SP sha256-digest\] NL + +\[At most once\] + +"sha1-digest" is a hex-encoded SHA1 digest (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 field is +absent, the router is not uploading a corresponding extra-info +document.) + +"sha256-digest" is a base64-encoded SHA256 digest of the extra-info +document. Unlike the "sha1-digest", this digest is calculated over the +entire document, including the signature. This difference 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" NL + +\[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. + +```text + "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP + CIRCUIT-VERSION-LIST NL + + [At most once.] +``` + +An obsolete list of protocol versions, superseded by the "proto" +entry. This list was never parsed, and has not been emitted +since Tor 0.2.9.4-alpha. New code should neither generate nor +parse this line. + +"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" 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: + +```text + * 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" NL + +\[At most once.\] +\[No extra arguments\] + +```text + 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" SP Entries NL + + [Exactly once.] +``` + +Entries = +Entries = Entry +Entries = Entry SP Entries + +Entry = Keyword "=" Values + +Values = +Values = Value +Values = Value "," Values + +Value = Int +Value = Int "-" Int + +Int = NON_ZERO_DIGIT +Int = Int DIGIT + +Each 'Entry' in the "proto" line indicates that the Tor relay supports +one or more versions of the protocol in question. 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. Ints 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.\] |