Skip to content
Snippets Groups Projects
Commit eb4fb3c5 authored by David Goulet's avatar David Goulet :panda_face:
Browse files

Merge proposal 264 to dir-spec and tor-spec 


Signed-off-by: David Goulet's avatarDavid Goulet <dgoulet@torproject.org>
parent bb39e5dd
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
dir-spec.txt
+ 82
− 0
View file @ eb4fb3c5
......@@ -731,6 +731,32 @@
Present if the router accepts "tunneled" directory requests using a
BEGIN_DIR cell over the router's OR port.
"proto" SP Entries NL
[At most one.]
Entries =
Entries = Entry
Entries = Entry SP Entries
Entry = Keyword "=" 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
more than 2^32 - 1.
2.1.2. Extra-info document format
Extra-info documents consist of the following items:
......@@ -1425,6 +1451,11 @@
Implementations MUST ignore "id" lines with unrecognized
key-types in place of "rsa1024" or "ed25519"
"pr" SP Entries NL
[At most once.]
The "proto" element as specified in section 2.1.1.
(Note that with microdescriptors, clients do not learn the RSA identity of
their routers: they only learn a hash of the RSA identity key. This is
......@@ -1733,6 +1764,27 @@
Value is the actual shared random value encoded in base64. NumReveals
is the number of commits used to generate this SRV.
"recommended-relay-protocols" SP Entries NL
"required-relay-protocols" SP Entries NL
"recommended-client-protocols" SP Entries NL
"required-client-protocols" SP Entries NL
[At most once for each.]
The "proto" element as specified in section 2.1.1.
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. and should require a supermajority of
authorities (2/3) to make a protocol required. The required protocols
should not be torrc-configurable, but rather should be hardwired in
the Tor code.
The tor-spec.txt section 9 details how a relay and a client should
behave when they encounter these lines in the consensus.
"params" SP [Parameters] NL
[At most once]
......@@ -2010,6 +2062,19 @@
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.]
......@@ -2575,6 +2640,7 @@
"22" -- Instantiates Ed25519 voting algorithm correctly.
"23" -- Adds shared randomness protocol data.
"24" -- No longer lists routers that are not Valid in the consensus.
"25" -- Vote on recommended-protocols and required-protocols.
Before generating a consensus, an authority must decide which consensus
method to use. To do this, it looks for the highest version number
......@@ -3528,3 +3594,19 @@ C. Converting a curve25519 public key to an ed25519 public key
feed it to the ed25519 public key generation algorithm, and see
what the sign is.
D. Inferring missing proto lines.
The directory authorities no longer allow versions of Tor before
0.2.4.18-rc. But right now, there is no version of Tor in the consensus
before 0.2.4.19. Therefore, we should disallow versions of Tor earlier
than 0.2.4.19, so that we can have the protocol list for all current Tor
versions include:
Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1-2 Link=1-4
LinkAuth=1 Microdesc=1-2 Relay=1-2
For Desc, Tor versions before 0.2.7.stable should be taken to have Desc=1
and versions 0.2.7.stable or later should have Desc=1-2.
For Microdesc and Cons, Tor versions before 0.2.7.stable should be taken to
support version 1; 0.2.7.stable and later should have 1-2.
tor-spec.txt
+ 155
− 0
View file @ eb4fb3c5
......@@ -1610,3 +1610,158 @@ see tor-design.pdf.
cells in both directions on that circuit. Count the amount of
memory we recovered towards the total.
9. Subprotocol versioning
This section specifies the Tor subprotocol versioning. They are broken down
into different types with their current version numbers. Any new version
number should be added to this section.
The dir-spec.txt details how those versions are encoded. See the
"proto"/"pr" line in a descriptor and the "recommended-relay-protocols",
"required-relay-protocols", "recommended-client-protocols" and
"required-client-protocols" lines in the vote/consensus format.
Here are the rules a relay and client should follow when encountering a
protocol list in the consensus:
- When a relay lacks a protocol listed in recommended-relay-protocols,
it should warn its operator that the relay is obsolete.
- When a relay lacks a protocol listed in required-relay-protocols, it
must not attempt to join the network.
- When a client lacks a protocol listed in recommended-client-protocols,
it should warn the user that the client is obsolete.
- When a client lacks a protocol listed in required-client-protocols, it
must not connect to the network. This implements a "safe forward
shutdown" mechanism for zombie clients.
- If a client or relay has a cached consensus telling it that a given
protocol is required, and it does not implement that protocol, it
SHOULD NOT try to fetch a newer consensus.
Starting in version 0.2.9.4-alpha, the initial required protocols for
clients that we will Recommend and Require are:
Cons=1-2 Desc=1-2 DirCache=1 HSDir=2 HSIntro=3 HSRend=1 Link=4
LinkAuth=1 Microdesc=1-2 Relay=2
For relays we will Require:
Cons=1 Desc=1 DirCache=1 HSDir=2 HSIntro=3 HSRend=1 Link=3-4
LinkAuth=1 Microdesc=1 Relay=1-2
For relays, we will additionally Recommend all protocols which we
recommend for clients.
9.1. "Link"
The "link" protocols are those used by clients and relays to initiate and
receive OR connections and to handle cells on OR connections. The "link"
protocol versions correspond 1:1 to those versions.
Two Tor instances can make a connection to each other only if they have at
least one link protocol in common.
The current "link" versions are: "1" through "4". See section 4.1 for more
information. All current Tor versions support "1-3"; version from
0.2.4.11-alpha and on support "1-4". Eventually we will drop "1" and "2".
9.2. "LinkAuth"
LinkAuth protocols correspond to varieties of Authenticate cells used for
the v3+ link protocools.
The current version is "1".
"2" is unused, and reserved by proposal 244.
"3" is the ed25519 link handshake of proposal 220.
9.3. "Relay"
The "relay" protocols are those used to handle CREATE cells, and those that
handle the various RELAY cell types received after a CREATE cell. (Except,
relay cells used to manage introduction and rendezvous points are managed
with the "HSIntro" and "HSRend" protocols respectively.)
Current versions are:
"1" -- supports the TAP key exchange, with all features in Tor 0.2.3.
Support for CREATE and CREATED and CREATE_FAST and CREATED_FAST
and EXTEND and EXTENDED.
"2" -- supports the ntor key exchange, and all features in Tor
0.2.4.19. Includes support for CREATE2 and CREATED2 and
EXTEND2 and EXTENDED2.
9.4. "HSIntro"
The "HSIntro" protocol handles introduction points.
"3" -- supports authentication as of proposal 121 in Tor
0.2.1.6-alpha.
9.5. "HSRend"
The "HSRend" protocol handles rendezvous points.
"1" -- supports all features in Tor 0.0.6.
"2" -- supports RENDEZVOUS2 cells of arbitrary length as long as they
have 20 bytes of cookie in Tor 0.2.9.1-alpha.
9.6. "HSDir"
The "HSDir" protocols are the set of hidden service document types that can
be uploaded to, understood by, and downloaded from a tor relay, and the set
of URLs available to fetch them.
"1" -- supports all features in Tor 0.2.0.10-alpha.
9.7. "DirCache"
The "DirCache" protocols are the set of documents available for download
from a directory cache via BEGIN_DIR, and the set of URLs available to
fetch them. (This excludes URLs for hidden service objects.)
"1" -- supports all features in Tor 0.2.4.19.
9.8. "Desc"
Describes features present or absent in descriptors.
Most features in descriptors don't require a "Desc" update -- only those
that need to someday be required. For example, someday clients will need
to understand ed25519 identities.
"1" -- supports all features in Tor 0.2.4.19.
"2" -- cross-signing with onion-keys, signing with ed25519
identities.
9.9. "Microdesc"
Describes features present or absent in microdescriptors.
Most features in descriptors don't require a "MicroDesc" update -- only
those that need to someday be required. These correspond more or less with
consensus methods.
"1" -- consensus methods 9 through 20.
"2" -- consensus method 21 (adds ed25519 keys to microdescs).
9.10. "Cons"
Describes features present or absent in consensus documents.
Most features in consensus documents don't require a "Cons" update -- only
those that need to someday be required.
These correspond more or less with consensus methods.
"1" -- consensus methods 9 through 20.
"2" -- consensus method 21 (adds ed25519 keys to microdescs).
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment