[tor-commits] [torspec/master] Document newly required fields from prop315.

[asn at torproject.org]

commit 1040c2d0fc972d2659391ddee1e36dff49ad498f
Author: Nick Mathewson <nickm at 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