diff options
Diffstat (limited to 'dir-spec.txt')
| -rw-r--r-- | dir-spec.txt | 98 |
1 files changed, 71 insertions, 27 deletions
diff --git a/dir-spec.txt b/dir-spec.txt index df824e6..91d6052 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -358,6 +358,11 @@ - Its uptime has been reset (by restarting). + - It receives a networkstatus consensus in which it is not listed. + + - It receives a networkstatus consensus in which it is listed + with the StaleDesc flag. + [XXX this list is incomplete; see router_differences_are_cosmetic() in routerlist.c for others] @@ -701,17 +706,23 @@ [Versions before 0.2.0.1-alpha don't recognize this] - "extra-info-digest" SP sha1digest [SP sha256-digest] NL + "extra-info-digest" SP sha1-digest [SP sha256-digest] NL [At most once] - "sha1-digest" is a hex-encoded 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.) + "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, computed over the same data. + 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.] @@ -1495,6 +1506,32 @@ The "family" element as specified in section 2.1.1. + When generating microdescriptors for consensus method 29 or later, + the following canonicalization algorithm is applied to improve + compression: + + For all entries of the form $hexid=name or $hexid~name, + remove the =name or ~name portion. + + Remove all entries of the form $hexid, where hexid is not + 40 hexadecimal characters long. + + If an entry is a valid nickname, put it into lower case. + + If an entry is a valid $hexid, put it into upper case. + + If there are any entries, add a single $hexid entry for + the relay in question, so that it is a member of its own + family. + + Sort all entries in lexical order. + + Remove duplicate entries. + + (Note that if an entry is not of the form "nickname", "$hexid", + "$hexid=nickname" or "$hexid~nickname", then it will be unchanged: + this is what makes the algorithm forward-compatible.) + "p" SP ("accept" / "reject") SP PortList NL [Exactly once.] @@ -1512,8 +1549,8 @@ [At most once] - The IPv6 exit policy summary as specified in sections 3.4.1 and 3.8.2. A - missing "p6" line is equivalent to "p6 reject 1-65535". + The IPv6 exit policy summary as specified in sections 3.4.1 and + 3.8.2. A missing "p6" line is equivalent to "p6 reject 1-65535". (Only included when generating microdescriptors for consensus-method 15 or later.) @@ -2105,26 +2142,26 @@ If an authority is configured with a V3BandwidthsFile, but parsing fails, this line SHOULD appear in its vote, but without any headers. - Current Keywords: - "timestamp" -- the Unix Epoch time in seconds of the most recent - generator result. - "version" -- the Bandwidth List format document specification version. - "software" -- the name of the software that created the document. - "software_version" -- the version of the software that created the - document. - "file_created" -- the date and time timestamp in ISO 8601 format - and UTC time zone when the file was created. - "generator_started" -- the date and time timestamp in ISO 8601 format - and UTC time zone when the generator started. - "earliest_bandwidth" -- the date and time timestamp in ISO 8601 format - and UTC time zone when the first relay bandwidth was obtained. - "latest_bandwidth" -- the date and time timestamp in ISO 8601 format - and UTC time zone of the most recent generator result. - This time MUST be identical to the initial Timestamp line. - This duplicate value is included to make the format easier for people - to read. First-appeared: Tor 0.3.5.1-alpha. + "bandwidth-file-digest" 1*(SP algorithm "=" digest) NL + + [At most once for votes; does not occur in consensuses.] + + A digest of the bandwidth file used to generate this vote. + "algorithm" is the name of the hash algorithm producing "digest", + which can be "sha256" or another algorithm. "digest" is the + base64 encoding of the hash of the bandwidth file, with trailing =s + omitted. + + If an authority is not configured with a V3BandwidthsFile, this line + SHOULD NOT appear in its vote. + + If an authority is configured with a V3BandwidthsFile, but parsing + fails, this line SHOULD appear in its vote, with the digest(s) of the + unparseable file. + First-appeared: Tor 0.4.0.1-alpha + The authority section of a vote contains the following items, followed in turn by the authority's current key certificate: @@ -2293,6 +2330,8 @@ "NoEdConsensus" if any Ed25519 key in the router's descriptor or microdesriptor does not reflect authority consensus. "Stable" if the router is suitable for long-lived circuits. + "StaleDesc" if the router should upload a new descriptor because + the old one is too old. "Running" if the router is currently usable over all its published ORPorts. (Authorities ignore IPv6 ORPorts unless configured to check IPv6 reachability.) Relays without this flag are omitted @@ -2392,7 +2431,7 @@ [No extra arguments] It contains two subsections, a bandwidths-weights line and a - directory-signature. (Prior to conensus method 9, footers only contained + directory-signature. (Prior to consensus method 9, footers only contained directory-signatures without a 'directory-footer' line or bandwidth-weights.) @@ -2576,6 +2615,10 @@ "NoEdConsensus" -- authorities should not vote on this flag; it is produced as part of the consensus for consensus method 22 or later. + "StaleDesc" -- authorities should vote to assign this flag if the + published time on the descriptor is over 18 hours in the past. (This flag + was added in 0.4.0.1-alpha.) + Directory server administrators may label some relays or IPs as blacklisted, and elect not to include them in their network-status lists. @@ -2961,6 +3004,7 @@ "26" -- Initialize bandwidth weights to 1 to avoid division-by-zero. "27" -- Adds support for "a" lines in microdescriptor consensues. "28" -- Removes "a" lines from microdescriptors. + "29" -- Canonicalizes families in microdescriptors. Before generating a consensus, an authority must decide which consensus method to use. To do this, it looks for the highest version number |