commit 1040c2d0fc972d2659391ddee1e36dff49ad498f Author: Nick Mathewson nickm@torproject.org Date: Fri Oct 16 16:21:04 2020 -0400

Document newly required fields from prop315. --- dir-spec.txt | 46 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 14 deletions(-)

diff --git a/dir-spec.txt b/dir-spec.txt index dbb15ab..68a1319 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -441,7 +441,7 @@ "identity-ed25519" NL "-----BEGIN ED25519 CERT-----" NL certificate "-----END ED25519 CERT-----" NL

- [At most once, in second position in document.] + [Exactly once, in second position in document.] [No extra arguments]

The certificate is a base64-encoded Ed25519 certificate (see @@ -453,14 +453,18 @@ signed-with-ed25519-key extension (see cert-spec.txt, section 2.2.1), so that we can extract the master identity key.

+ [Before Tor 0.4.5.1-alpha, this field was optional.] + "master-key-ed25519" SP MasterKey NL

- [At most once] + [Exactly once]

Contains the base-64 encoded ed25519 master key as a single argument. If it is present, it MUST match the identity key in the identity-ed25519 entry.

+ [Before Tor 0.4.5.1-alpha, this field was optional.] + "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL

[Exactly once] @@ -535,10 +539,9 @@

"onion-key-crosscert" NL a RSA signature in PEM format.

- [At most once, required when identity-ed25519 is present] + [Exactly once] [No extra arguments]

- This element contains an RSA signature, generated using the onion-key, of the following:

@@ -558,9 +561,12 @@ had control over the secret key corresponding to the onion-key.

+ [Before Tor 0.4.5.1-alpha, this field was optional whenever + identity-ed25519 was absent.] + "ntor-onion-key" base-64-encoded-key

- [At most once] + [Exactly once]

A curve25519 public key used for the ntor circuit extended handshake. It's the standard encoding of the OR's curve25519 @@ -569,11 +575,13 @@ for at least 1 week after any new key is published in a subsequent descriptor.

+ [Before Tor 0.4.5.1-alpha, this field was optional.] + "ntor-onion-key-crosscert" SP Bit NL "-----BEGIN ED25519 CERT-----" NL certificate "-----END ED25519 CERT-----" NL

- [At most once, required when identity-ed25519 is present] + [Exactly once] [No extra arguments]

A signature created with the ntor-onion-key, using the @@ -593,6 +601,9 @@ had control over the secret key corresponding to the ntor-onion-key.

+ [Before Tor 0.4.5.1-alpha, this field was optional whenever + identity-ed25519 was absent.] + "signing-key" NL a public key in PEM format

[Exactly once] @@ -626,8 +637,7 @@

"router-sig-ed25519" SP Signature NL

- [At most once.] - [Required when identity-ed25519 is present; forbidden otherwise.] + [Exactly once.]

It MUST be the next-to-last element in the descriptor, appearing immediately before the RSA signature. It MUST contain an Ed25519 @@ -642,6 +652,9 @@ The signing key in the identity-ed25519 certificate MUST be the one used to sign the document.

+ [Before Tor 0.4.5.1-alpha, this field was optional whenever + identity-ed25519 was absent.] + "router-signature" NL Signature NL

[At end, exactly once] @@ -819,8 +832,7 @@

"proto" SP Entries NL

- [At most one.] - [Will become mandatory at some point after May 2018.] + [Exactly once.]

Entries = Entries = Entry @@ -845,8 +857,10 @@ Ranges should be represented as compactly as possible. Ints must be no more than 2^32 - 2. (Yes, 2.)

- This field was first added in Tor 0.2.9.x. Some time after all earlier - Tor relay versions are obsolete, it will become mandatory. + This field was first added in Tor 0.2.9.x. + + [Before Tor 0.4.5.1-alpha, this field was optional.] +

2.1.2. Extra-info document format

@@ -1518,13 +1532,15 @@

"ntor-onion-key" SP base-64-encoded-key NL

- [At most once] + [Exactly once]

The "ntor-onion-key" element as specified in section 2.1.1.

(Only included when generating microdescriptors for consensus-method 16 or later.)

+ [Before Tor 0.4.5.1-alpha, this field was optional.] + "a" SP address ":" port NL

[Any number] @@ -1633,10 +1649,12 @@

"pr" SP Entries NL

- [At most once.] + [Exactly once.]

The "proto" element as specified in section 2.1.1.

+ [Before Tor 0.4.5.1-alpha, this field was optional.] + (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 all they need to confirm the actual identity key when doing a TLS