-
Notifications
You must be signed in to change notification settings - Fork 84
/
315-update-dir-required-fields.txt
131 lines (102 loc) · 5.22 KB
/
315-update-dir-required-fields.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
Filename: 315-update-dir-required-fields.txt
Title: Updating the list of fields required in directory documents
Author: Nick Mathewson
Created: 23 April 2020
Status: Closed
Implemented-In: 0.4.5.1-alpha
Notes:
The "hidden-service-dir" field was not made assumed-present; all other
fields were updated.
1. Introduction
When we add a new field to a directory document, we must at first
describe it as "optional", since older Tor implementations will
not generate it. When those implementations are obsolete and
unsupported, however, we can safely describe those fields as
"required", since they are always included in practice.
Making fields required is not just a matter of bookkeeping: it
helps prevent bugs in two ways. First, it simplifies our code.
Second, it makes our code's requirements match our assumptions
about the network.
Here I'll describe a general policy for making fields required
when LTS versions become unsupported, and include a list of
fields that should become required today.
This document does not require to us to make all optional fields
required -- only those which we intend that all Tor instances
should always generate and expect.
When we speak of making a field "required", we are talking about
describing it as "required" in dir-spec.txt, so that any document
missing that field is no longer considered well-formed.
2. When fields should become required
We have four relevant kinds of directory documents: those
generated by public relays, those generated by bridges, those
generated by authorities, and those generated by onion services.
Relays generate extrainfo documents and routerdesc documents.
For these, we can safely make a field required when it is always
generated by all relay versions that the authorities allow to
join the network. To avoid partitioning, authorities should
start requiring the field before any relays or clients do.
(If a relay field indicates the presence of a now-required
feature, then instead of making the field mandatory, we may
change the semantics so that the field is assumed to be
present. Later we can remove the option.)
Bridge relays have their descriptors processed by clients
without necessarily passing through authorities.
We can make fields mandatory in bridge descriptors once we
can be confident that no bridge lacking them will actually
connect to the network-- or that all such bridges are safe
to stop using.
For bridges, when a field becomes required, it will take some
time before all clients require that field. This would create a
partitioning opportunity, but partitioning at the first-hop
position is not so strong: the bridge already knows the client's
IP, which is a much better identifier than the client's Tor
version.
Authorities generate authority certificates, votes, consensus
documents, and microdescriptors. For these, we can safely make a
field required once all authorities are generating it, and we are
confident that we do not plan to downgrade those authorities.
Onion services generate service descriptors. Because of the risk
of partitioning attacks, we should not make features in service
descriptors required without a phased process, described in the
following section.
2.1. Phased addition of onion service descriptor changes
Phase one: we add client and service support for the new field,
but have this support disabled by default. By default, services
should not generate the new field, and clients should not parse
it when it is present. This behavior is controlled by a pair of
network parameters. (If the feature is at all complex, the
network parameters should describe a _minimum version_ that
should enable the feature, so that we can later enable it only in
the versions where the feature is not buggy.)
During this phase, we can manually override the defaults on
particular clients and services to test the new field.
Phase two: authorities use the network parameters to enable the
client support and the service support. They should only do this
once enough clients and services have upgraded to a version that
supports the feature.
Phase three: once all versions that support the feature are
obsolete and unsupported, the feature may be marked as required
in the specifications, and the network parameters ignored.
Phase four: once all versions that used the network parameters
are obsolete and unsupported, authorities may stop including
those parameters in their votes.
3. Directory fields that should become required.
These fields in router descriptors should become required:
* identity-ed25519
* master-key-ed25519
* onion-key-crosscert
* ntor-onion-key
* ntor-onion-key-crosscert
* router-sig-ed25519
* proto
These fields in router descriptors should become "assumed present":
* hidden-service-dir
These fields in extra-info documents should become required:
* identity-ed25519
* router-sig-ed25519
The following fields in microdescriptors should become
required:
* ntor-onion-key
The following fields in votes and consensus documents should
become required:
* pr