January 2014 - tor-commits - lists.torproject.org

[torspec/master] Rename section 3 and remove obsolete overview part.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 6956d6cb2b86385740abe9cf5f4b2b5257c9365a Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Mon Jan 13 18:46:30 2014 +0100 Rename section 3 and remove obsolete overview part. Section 3 will describe operations and data formats that are related to the authority role, and section 4 will specify which operations are performed by caches. Reflect this in the new section title of section 3, and remove the (already obsolete) overview part listing which documents are generated by authorities. --- dir-spec.txt | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 184bc2e..a66a684 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1010,7 +1010,7 @@ bool ::= "0" | "1" -3. Formats produced by directory authorities. +3. Directory authority operation and formats Every authority has two keys used in this protocol: a signing key, and an authority identity key. (Authorities also have a router identity @@ -1019,14 +1019,6 @@ sign new key certificates using new signing keys; it is very sensitive. The signing key is used to sign key certificates and status documents. - There are three kinds of documents generated by directory authorities: - - Key certificates - Status votes - Status consensuses - - Each is discussed below. - 3.1. Key certificates Key certificates consist of the following items:

1 0

[torspec/master] Rephrase subsection title to be more precise.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit ae40466472add2c92b29e8aac02f43cc97984bd2 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Mon Jan 13 20:00:10 2014 +0100 Rephrase subsection title to be more precise. --- dir-spec.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dir-spec.txt b/dir-spec.txt index 46d92fa..5452ea4 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1096,7 +1096,7 @@ Authorities MUST generate a new signing key and corresponding certificate before the key expires. -3.2. Accepting uploads (authorities only) +3.2. Accepting router descriptor and extra-info document uploads When a router posts a signed descriptor to a directory authority, the authority first checks whether it is well-formed and correctly

1 0

[torspec/master] Tweak section 3.3 "Microdescriptors".
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 75dccc532e083abf364906c99c78e0988a1e22c1 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Mon Jan 13 20:01:48 2014 +0100 Tweak section 3.3 "Microdescriptors". Phrase subsection title as operation. Also, remove subsubsection implying that there would be other subsubsections in the future, which is not the case. --- dir-spec.txt | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 5452ea4..fa13bee 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1131,7 +1131,7 @@ descriptor that it believes is currently useful. If so, it accepts it and stores it and serves it as requested. If not, it drops it. -3.3. Microdescriptors +3.3. Computing microdescriptors Microdescriptors are a stripped-down version of router descriptors generated by the directory authorities which may additionally contain @@ -1149,8 +1149,6 @@ contain any version information, because their version is determined by the consensus method. -3.3.1. Microdescriptors in consensus method 8 or later - Starting with consensus method 8, microdescriptors contain the following elements taken from or based on the router descriptor. Order matters here, because different directory authorities must be able to

1 0

[torspec/master] Fix section references from adding new section 3.4.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 50755bde094627d4980da26f67d22ab8af136234 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue Jan 14 11:14:26 2014 +0100 Fix section references from adding new section 3.4. --- dir-spec.txt | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 6b24c6f..44b8d4e 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -483,7 +483,7 @@ [At most once.] - An exit-policy summary as specified in sections 3.4 and 3.6.2, + An exit-policy summary as specified in sections 3.5 and 3.7.2, summarizing the router's rules for connecting to IPv6 addresses. A missing "ipv6-policy" line is equivalent to "ipv6-policy reject 1-65535". @@ -1186,7 +1186,7 @@ [At most once] - The exit-policy summary as specified in sections 3.4 and 3.6.2. A + The exit-policy summary as specified in sections 3.5 and 3.7.2. A missing "p" line is equivalent to "p reject 1-65535". [With microdescriptors, clients don't learn exact exit policies: @@ -1198,7 +1198,7 @@ [At most once] - The IPv6 exit policy summary as specified in sections 3.4 and 3.6.2. A + The IPv6 exit policy summary as specified in sections 3.5 and 3.7.2. A missing "p6" line is equivalent to "p6 reject 1-65535". (Only included when generating microdescriptors for @@ -1248,7 +1248,7 @@ http://<hostname>/tor/status-vote/next/d/<d>.z where <d> is the digest of the vote document. -3.4. Vote and consensus status documents +3.5. Vote and consensus status documents Votes and consensuses are more strictly formatted than other documents in this specification, since different authorities must be able to @@ -1288,7 +1288,7 @@ [At most once for votes; does not occur in consensuses.] A space-separated list of supported methods for generating - consensuses from votes. See section 3.6.1 for details. If this + consensuses from votes. See section 3.7.1 for details. If this line is present, method "1" MUST be included. Absence of the line means that only method "1" is supported. @@ -1296,7 +1296,7 @@ [At most once for consensuses; does not occur in votes.] - See section 3.6.1 for details. + See section 3.7.1 for details. (Only included when the vote is generated with consensus-method 2 or later.) @@ -1725,7 +1725,7 @@ 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.6.3. + These values are calculated as specified in section 3.7.3. The signature contains the following item, which appears Exactly Once for a vote, and At Least Once for a consensus. @@ -1756,7 +1756,7 @@ (Tor clients before 0.2.3.x did not understand the 'algorithm' field.) -3.5. Assigning flags in a vote +3.6. Assigning flags in a vote (This section describes how directory authorities choose which status flags to apply to routers. Later directory authorities MAY do things @@ -1898,9 +1898,9 @@ accept not for all addresses, ignoring all rejects for private netblocks. "Most" addresses are permitted if no more than 2^25 IPv4 addresses (two /8 networks) were blocked. The list is encoded - as described in section 3.6.2. + as described in section 3.7.2. -3.6. Computing a consensus from a set of votes +3.7. Computing a consensus from a set of votes Given a set of votes, authorities compute the contents of the consensus document as follows: @@ -1983,7 +1983,7 @@ for the descriptor we are listing. (They should all be the same. If they are not, we pick the most commonly listed one, breaking ties in favor of the lexicographically larger - vote.) The port list is encoded as specified in section 3.6.2. + vote.) The port list is encoded as specified in section 3.7.2. * If consensus-method 6 or later is in use and if 3 or more authorities provide a Measured= keyword in their votes for @@ -2027,7 +2027,7 @@ All ties in computing medians are broken in favor of the smaller or earlier item. -3.6.1. Forward compatibility +3.7.1. Forward compatibility Future versions of Tor will need to include new information in the consensus documents, but it is important that all authorities (or at least @@ -2065,7 +2065,7 @@ making changes in the contents of consensus; not for making backward-incompatible changes in their format.) -3.6.2. Encoding port lists +3.7.2. Encoding port lists Whether the summary shows the list of accepted ports or the list of rejected ports depends on which list is shorter (has a shorter string @@ -2085,7 +2085,7 @@ use an accept-style summary and list as much of the port list as is possible within these 1000 bytes. [XXXX be more specific.] -3.6.3. Computing Bandwidth Weights +3.7.3. Computing Bandwidth Weights Let weight_scale = 10000 @@ -2247,7 +2247,7 @@ Handle bridges and strange exit policies: Wgm=Wgg, Wem=Wee, Weg=Wed -3.7. Consensus flavors +3.8. Consensus flavors Consensus flavors are variants of the consensus that clients can choose to download and use instead of the unflavored consensus. The purpose @@ -2263,7 +2263,7 @@ Examples for consensus flavors include: - Publishing hashes of microdescriptors instead of hashes of - full descriptors (see section 3.7.2). + full descriptors (see section 3.8.2). - Including different digests of descriptors, instead of the perhaps-soon-to-be-totally-broken SHA1. @@ -2284,7 +2284,7 @@ "network-status-version" SP version SP flavor NL -3.7.1. ns consensus +3.8.1. ns consensus The ns consensus flavor is equivalent to the unflavored consensus except for its first line which states its consensus flavor name: @@ -2293,7 +2293,7 @@ [At start, exactly once.] -3.7.2. Microdescriptor consensus +3.8.2. Microdescriptor consensus The microdescriptor consensus is a consensus flavor that contains microdescriptor hashes instead of descriptor hashes and that omits @@ -2319,7 +2319,7 @@ [At start, exactly once.] - Similar to "r" lines in section 3.4, but without the digest element. + Similar to "r" lines in section 3.5, but without the digest element. "p" ... NL @@ -2349,7 +2349,7 @@ Additionally, a microdescriptor consensus MAY use the sha256 digest algorithm for its signatures. -3.8. Detached signatures +3.9. Detached signatures Assuming full connectivity, every authority should compute and sign the same consensus including any flavors in each period. Therefore, it @@ -2791,7 +2791,7 @@ Everyone besides directory authorities uses the approaches in this section to decide which relays to use and what their keys are likely to be. - (Directory authorities just believe their own opinions, as in section 3.5 + (Directory authorities just believe their own opinions, as in section 3.6 above.) 6.1. Choosing routers for circuits.

1 0

[torspec/master] Move part of 4.1. "Voting" to new 3.4.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 5d226d2d007c402870e3a936d2986c723418a6a8 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue Jan 14 11:09:36 2014 +0100 Move part of 4.1. "Voting" to new 3.4. This commit does not yet repair section numbering or references. --- dir-spec.txt | 74 ++++++++++++++++++++++++++++++---------------------------- 1 file changed, 38 insertions(+), 36 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index fa13bee..6b24c6f 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1210,6 +1210,44 @@ they need to confirm the actual identity key when doing a TLS handshake, and all they need to put the identity key digest in their CREATE cells.) +3.4. Exchanging votes + + Authorities divide time into Intervals. Authority administrators SHOULD + try to all pick the same interval length, and SHOULD pick intervals that + are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30 + minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to + divide evenly into a 24-hour day. + + Authorities SHOULD act according to interval and delays in the + latest consensus. Lacking a latest consensus, they SHOULD default to a + 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay. + + Authorities MUST take pains to ensure that their clocks remain accurate + within a few seconds. (Running NTP is usually sufficient.) + + The first voting period of each day begins at 00:00 (midnight) UTC. If + the last period of the day would be truncated by one-half or more, it is + merged with the second-to-last period. + + An authority SHOULD publish its vote immediately at the start of each voting + period (minus VoteSeconds+DistSeconds). It does this by making it + available at + http://<hostname>/tor/status-vote/next/authority.z + and sending it in an HTTP POST request to each other authority at the URL + http://<hostname>/tor/post/vote + + If, at the start of the voting period, minus DistSeconds, an authority + does not have a current statement from another authority, the first + authority downloads the other's statement. + + Once an authority has a vote from another authority, it makes it available + at + http://<hostname>/tor/status-vote/next/<fp>.z + where <fp> is the fingerprint of the other authority's identity key. + And at + http://<hostname>/tor/status-vote/next/d/<d>.z + where <d> is the digest of the vote document. + 3.4. Vote and consensus status documents Votes and consensuses are more strictly formatted than other documents @@ -2379,42 +2417,6 @@ 4.1. Voting (authorities only) - Authorities divide time into Intervals. Authority administrators SHOULD - try to all pick the same interval length, and SHOULD pick intervals that - are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30 - minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to - divide evenly into a 24-hour day. - - Authorities SHOULD act according to interval and delays in the - latest consensus. Lacking a latest consensus, they SHOULD default to a - 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay. - - Authorities MUST take pains to ensure that their clocks remain accurate - within a few seconds. (Running NTP is usually sufficient.) - - The first voting period of each day begins at 00:00 (midnight) UTC. If - the last period of the day would be truncated by one-half or more, it is - merged with the second-to-last period. - - An authority SHOULD publish its vote immediately at the start of each voting - period (minus VoteSeconds+DistSeconds). It does this by making it - available at - http://<hostname>/tor/status-vote/next/authority.z - and sending it in an HTTP POST request to each other authority at the URL - http://<hostname>/tor/post/vote - - If, at the start of the voting period, minus DistSeconds, an authority - does not have a current statement from another authority, the first - authority downloads the other's statement. - - Once an authority has a vote from another authority, it makes it available - at - http://<hostname>/tor/status-vote/next/<fp>.z - where <fp> is the fingerprint of the other authority's identity key. - And at - http://<hostname>/tor/status-vote/next/d/<d>.z - where <d> is the digest of the vote document. - The consensus status, along with as many signatures as the server currently knows, should be available at http://<hostname>/tor/status-vote/next/consensus.z

1 0

[torspec/master] Fix references from moving section 4.1 to 3.2.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 6e5d367a290c7b84f78909e8f81cbaf8c1b39153 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Mon Jan 13 19:58:15 2014 +0100 Fix references from moving section 4.1 to 3.2. --- dir-spec.txt | 64 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index c6fe1c5..46d92fa 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -483,7 +483,7 @@ [At most once.] - An exit-policy summary as specified in sections 3.3 and 3.5.2, + An exit-policy summary as specified in sections 3.4 and 3.6.2, summarizing the router's rules for connecting to IPv6 addresses. A missing "ipv6-policy" line is equivalent to "ipv6-policy reject 1-65535". @@ -1096,7 +1096,7 @@ Authorities MUST generate a new signing key and corresponding certificate before the key expires. -4.1. Accepting uploads (authorities only) +3.2. Accepting uploads (authorities only) When a router posts a signed descriptor to a directory authority, the authority first checks whether it is well-formed and correctly @@ -1131,7 +1131,7 @@ descriptor that it believes is currently useful. If so, it accepts it and stores it and serves it as requested. If not, it drops it. -3.2. Microdescriptors +3.3. Microdescriptors Microdescriptors are a stripped-down version of router descriptors generated by the directory authorities which may additionally contain @@ -1149,7 +1149,7 @@ contain any version information, because their version is determined by the consensus method. -3.2.1. Microdescriptors in consensus method 8 or later +3.3.1. Microdescriptors in consensus method 8 or later Starting with consensus method 8, microdescriptors contain the following elements taken from or based on the router descriptor. Order @@ -1188,7 +1188,7 @@ [At most once] - The exit-policy summary as specified in sections 3.3 and 3.5.2. A + The exit-policy summary as specified in sections 3.4 and 3.6.2. A missing "p" line is equivalent to "p reject 1-65535". [With microdescriptors, clients don't learn exact exit policies: @@ -1200,7 +1200,7 @@ [At most once] - The IPv6 exit policy summary as specified in sections 3.3 and 3.5.2. A + The IPv6 exit policy summary as specified in sections 3.4 and 3.6.2. A missing "p6" line is equivalent to "p6 reject 1-65535". (Only included when generating microdescriptors for @@ -1212,7 +1212,7 @@ they need to confirm the actual identity key when doing a TLS handshake, and all they need to put the identity key digest in their CREATE cells.) -3.3. Vote and consensus status documents +3.4. Vote and consensus status documents Votes and consensuses are more strictly formatted than other documents in this specification, since different authorities must be able to @@ -1252,7 +1252,7 @@ [At most once for votes; does not occur in consensuses.] A space-separated list of supported methods for generating - consensuses from votes. See section 3.5.1 for details. If this + consensuses from votes. See section 3.6.1 for details. If this line is present, method "1" MUST be included. Absence of the line means that only method "1" is supported. @@ -1260,7 +1260,7 @@ [At most once for consensuses; does not occur in votes.] - See section 3.5.1 for details. + See section 3.6.1 for details. (Only included when the vote is generated with consensus-method 2 or later.) @@ -1689,7 +1689,7 @@ 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.5.3. + These values are calculated as specified in section 3.6.3. The signature contains the following item, which appears Exactly Once for a vote, and At Least Once for a consensus. @@ -1720,7 +1720,7 @@ (Tor clients before 0.2.3.x did not understand the 'algorithm' field.) -3.4. Assigning flags in a vote +3.5. Assigning flags in a vote (This section describes how directory authorities choose which status flags to apply to routers. Later directory authorities MAY do things @@ -1862,9 +1862,9 @@ accept not for all addresses, ignoring all rejects for private netblocks. "Most" addresses are permitted if no more than 2^25 IPv4 addresses (two /8 networks) were blocked. The list is encoded - as described in section 3.5.2. + as described in section 3.6.2. -3.5. Computing a consensus from a set of votes +3.6. Computing a consensus from a set of votes Given a set of votes, authorities compute the contents of the consensus document as follows: @@ -1947,7 +1947,7 @@ for the descriptor we are listing. (They should all be the same. If they are not, we pick the most commonly listed one, breaking ties in favor of the lexicographically larger - vote.) The port list is encoded as specified in section 3.5.2. + vote.) The port list is encoded as specified in section 3.6.2. * If consensus-method 6 or later is in use and if 3 or more authorities provide a Measured= keyword in their votes for @@ -1991,7 +1991,7 @@ All ties in computing medians are broken in favor of the smaller or earlier item. -3.5.1. Forward compatibility +3.6.1. Forward compatibility Future versions of Tor will need to include new information in the consensus documents, but it is important that all authorities (or at least @@ -2029,7 +2029,7 @@ making changes in the contents of consensus; not for making backward-incompatible changes in their format.) -3.5.2. Encoding port lists +3.6.2. Encoding port lists Whether the summary shows the list of accepted ports or the list of rejected ports depends on which list is shorter (has a shorter string @@ -2049,7 +2049,7 @@ use an accept-style summary and list as much of the port list as is possible within these 1000 bytes. [XXXX be more specific.] -3.5.3. Computing Bandwidth Weights +3.6.3. Computing Bandwidth Weights Let weight_scale = 10000 @@ -2211,7 +2211,7 @@ Handle bridges and strange exit policies: Wgm=Wgg, Wem=Wee, Weg=Wed -3.6. Consensus flavors +3.7. Consensus flavors Consensus flavors are variants of the consensus that clients can choose to download and use instead of the unflavored consensus. The purpose @@ -2227,7 +2227,7 @@ Examples for consensus flavors include: - Publishing hashes of microdescriptors instead of hashes of - full descriptors (see section 3.6.2). + full descriptors (see section 3.7.2). - Including different digests of descriptors, instead of the perhaps-soon-to-be-totally-broken SHA1. @@ -2248,7 +2248,7 @@ "network-status-version" SP version SP flavor NL -3.6.1. ns consensus +3.7.1. ns consensus The ns consensus flavor is equivalent to the unflavored consensus except for its first line which states its consensus flavor name: @@ -2257,7 +2257,7 @@ [At start, exactly once.] -3.6.2. Microdescriptor consensus +3.7.2. Microdescriptor consensus The microdescriptor consensus is a consensus flavor that contains microdescriptor hashes instead of descriptor hashes and that omits @@ -2283,7 +2283,7 @@ [At start, exactly once.] - Similar to "r" lines in section 3.3, but without the digest element. + Similar to "r" lines in section 3.4, but without the digest element. "p" ... NL @@ -2313,7 +2313,7 @@ Additionally, a microdescriptor consensus MAY use the sha256 digest algorithm for its signatures. -3.7. Detached signatures +3.8. Detached signatures Assuming full connectivity, every authority should compute and sign the same consensus including any flavors in each period. Therefore, it @@ -2379,7 +2379,7 @@ All directory authorities and directory caches ("directory servers") implement this section, except as noted. -4.2. Voting (authorities only) +4.1. Voting (authorities only) Authorities divide time into Intervals. Authority administrators SHOULD try to all pick the same interval length, and SHOULD pick intervals that @@ -2453,7 +2453,7 @@ /tor/status-vote/(current|next)/consensus-F.z. and /tor/status-vote/(current|next)/consensus-F/<FP1>+....z. -4.3. Downloading consensus status documents (caches only) +4.2. Downloading consensus status documents (caches only) All directory servers (authorities and caches) try to keep a recent network-status consensus document to serve to clients. A cache ALWAYS @@ -2477,7 +2477,7 @@ length. Caches serve all consensus flavors from the same locations as the directory authorities. -4.4. Downloading and storing router descriptors (authorities and caches) +4.3. Downloading and storing router descriptors (authorities and caches) Periodically (currently, every 10 seconds), directory servers check whether there are any specific descriptors that they do not have and that @@ -2509,9 +2509,9 @@ [XXXX define recent] Authorities SHOULD NOT download descriptors for routers that they would - immediately reject for reasons listed in section 4.1. + immediately reject for reasons listed in section 3.2. -4.5. Downloading and storing microdescriptors (caches only) +4.4. Downloading and storing microdescriptors (caches only) Directory mirrors should fetch, cache, and serve each microdescriptor from the authorities. @@ -2532,7 +2532,7 @@ (NOTE: Due to squid proxy url limitations at most 92 microdescrriptor hashes can be retrieved in a single request.) -4.6. Downloading and storing extra-info documents +4.5. Downloading and storing extra-info documents All authorities, and any cache that chooses to cache extra-info documents, and any client that uses extra-info documents, should implement this @@ -2546,9 +2546,9 @@ documents currently held. If so, it downloads whatever extra-info documents are missing. Caches download from authorities; non-caches try to download from caches. We follow the same splitting and back-off rules - as in section 4.4 (if a cache) or section 5.3 (if a client). + as in section 4.3 (if a cache) or section 5.3 (if a client). -4.7. General-use HTTP URLs +4.6. General-use HTTP URLs "Fingerprints" in these URLs are base16-encoded SHA1 hashes. @@ -2791,7 +2791,7 @@ Everyone besides directory authorities uses the approaches in this section to decide which relays to use and what their keys are likely to be. - (Directory authorities just believe their own opinions, as in section 3.4 + (Directory authorities just believe their own opinions, as in section 3.5 above.) 6.1. Choosing routers for circuits.

1 0

[torspec/master] Make 3.5 and 3.6 subsections of 3.4.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit fc17048ec0328459d872f48d6048e740107b6e77 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue Jan 14 11:25:34 2014 +0100 Make 3.5 and 3.6 subsections of 3.4. The vote status document format (3.5) and the process of assigning flags in a vote (3.6) are both part of the authority operation "exchanging votes" and not operations on their own. That's why they should be subsubsections rather than subsections. This results in the following changes to section numbers: * 3.5 -> 3.4.1 * 3.6 -> 3.4.2 * 3.7 -> 3.5 * 3.8 -> 3.6 * 3.9 -> 3.7 --- dir-spec.txt | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 44b8d4e..94570a9 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -483,7 +483,7 @@ [At most once.] - An exit-policy summary as specified in sections 3.5 and 3.7.2, + An exit-policy summary as specified in sections 3.4.1 and 3.5.2, summarizing the router's rules for connecting to IPv6 addresses. A missing "ipv6-policy" line is equivalent to "ipv6-policy reject 1-65535". @@ -1186,7 +1186,7 @@ [At most once] - The exit-policy summary as specified in sections 3.5 and 3.7.2. A + The exit-policy summary as specified in sections 3.4.1 and 3.5.2. A missing "p" line is equivalent to "p reject 1-65535". [With microdescriptors, clients don't learn exact exit policies: @@ -1198,7 +1198,7 @@ [At most once] - The IPv6 exit policy summary as specified in sections 3.5 and 3.7.2. A + The IPv6 exit policy summary as specified in sections 3.4.1 and 3.5.2. A missing "p6" line is equivalent to "p6 reject 1-65535". (Only included when generating microdescriptors for @@ -1248,7 +1248,7 @@ http://<hostname>/tor/status-vote/next/d/<d>.z where <d> is the digest of the vote document. -3.5. Vote and consensus status documents +3.4.1. 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 @@ -1288,7 +1288,7 @@ [At most once for votes; does not occur in consensuses.] A space-separated list of supported methods for generating - consensuses from votes. See section 3.7.1 for details. If this + consensuses from votes. See section 3.5.1 for details. If this line is present, method "1" MUST be included. Absence of the line means that only method "1" is supported. @@ -1296,7 +1296,7 @@ [At most once for consensuses; does not occur in votes.] - See section 3.7.1 for details. + See section 3.5.1 for details. (Only included when the vote is generated with consensus-method 2 or later.) @@ -1725,7 +1725,7 @@ 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.7.3. + These values are calculated as specified in section 3.5.3. The signature contains the following item, which appears Exactly Once for a vote, and At Least Once for a consensus. @@ -1756,7 +1756,7 @@ (Tor clients before 0.2.3.x did not understand the 'algorithm' field.) -3.6. Assigning flags in a vote +3.4.2. Assigning flags in a vote (This section describes how directory authorities choose which status flags to apply to routers. Later directory authorities MAY do things @@ -1898,9 +1898,9 @@ accept not for all addresses, ignoring all rejects for private netblocks. "Most" addresses are permitted if no more than 2^25 IPv4 addresses (two /8 networks) were blocked. The list is encoded - as described in section 3.7.2. + as described in section 3.5.2. -3.7. Computing a consensus from a set of votes +3.5. Computing a consensus from a set of votes Given a set of votes, authorities compute the contents of the consensus document as follows: @@ -1983,7 +1983,7 @@ for the descriptor we are listing. (They should all be the same. If they are not, we pick the most commonly listed one, breaking ties in favor of the lexicographically larger - vote.) The port list is encoded as specified in section 3.7.2. + vote.) The port list is encoded as specified in section 3.5.2. * If consensus-method 6 or later is in use and if 3 or more authorities provide a Measured= keyword in their votes for @@ -2027,7 +2027,7 @@ All ties in computing medians are broken in favor of the smaller or earlier item. -3.7.1. Forward compatibility +3.5.1. Forward compatibility Future versions of Tor will need to include new information in the consensus documents, but it is important that all authorities (or at least @@ -2065,7 +2065,7 @@ making changes in the contents of consensus; not for making backward-incompatible changes in their format.) -3.7.2. Encoding port lists +3.5.2. Encoding port lists Whether the summary shows the list of accepted ports or the list of rejected ports depends on which list is shorter (has a shorter string @@ -2085,7 +2085,7 @@ use an accept-style summary and list as much of the port list as is possible within these 1000 bytes. [XXXX be more specific.] -3.7.3. Computing Bandwidth Weights +3.5.3. Computing Bandwidth Weights Let weight_scale = 10000 @@ -2247,7 +2247,7 @@ Handle bridges and strange exit policies: Wgm=Wgg, Wem=Wee, Weg=Wed -3.8. Consensus flavors +3.6. Consensus flavors Consensus flavors are variants of the consensus that clients can choose to download and use instead of the unflavored consensus. The purpose @@ -2263,7 +2263,7 @@ Examples for consensus flavors include: - Publishing hashes of microdescriptors instead of hashes of - full descriptors (see section 3.8.2). + full descriptors (see section 3.6.2). - Including different digests of descriptors, instead of the perhaps-soon-to-be-totally-broken SHA1. @@ -2284,7 +2284,7 @@ "network-status-version" SP version SP flavor NL -3.8.1. ns consensus +3.6.1. ns consensus The ns consensus flavor is equivalent to the unflavored consensus except for its first line which states its consensus flavor name: @@ -2293,7 +2293,7 @@ [At start, exactly once.] -3.8.2. Microdescriptor consensus +3.6.2. Microdescriptor consensus The microdescriptor consensus is a consensus flavor that contains microdescriptor hashes instead of descriptor hashes and that omits @@ -2319,7 +2319,7 @@ [At start, exactly once.] - Similar to "r" lines in section 3.5, but without the digest element. + Similar to "r" lines in section 3.4.1, but without the digest element. "p" ... NL @@ -2349,7 +2349,7 @@ Additionally, a microdescriptor consensus MAY use the sha256 digest algorithm for its signatures. -3.9. Detached signatures +3.7. Detached signatures Assuming full connectivity, every authority should compute and sign the same consensus including any flavors in each period. Therefore, it @@ -2791,7 +2791,7 @@ Everyone besides directory authorities uses the approaches in this section to decide which relays to use and what their keys are likely to be. - (Directory authorities just believe their own opinions, as in section 3.6 + (Directory authorities just believe their own opinions, as in section 3.4.2 above.) 6.1. Choosing routers for circuits.

1 0

[torspec/master] Copy 4.3 "Downloading router descriptors" after 3.5.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 5c2ee924adbc0ec3b3ebd7f39e0139de5a15069e Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue Jan 14 12:28:48 2014 +0100 Copy 4.3 "Downloading router descriptors" after 3.5. This commit does not yet repair section numbering or references. --- dir-spec.txt | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/dir-spec.txt b/dir-spec.txt index e46da61..ad59fcd 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1903,6 +1903,40 @@ XXX when to download certificates. +4.3. Downloading and storing router descriptors (authorities and caches) + + Periodically (currently, every 10 seconds), directory servers check + whether there are any specific descriptors that they do not have and that + they are not currently trying to download. Caches identify these + descriptors by hash in the recent network-status consensus documents; + authorities identify them by hash in vote (if publication date is more + recent than the descriptor we currently have). + + [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can + do that for now.] + + If so, the directory server launches requests to the authorities for these + descriptors, such that each authority is only asked for descriptors listed + in its most recent vote (if the requester is an authority) or in the + consensus (if the requester is a cache). If we're an authority, and more + than one authority lists the descriptor, we choose which to ask at random. + + If one of these downloads fails, we do not try to download that descriptor + from the authority that failed to serve it again unless we receive a newer + network-status (consensus or vote) from that authority that lists the same + descriptor. + + Directory servers must potentially cache multiple descriptors for each + router. Servers must not discard any descriptor listed by any recent + consensus. If there is enough space to store additional descriptors, + servers SHOULD try to hold those which clients are likely to download the + most. (Currently, this is judged based on the interval for which each + descriptor seemed newest.) +[XXXX define recent] + + Authorities SHOULD NOT download descriptors for routers that they would + immediately reject for reasons listed in section 3.2. + 3.6. Computing a consensus from a set of votes Given a set of votes, authorities compute the contents of the consensus

1 0

[torspec/master] Add new section 3.5 "Downloading missing certificates".
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit 866123c9c5bc5be085398b41e1a7c8fd5d25f56c Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue Jan 14 11:34:05 2014 +0100 Add new section 3.5 "Downloading missing certificates". This subsection is just a placeholder for now. Also fix section numbers and references. --- dir-spec.txt | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 94570a9..e46da61 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -18,7 +18,6 @@ 103 Splitting identity key from regularly used signing key 104 Long and Short Router Descriptors - XXX when to download certificates. XXX timeline XXX fill in XXXXs @@ -483,7 +482,7 @@ [At most once.] - An exit-policy summary as specified in sections 3.4.1 and 3.5.2, + An exit-policy summary as specified in sections 3.4.1 and 3.6.2, summarizing the router's rules for connecting to IPv6 addresses. A missing "ipv6-policy" line is equivalent to "ipv6-policy reject 1-65535". @@ -1186,7 +1185,7 @@ [At most once] - The exit-policy summary as specified in sections 3.4.1 and 3.5.2. A + The exit-policy summary as specified in sections 3.4.1 and 3.6.2. A missing "p" line is equivalent to "p reject 1-65535". [With microdescriptors, clients don't learn exact exit policies: @@ -1198,7 +1197,7 @@ [At most once] - The IPv6 exit policy summary as specified in sections 3.4.1 and 3.5.2. A + The IPv6 exit policy summary as specified in sections 3.4.1 and 3.6.2. A missing "p6" line is equivalent to "p6 reject 1-65535". (Only included when generating microdescriptors for @@ -1288,7 +1287,7 @@ [At most once for votes; does not occur in consensuses.] A space-separated list of supported methods for generating - consensuses from votes. See section 3.5.1 for details. If this + consensuses from votes. See section 3.6.1 for details. If this line is present, method "1" MUST be included. Absence of the line means that only method "1" is supported. @@ -1296,7 +1295,7 @@ [At most once for consensuses; does not occur in votes.] - See section 3.5.1 for details. + See section 3.6.1 for details. (Only included when the vote is generated with consensus-method 2 or later.) @@ -1725,7 +1724,7 @@ 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.5.3. + These values are calculated as specified in section 3.6.3. The signature contains the following item, which appears Exactly Once for a vote, and At Least Once for a consensus. @@ -1898,9 +1897,13 @@ accept not for all addresses, ignoring all rejects for private netblocks. "Most" addresses are permitted if no more than 2^25 IPv4 addresses (two /8 networks) were blocked. The list is encoded - as described in section 3.5.2. + as described in section 3.6.2. + +3.5. Downloading missing certificates + + XXX when to download certificates. -3.5. Computing a consensus from a set of votes +3.6. Computing a consensus from a set of votes Given a set of votes, authorities compute the contents of the consensus document as follows: @@ -1983,7 +1986,7 @@ for the descriptor we are listing. (They should all be the same. If they are not, we pick the most commonly listed one, breaking ties in favor of the lexicographically larger - vote.) The port list is encoded as specified in section 3.5.2. + vote.) The port list is encoded as specified in section 3.6.2. * If consensus-method 6 or later is in use and if 3 or more authorities provide a Measured= keyword in their votes for @@ -2027,7 +2030,7 @@ All ties in computing medians are broken in favor of the smaller or earlier item. -3.5.1. Forward compatibility +3.6.1. Forward compatibility Future versions of Tor will need to include new information in the consensus documents, but it is important that all authorities (or at least @@ -2065,7 +2068,7 @@ making changes in the contents of consensus; not for making backward-incompatible changes in their format.) -3.5.2. Encoding port lists +3.6.2. Encoding port lists Whether the summary shows the list of accepted ports or the list of rejected ports depends on which list is shorter (has a shorter string @@ -2085,7 +2088,7 @@ use an accept-style summary and list as much of the port list as is possible within these 1000 bytes. [XXXX be more specific.] -3.5.3. Computing Bandwidth Weights +3.6.3. Computing Bandwidth Weights Let weight_scale = 10000 @@ -2247,7 +2250,7 @@ Handle bridges and strange exit policies: Wgm=Wgg, Wem=Wee, Weg=Wed -3.6. Consensus flavors +3.7. Consensus flavors Consensus flavors are variants of the consensus that clients can choose to download and use instead of the unflavored consensus. The purpose @@ -2263,7 +2266,7 @@ Examples for consensus flavors include: - Publishing hashes of microdescriptors instead of hashes of - full descriptors (see section 3.6.2). + full descriptors (see section 3.7.2). - Including different digests of descriptors, instead of the perhaps-soon-to-be-totally-broken SHA1. @@ -2284,7 +2287,7 @@ "network-status-version" SP version SP flavor NL -3.6.1. ns consensus +3.7.1. ns consensus The ns consensus flavor is equivalent to the unflavored consensus except for its first line which states its consensus flavor name: @@ -2293,7 +2296,7 @@ [At start, exactly once.] -3.6.2. Microdescriptor consensus +3.7.2. Microdescriptor consensus The microdescriptor consensus is a consensus flavor that contains microdescriptor hashes instead of descriptor hashes and that omits @@ -2349,7 +2352,7 @@ Additionally, a microdescriptor consensus MAY use the sha256 digest algorithm for its signatures. -3.7. Detached signatures +3.8. Detached signatures Assuming full connectivity, every authority should compute and sign the same consensus including any flavors in each period. Therefore, it

1 0

[torspec/master] Clean up copied section 3.6 and section 4.3.
by nickm＠torproject.org 17 Jan '14

17 Jan '14

commit c0e39f28b02bd247b20ecbe16750a475b06b876a Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue Jan 14 12:42:07 2014 +0100 Clean up copied section 3.6 and section 4.3. Take out cache-only parts from 3.6 and authority-only parts from 4.3. --- dir-spec.txt | 49 ++++++++++++++++++------------------------------- 1 file changed, 18 insertions(+), 31 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 4fc8fdd..0082443 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1905,20 +1905,18 @@ 3.6. Downloading router descriptors - Periodically (currently, every 10 seconds), directory servers check + Periodically (currently, every 10 seconds), directory authorities check whether there are any specific descriptors that they do not have and that - they are not currently trying to download. Caches identify these - descriptors by hash in the recent network-status consensus documents; - authorities identify them by hash in vote (if publication date is more + they are not currently trying to download. + Authorities identify them by hash in vote (if publication date is more recent than the descriptor we currently have). [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can do that for now.] - If so, the directory server launches requests to the authorities for these + If so, the directory authority launches requests to the authorities for these descriptors, such that each authority is only asked for descriptors listed - in its most recent vote (if the requester is an authority) or in the - consensus (if the requester is a cache). If we're an authority, and more + in its most recent vote. If more than one authority lists the descriptor, we choose which to ask at random. If one of these downloads fails, we do not try to download that descriptor @@ -1926,10 +1924,10 @@ network-status (consensus or vote) from that authority that lists the same descriptor. - Directory servers must potentially cache multiple descriptors for each - router. Servers must not discard any descriptor listed by any recent + Directory authorities must potentially cache multiple descriptors for each + router. Authorities must not discard any descriptor listed by any recent consensus. If there is enough space to store additional descriptors, - servers SHOULD try to hold those which clients are likely to download the + authorities SHOULD try to hold those which clients are likely to download the most. (Currently, this is judged based on the interval for which each descriptor seemed newest.) [XXXX define recent] @@ -2514,39 +2512,28 @@ length. Caches serve all consensus flavors from the same locations as the directory authorities. -4.3. Downloading and storing router descriptors (authorities and caches) +4.3. Downloading router descriptors - Periodically (currently, every 10 seconds), directory servers check + Periodically (currently, every 10 seconds), directory caches check whether there are any specific descriptors that they do not have and that they are not currently trying to download. Caches identify these - descriptors by hash in the recent network-status consensus documents; - authorities identify them by hash in vote (if publication date is more - recent than the descriptor we currently have). - - [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can - do that for now.] + descriptors by hash in the recent network-status consensus documents. - If so, the directory server launches requests to the authorities for these - descriptors, such that each authority is only asked for descriptors listed - in its most recent vote (if the requester is an authority) or in the - consensus (if the requester is a cache). If we're an authority, and more - than one authority lists the descriptor, we choose which to ask at random. + If so, the directory cache launches requests to the authorities for these + descriptors. If one of these downloads fails, we do not try to download that descriptor from the authority that failed to serve it again unless we receive a newer - network-status (consensus or vote) from that authority that lists the same - descriptor. + network-status consensus that lists the same descriptor. - Directory servers must potentially cache multiple descriptors for each - router. Servers must not discard any descriptor listed by any recent + Directory caches must potentially cache multiple descriptors for each + router. Caches must not discard any descriptor listed by any recent consensus. If there is enough space to store additional descriptors, - servers SHOULD try to hold those which clients are likely to download the + caches SHOULD try to hold those which clients are likely to download the most. (Currently, this is judged based on the interval for which each descriptor seemed newest.) -[XXXX define recent] - Authorities SHOULD NOT download descriptors for routers that they would - immediately reject for reasons listed in section 3.2. + [XXXX define recent] 4.4. Downloading and storing microdescriptors (caches only)

1 0