Vote and consensus status document formats

Votes and consensuses are more strictly formatted than other documents in this specification, since different authorities must be able to generate exactly the same consensus given the same set of votes.

The procedure for deciding when to generate vote and consensus status documents are described in section 1.4 on the voting timeline.

Status documents contain a preamble, an authority section, a list of router status entries, and one or more footer signature, in that order.

Some items appear only in votes, and some items appear only in consensuses. Unless specified, items occur in both. Items appearing only in certain documents is indicated by one of the following in the Item's syntax bullet points:

  • In votes only
  • In consensus only

Consensus documents may also be available in "flavored" forms computed (deterministically) from the information desccribed here.

Consensus documents --- reproducibility

Consensus documents generated by each dirauth must be byte-for-byte identical, as the same document must be countersigned by multiple dirauths.

Therefore, when generating a consensus document, certain of the metaformat rules are tightened:

  • Each WS is precisely a single SP.
  • Extra arguments are not allowed.
  • Items are ordered as specified here.

These rules MUST be followed by a dirauth when generating a consensus. When reading a vote or consensus, an implementation MUST NOT insist on them.

When reading, the usual relaxed parsing is needed to support future compatibility. When writing, consensus-methods in votes allows the participating dirauths to negotiate protocol upgrades.

Vote and consensus document preamble items

The preamble contains the following items.

network-status-version --- Document format version

  • network-status-version version ..
  • At start, exactly once.

The document format version. For this specification, the version is "3".

vote-status --- Declare document type

  • vote-status type ..
  • Exactly once.
  • type is vote or status

consensus-methods -- Supported consensus methods

  • consensus-methods method method ..
  • At most once
  • In votes only
  • At least one method argument.

The consensus methods supported by this voter. Each method is a as a decimal integer. See Computing a consensus for details. Absence of the line means that only method "1" is supported.

consensus-method --- Consensus method used

  • consensus-method method
  • At most once
  • In consensus only

See Computing a consensus for details.

(Only included when the vote is generated with consensus-method 2 or later.)

(Vote and consensus document items in ad-hoc representation, continued)

"published" SP YYYY-MM-DD SP HH:MM:SS NL

[Exactly once for votes; does not occur in consensuses.]

The publication time for this status document (if a vote).

"valid-after" SP YYYY-MM-DD SP HH:MM:SS NL

[Exactly once.]

The start of the Interval for this vote. Before this time, the consensus document produced from this vote is not officially in use.

(Note that because of propagation delays, clients and relays may see consensus documents that are up to DistSeconds earlier than this time, and should not warn about them.)

See section 1.4 for voting timeline information.

"fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL

[Exactly once.]

The time at which the next consensus should be produced; before this time, there is no point in downloading another consensus, since there won't be a new one. See section 1.4 for voting timeline information.

"valid-until" SP YYYY-MM-DD SP HH:MM:SS NL

[Exactly once.]

The end of the Interval for this vote. After this time, all clients should try to find a more recent consensus. See section 1.4 for voting timeline information.

In practice, clients continue to use the consensus for up to 24 hours after it is no longer valid, if no more recent consensus can be downloaded.

"voting-delay" SP VoteSeconds SP DistSeconds NL

[Exactly once.]

VoteSeconds is the number of seconds that we will allow to collect votes from all authorities; DistSeconds is the number of seconds we'll allow to collect signatures from all authorities. See section 1.4 for voting timeline information.

client-versions --- Recommended Tor client software

  • client-versions version,version,.. ..
  • At most once

A comma-separated list of recommended Tor **version**s for client usage, in ascending order. The versions are given as defined by version-spec.txt. If absent, no opinion is held about client versions.

server-versions --- Recommended Tor server software

  • server-versions version,version,.. ..
  • At most once.

A comma-separated list of recommended Tor versions for relay usage, in ascending order. The versions are given as defined by version-spec.txt. If absent, no opinion is held about server versions.

package --- Software distribution hashes (obsolete)

"package" SP PackageName SP Version SP URL SP DIGESTS NL

[Any number of times.]

For this element:

        PACKAGENAME = NONSPACE
        VERSION = NONSPACE
        URL = NONSPACE
        DIGESTS = DIGEST | DIGESTS SP DIGEST
        DIGEST = DIGESTTYPE "=" DIGESTVAL
        NONSPACE = one or more non-space printing characters
        DIGESTVAL = DIGESTTYPE = one or more non-space printing characters
              other than "=".

Indicates that a package called "package" of version VERSION may be found at URL, and its digest as computed with DIGESTTYPE is equal to DIGESTVAL. In consensuses, these lines are sorted lexically by "PACKAGENAME VERSION" pairs, and DIGESTTYPES must appear in ascending order. A consensus must not contain the same "PACKAGENAME VERSION" more than once. If a vote contains the same "PACKAGENAME VERSION" more than once, all but the last is ignored.

Included in consensuses only for methods 19-33. Earlier methods did not include this; method 34 removed it.

known-flags --- Router flags which could be determined

  • known-flags flag flag ..
  • Exactly once.
  • One or more distinct _flag_ arguments, in lexical order

A space-separated list of all of the flags that this document might contain in s Items.

A flag is "known" either because the authority knows about them and might set them (if in a vote), or because enough votes were counted for the consensus for an authoritative opinion to have been formed about their status.

flag-thresholds --- Authority's performance thresholds

  • flag-thresholds threshold threshold ..
  • One or more threshold arguments
  • At most once for votes; does not occur in consensuses.
         The metaformat is:
            threshold = ThresholdKey '=' ThresholdVal
            ThresholdKey = (KeywordChar | "_") +
            ThresholdVal = [0-9]+("."[0-9]+)? "%"?

A space-separated list of the internal performance thresholds that the directory authority had at the moment it was forming a vote.

Commonly used ThresholdKeys at this point include:

  • stable-uptime -- Uptime (in seconds) required for a relay to be marked as stable.

  • stable-mtbf -- MTBF (in seconds) required for a relay to be marked as stable.

  • enough-mtbf -- Whether we have measured enough MTBF to look at stable-mtbf instead of stable-uptime.

  • fast-speed -- Bandwidth (in bytes per second) required for a relay to be marked as fast.

  • guard-wfu -- WFU (in seconds) required for a relay to be marked as guard.

  • guard-tk -- Weighted Time Known (in seconds) required for a relay to be marked as guard.

  • guard-bw-inc-exits -- If exits can be guards, then all guards must have a bandwidth this high.

  • guard-bw-exc-exits -- If exits can't be guards, then all guards must have a bandwidth this high.

  • ignoring-advertised-bws -- 1 if we have enough measured bandwidths that we'll ignore the advertised bandwidth claims of routers without measured bandwidth.

required- / recommended-*-protocols --- Minimum protocol features

  • recommended-client-protocols entry entry ..
  • recommended-relay-protocols entry entry ..
  • required-client-protocols entry entry ..
  • required-relay-protocols entry entry ..
  • At most once each.
  • Zero or more entry arguments.

entry is as for proto in a server descriptor.

To vote on these entries, a protocol/version combination is included only if it is listed by a majority of the voters.

These lines should be voted on. A majority of votes is sufficient to make a protocol un-supported. A supermajority of authorities (2/3) are needed to make a protocol required. The required protocols should not be locally configurable, but rather should be hardwired in the dirauth implementation.

See Subprotocol versioning for details of how a relay and a client should behave when they encounter these lines in the consensus.

Implications of required-*-protocols

A consensus containing erroneous required-*-protocols has the potential to take down the network: clients and relays that see requirements, that they do not meet, will shut down, and not retry.

Note that this applies to versions, not just protocols! If the consensus requires Foobar=8-9, and the client only has Foobar=9, it will shut down.

For further information, see notes in the C Tor source code.

params --- Network parameters

  • params [Keyword=Value Keyword=Value ..]
  • Distinct _Keyword_s, in lexical order
  • At most once

Each Keyword is a parameter keyword. Each Value is a signed 32-bit integer, in decimal.

When reading a document, unknown parameters MUST be tolerated.

When a dirauth computes a consensus from votes, every parameter, even one unknown to that dirauth, MUST be included in the consensus if it appears in enough votes.

shared-rand-*-value --- Shared random values

  • shared-rand-previous-value NumReveals Value ..
  • shared-rand-current-value NumReveals Value ..
  • At most once each

Value is the shared random value (256 bits) encoded in base64, as calculated by the shared random protocol.

NumReveals is the number of commits used to generate Value.

shared-rand-current-value is the value that was generated during the latest shared randomness protocol run. shared-rand-previous-value is the value generated during the second-to-last run.

For example, if this document was created on the 5th of November, current carries the value generated during the protocol run of the 4th of November, and previous carries the value generated during the protocol run of the 3rd of November.

See CONS for why we include old values in votes and consensus.

bandwidth-file-headers --- Bandwidth file metadata

"bandwidth-file-headers" SP KeyValues NL

[At most once for votes; does not occur in consensuses.]

KeyValues ::= "" | KeyValue | KeyValues SP KeyValue KeyValue ::= Keyword '=' Value Value ::= ArgumentCharValue+ ArgumentCharValue ::= any printing ASCII character except NL and SP.

The headers from the bandwidth file used to generate this vote.

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, but without any headers.

First-appeared: Tor 0.3.5.1-alpha.

bandwidth-file-digest --- Bandwidth file

  • bandwidth-file-digest algorithm=digest ..
  • One or more algorithm=digest arguments
  • At most once
  • In votes only

Each digest is the hash using algorithm of the bandwidth file used to generate this vote, in base64, unpadded.

algorithm is sha256 or another algorithm.

If an authority is not configured with a bandwidth file, this line SHOULD NOT appear in its vote.

If an authority is configured with a bandwidth file, but parsing fails, this line SHOULD appear in its vote, with the digest(s) of the unparseable file.

First-appeared: Tor 0.4.0.4-alpha

In C Tor this file is configured with V3BandwidthsFile in torrc

Vote and consensus document, authority section items

The authority section of a vote contains the following items, followed in turn by the authority's current key certificate:

    "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
       orport NL

        [Exactly once, at start]

Describes this authority. The nickname is a convenient identifier for the authority. The identity is an uppercase hex fingerprint of the authority's current (v3 authority) identity key. The address is the server's hostname. The IP is the server's current IP address, and dirport is its current directory port. The orport is the port at that address where the authority listens for OR connections.

"contact" SP string NL

[Exactly once]

An arbitrary string describing how to contact the directory server's administrator. Administrators should include at least an email address and a PGP fingerprint.

"legacy-dir-key" SP FINGERPRINT NL

[At most once]

Lists a fingerprint for an obsolete identity key still used by this authority to keep older clients working. This option is used to keep key around for a little while in case the authorities need to migrate many identity keys at once. (Generally, this would only happen because of a security vulnerability that affected multiple authorities, like the Debian OpenSSL RNG bug of May 2008.)

"shared-rand-participate" NL

[At most once]

Denotes that the directory authority supports and can participate in the shared random protocol.

shared-rand-commit --- Shared random commitment

  • shared-rand-commit Version AlgName Identity Commit [ Reveal ]
  • Any number of times
Version ::= An integer greater or equal to 0.
AlgName ::= 1\*(ALPHA / DIGIT / "\_" / "-")
Identity ::= 40\* HEXDIG

Denotes a directory authority commit for the shared randomness protocol, containing the commitment value and potentially also the reveal value. See sections [COMMITREVEAL] and [VALIDATEVALUES] of srv-spec.txt on how to generate and validate these values.

Version is the current shared randomness protocol version. AlgName is the hash algorithm that is used (e.g. "sha3-256") and Identity is the authority's SHA1 v3 identity fingerprint. Commit is the encoded commitment value in base64. Reveal (optional) contains the reveal value in base64.

If a vote contains multiple commits from the same authority, the receiver MUST only consider the first commit listed.

(Vote and consensus document items in ad-hoc representation, continued)

"shared-rand-previous-value" SP NumReveals SP Value NL

[At most once]

See shared-rand-previous-value description above.

"shared-rand-current-value" SP NumReveals SP Value NL

[At most once]

See shared-rand-current-value description above.

The authority section of a consensus contains groups of the following items, in the order given, with one group for each authority that contributed to the consensus, with groups sorted by authority identity digest:

    "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
       orport NL

        [Exactly once, at start]

        As in the authority section of a vote.

    "contact" SP string NL

        [Exactly once.]

        As in the authority section of a vote.

    "vote-digest" SP digest NL

        [Exactly once.]

A digest of the vote from the authority that contributed to this consensus, as signed (that is, not including the signature). (Hex, upper-case.)

For each "legacy-dir-key" in the vote, there is an additional "dir-source" line containing that legacy key's fingerprint, the authority's nickname with "-legacy" appended, and all other fields as in the main "dir-source" line for that authority. These "dir-source" lines do not have corresponding "contact" or "vote-digest" entries.

Vote and consensus document router status items

Each router status entry contains the following items. Router status entries are sorted in ascending order by identity digest.

r --- Introduce a router status entry

  • r nickname identity digest publication IP ORPort DirPort ..
  • At start of router status entry, exactly once

Nickname is the OR's nickname. Identity is its SHA1(DER(KP_relayid_rsa)) in unpadded base64. Digest is a hash of its most recent descriptor as signed (that is, not including the signature) by the RSA identity key (see section 1.3.), encoded in base64.

Publication was once the publication time of the router's most recent descriptor, in the form YYYY-MM-DD HH:MM:SS, in UTC. Now it is only used in votes, and may be set to a fixed value in consensus documents. Implementations SHOULD ignore this value in non-vote documents.

IP is its current IPv4 address. ORPort is its current OR port. DirPort is its directory port or 0 for "none".

a --- Further router address(es) (IPv6)

  • a address:port
  • Any number

address and port are as for or-address.

Additional reachable address(es) for the OR. Used to convey the OR's IPv6 address.

Clients should ignore any IPv4 addresses in as, and use only the first IPv6 address, if there is one.

Authorities should include only the first advertised IPv6 address, if it is reachable.

We may extend the protocol in the future to support multiple addresses for each address family.

(Only included when the vote or consensus is generated with consensus-method 14 or later.)

s --- Router status flags

  • s [flag flag ..]
  • Exactly once.
  • Zero or more distinct _flag_ arguments, in lexical order

Each flag argument states a property of the router. If a particular flag is present in known-flags, but absent from the router entry, the document states that the router does not have the property in question. If a flag is absent from known-flags, information about the property is not available in this document. (Every flag in an s item MUST be in known-flags.)

Currently specified flags are:

  • Authority --- is a directory authority.
  • BadExit --- is believed to be useless as an exit node (because its ISP censors it, because it is behind a restrictive proxy, or for some similar reason).
  • Exit --- supports commonly used exit ports, and should be treated specially in the path building algorithm.
  • Fast --- is suitable for high-bandwidth circuits.
  • Guard --- is suitable for use as an entry guard.
  • HSDir --- is considered a v2 hidden service directory.
  • MiddleOnly --- is considered unsuitable for usage other than as a middle relay. Clients do not need to handle this option, since when it is present, the authorities will automatically vote against flags that would make the router usable in other positions. (Since 0.4.7.2-alpha.)
  • NoEdConsensus --- any Ed25519 key in the router's descriptor or microdescriptor does not reflect authority consensus.
  • Stable --- is suitable for long-lived circuits.
  • StaleDesc --- should upload a new descriptor because the old one is too old.
  • Running --- is currently usable over all its published ORPorts. (Authorities ignore IPv6 ORPorts unless configured to check IPv6 reachability.) Relays without this flag are omitted from the consensus, and current clients (since 0.2.9.4-alpha) assume that every listed relay has this flag.
  • Valid --- has been 'validated'. Clients before 0.2.9.4-alpha would not use routers without this flag by default. Currently, relays without this flag are omitted from the consensus, and current (post-0.2.9.4-alpha) clients assume that every listed relay has this flag.
  • V2Dir --- implements the v2 directory protocol or higher.

Unknown flags must be ignored (in s and in known-flags) when reading a document. Except, they must be processed by an authority, when generating a consensus from votes.

(Vote and consensus document items in ad-hoc representation, continued)

"v" SP version NL

[At most once.]

The version of the Tor protocol that this relay is running. If the value begins with "Tor" SP, the rest of the string is a Tor version number, and the protocol is "The Tor protocol as supported by the given version of Tor." Otherwise, if the value begins with some other string, Tor has upgraded to a more sophisticated protocol versioning system, and the protocol is "a version of the Tor protocol more recent than any we recognize."

Directory authorities SHOULD omit version strings they receive from descriptors if they would cause "v" lines to be over 128 characters long.

"pr" SP Entries NL

[At most once.]

The "proto" family element as specified in section 2.1.1.

During voting, authorities copy these lines immediately below the "v" lines. When a descriptor does not contain a "proto" entry, the authorities should reconstruct it using the approach described below in section D. They are included in the consensus using the same rules as currently used for "v" lines, if a sufficiently late consensus method is in use.

"w" SP "Bandwidth=" INT [SP "Measured=" INT] [SP "Unmeasured=1"] NL

[At most once.]

An estimate of the bandwidth of this relay, in an arbitrary unit (currently kilobytes per second). Used to weight router selection. See section 3.4.2 for details on how the value of Bandwidth is determined in a consensus.

Additionally, the Measured= keyword is present in votes by participating bandwidth measurement authorities to indicate a measured bandwidth currently produced by measuring stream capacities. It does not occur in consensuses.

'Bandwidth=' and 'Measured=' values must be between 0 and 2^32 - 1 inclusive.

The "Unmeasured=1" value is included in consensuses generated with method 17 or later when the 'Bandwidth=' value is not based on a threshold of 3 or more measurements for this relay.

Other weighting keywords may be added later. Clients MUST ignore keywords they do not recognize.

"p" SP ("accept" / "reject") SP PortList NL

[At most once.]

PortList = PortOrRange PortList = PortList "," PortOrRange PortOrRange = INT "-" INT / INT

A list of those ports that this router supports (if 'accept') or does not support (if 'reject') for exit to "most addresses".

"m" SP methods 1*(SP algorithm "=" digest) NL

[Any number, only in votes.]

Microdescriptor hashes for all consensus methods that an authority supports and that use the same microdescriptor format. "methods" is a comma-separated list of the consensus methods that the authority believes will produce "digest". "algorithm" is the name of the hash algorithm producing "digest", which can be "sha256" or something else, depending on the consensus "methods" supporting this algorithm. "digest" is the base64 encoding of the hash of the router's microdescriptor with trailing =s omitted.

     "id" SP "ed25519" SP ed25519-identity NL
     "id" SP "ed25519" SP "none" NL
        [vote only, at most once]

     "stats" SP [KeyValues] NL

        [At most once. Vote only]

KeyValue ::= Keyword '=' Number Number ::= [0-9]+("."[0-9]+)? KeyValues ::= KeyValue | KeyValues SP KeyValue

Line containing various statistics that an authority has computed for this relay. Each stats is represented as a key + value. Reported keys are:

          "wfu"  - Weighted Fractional Uptime
          "tk"   - Weighted Time Known
          "mtbf" - Mean Time Between Failure (stability)

          (As of tor-0.4.6.1-alpha)

The footer section is delineated in all votes and consensuses supporting consensus method 9 and above with the following:

"directory-footer" NL [No extra arguments]

It contains two subsections, a bandwidths-weights line and a directory-signature. (Prior to consensus method 9, footers only contained directory-signatures without a 'directory-footer' line or bandwidth-weights.)

The bandwidths-weights line appears At Most Once for a consensus. It does not appear in votes.

"bandwidth-weights" [SP Weights] NL

Weight ::= Keyword '=' Int32 Int32 ::= A decimal integer between -2147483648 and 2147483647. Weights ::= Weight | Weights SP Weight

List of optional weights to apply to router bandwidths during path selection. They are sorted in lexical order and values are divided by the consensus' "bwweightscale" param. Definition of our known entries are...

         Wgg - Weight for Guard-flagged nodes in the guard position
         Wgm - Weight for non-flagged nodes in the guard Position
         Wgd - Weight for Guard+Exit-flagged nodes in the guard Position

         Wmg - Weight for Guard-flagged nodes in the middle Position
         Wmm - Weight for non-flagged nodes in the middle Position
         Wme - Weight for Exit-flagged nodes in the middle Position
         Wmd - Weight for Guard+Exit flagged nodes in the middle Position

         Weg - Weight for Guard flagged nodes in the exit Position
         Wem - Weight for non-flagged nodes in the exit Position
         Wee - Weight for Exit-flagged nodes in the exit Position
         Wed - Weight for Guard+Exit-flagged nodes in the exit Position

         Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
         Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
         Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
         Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes

         Wbg - Weight for Guard flagged nodes for BEGIN_DIR requests
         Wbm - Weight for non-flagged nodes for BEGIN_DIR requests
         Wbe - Weight for Exit-flagged nodes for BEGIN_DIR requests
         Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests

       These values are calculated as specified in section 3.8.3.

The signature contains the following item, which appears Exactly Once for a vote, and At Least Once for a consensus.

    "directory-signature" [SP Algorithm] SP identity SP signing-key-digest
        NL Signature

This is a signature of the status document, with the initial item "network-status-version", and the signature item "directory-signature", using the signing key. (In this case, we take the hash through the space after directory-signature, not the newline: this ensures that all authorities sign the same thing.) "identity" is the hex-encoded digest of the authority identity key of the signing authority, and "signing-key-digest" is the hex-encoded digest of the current authority signing key of the signing authority.

The Algorithm is one of "sha1" or "sha256" if it is present; implementations MUST ignore directory-signature entries with an unrecognized Algorithm. "sha1" is the default, if no Algorithm is given. The algorithm describes how to compute the hash of the document before signing it.

"ns"-flavored consensus documents must contain only sha1 signatures. Votes and microdescriptor documents may contain other signature types. Note that only one signature from each authority should be "counted" as meaning that the authority has signed the consensus.

(Tor clients before 0.2.3.x did not understand the 'algorithm' field.)