commit 37def4e5024eda2f067c650f1b8421679fa532e1 Author: Nick Mathewson <nickm@torproject.org> Date: Tue Jan 12 09:33:57 2016 -0500 Document which descriptor items aren't allowed to take extra args Closes #16227 --- dir-spec.txt | 32 ++++++++++++++++++++++++++++++++ rend-spec.txt | 15 ++++++++++++++- 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/dir-spec.txt b/dir-spec.txt index 1030c72..66b3421 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -253,6 +253,21 @@ "Once or more": These items MUST occur at least once in any instance of the document type, and MAY occur more. + For forward compatibility, each item MUST allow extra arguments at the + end of the line unless otherwise noted. So if an item's description below + is given as: + "thing" int int int NL + then implementations SHOULD accept this string as well: + "thing 5 9 11 13 16 12" NL + but not this string: + "thing 5" NL + and not this string: + "thing 5 10 thing" NL + . + + Whenever an item DOES NOT allow extra arguments, we will tag it with + "no extra arguments". + 1.3. Signing documents Every signable document below is signed in a similar manner, using a @@ -382,6 +397,7 @@ "-----END ED25519 CERT-----" NL [At most once, in second position in document.] + [No extra arguments] The certificate is a base64-encoded Ed25519 certificate (see cert-spec.txt) terminating =s removed. When this element is @@ -459,6 +475,7 @@ "onion-key" NL a public key in PEM format [Exactly once] + [No extra arguments] This key is used to encrypt CREATE cells for this OR. The key MUST be accepted for at least 1 week after any new key is published in a @@ -471,6 +488,8 @@ "onion-key-crosscert" NL a RSA signature in PEM format. [At most once, required when identity-25519 is present] + [No extra arguments] + This element contains an RSA signature, generated using the onion-key, of the following: @@ -505,6 +524,7 @@ "-----END ED25519 CERT-----" NL [At most once, required when identity-25519 is present] + [No extra arguments] A signature created with the ntor-onion-key, using the certificate format documented in cert-spec.txt, with type @@ -523,6 +543,7 @@ "signing-key" NL a public key in PEM format [Exactly once] + [No extra arguments] The OR's long-term RSA identity key. It MUST be 1024 bits. @@ -571,6 +592,7 @@ "router-signature" NL Signature NL [At end, exactly once] + [No extra arguments] The "SIGNATURE" object contains a signature of the PKCS1-padded hash of the entire server descriptor, taken from the beginning of the @@ -628,6 +650,7 @@ "caches-extra-info" NL [At most once.] + [No extra arguments] Present only if this router is a directory cache that provides extra-info documents. @@ -670,6 +693,7 @@ "allow-single-hop-exits" NL [At most once.] + [No extra arguments] Present only if the router allows single-hop circuits to make exit connections. Most Tor relays do not support this: this is @@ -1097,6 +1121,7 @@ "router-signature" NL Signature NL [At end, exactly once.] + [No extra arguments] A document signature as documented in section 1.3, using the initial item "extra-info" and the final item "router-signature", @@ -1178,6 +1203,7 @@ "dir-identity-key" NL a public key in PEM format [Exactly once.] + [No extra arguments] The long-term authority identity key for this authority. This key SHOULD be at least 2048 bits long; it MUST NOT be shorter than @@ -1199,6 +1225,7 @@ "dir-signing-key" NL a key in PEM format [Exactly once.] + [No extra arguments] The directory server's public signing key. This key MUST be at least 1024 bits, and MAY be longer. @@ -1206,6 +1233,7 @@ "dir-key-crosscert" NL CrossSignature NL [Exactly once.] + [No extra arguments] CrossSignature is a signature, made using the certificate's signing key, of the digest of the PKCS1-padded hash of the certificate's @@ -1220,6 +1248,7 @@ "dir-key-certification" NL Signature NL [At end, exactly once.] + [No extra arguments] A document signature as documented in section 1.3, using the initial item "dir-key-certificate-version" and the final item @@ -1304,6 +1333,7 @@ "onion-key" NL a public key in PEM format [Exactly once, at start] + [No extra arguments] The "onion-key" element as specified in section 2.1.1. @@ -1479,6 +1509,7 @@ "consensus-method" SP Integer NL [At most once for consensuses; does not occur in votes.] + [No extra arguments] See section 3.8.1 for details. @@ -1942,6 +1973,7 @@ consensus method 9 and above with the following: "directory-footer" NL + [No extra arguments] It contains two subsections, a bandwidths-weights line and a directory-signature. (Prior to conensus method 9, footers only contained diff --git a/rend-spec.txt b/rend-spec.txt index 33a9895..6442ecb 100644 --- a/rend-spec.txt +++ b/rend-spec.txt @@ -223,6 +223,7 @@ "rendezvous-service-descriptor" SP descriptor-id NL [At start, exactly once] + [No extra arguments] Indicates the beginning of the descriptor. "descriptor-id" is a periodically changing identifier of 160 bits formatted as 32 base32 @@ -267,7 +268,7 @@ "descriptor-cookie" is an optional secret password of 128 bits that is shared between the hidden service provider and its clients. If the descriptor-cookie is left out, the input to the hash function is 128 - bits shorter. + bits shorter. [No extra arguments] "replica" denotes the number of the replica. A service publishes multiple descriptors with different descriptor IDs in order to @@ -276,6 +277,7 @@ "version" SP version-number NL [Exactly once] + [No extra arguments] The version number of this descriptor's format. Version numbers are a positive integer. @@ -283,6 +285,7 @@ "permanent-key" NL a public key in PEM format [Exactly once] + [No extra arguments] The public key of the hidden service which is required to verify the "descriptor-id" and the "signature". @@ -290,6 +293,7 @@ "secret-id-part" SP secret-id-part NL [Exactly once] + [No extra arguments] The result of the following operation as explained above, formatted as 32 base32 chars. Using this secret id part, everyone can verify that @@ -307,6 +311,7 @@ "protocol-versions" SP version-string NL [Exactly once] + [No extra arguments] A comma-separated list of recognized and permitted version numbers for use in INTRODUCE cells; these versions are described in section @@ -315,6 +320,7 @@ "introduction-points" NL encrypted-string [At most once] + [No extra arguments] A list of introduction points. If the optional "descriptor-cookie" is used, this list is encrypted with AES in CTR mode with a random @@ -332,6 +338,7 @@ "introduction-point" SP identifier NL [At start, exactly once] + [No extra arguments] The identifier of this introduction point: the base32 encoded hash of this introduction point's identity key. @@ -339,12 +346,14 @@ "ip-address" SP ip4 NL [Exactly once] + [No extra arguments] The IP address of this introduction point. "onion-port" SP port NL [Exactly once] + [No extra arguments] The TCP port on which the introduction point is listening for incoming onion requests. @@ -352,6 +361,7 @@ "onion-key" NL a public key in PEM format [Exactly once] + [No extra arguments] The public key that can be used to encrypt messages to this introduction point. @@ -359,6 +369,7 @@ "service-key" NL a public key in PEM format [Exactly once] + [No extra arguments] The public key that can be used to encrypt messages to the hidden service. @@ -383,6 +394,7 @@ "signature" NL signature-string [At end, exactly once] + [No extra arguments] A signature of all fields above with the private key of the hidden service. @@ -994,6 +1006,7 @@ and stores the following data: "client-key" NL a public key in PEM format + [No extra arguments] 2.4. Client configuration