[tor-commits] [torspec/main] ntor3, rend3: clarify extension field defaults.

[nickm at torproject.org]

commit 176c9001f962848751bedfff9bade4aa58319714
Author: Nick Mathewson <nickm at torproject.org>
Date:   Thu Feb 17 10:53:20 2022 -0500

    ntor3, rend3: clarify extension field defaults.
    
    These patch changes describe new default behaviors for extension
    field lists, as appear in ntor3 and in many places throughout the
    ntor3 protocol.  In general:
    
    * Unrecognized extensions MUST be ignored.
    
    Additionally, all the following rules apply _unless otherwise stated
    in the documentation for an extension.
    
    * Extensions are sent in sorted order.
    * Extensions should only be sent once in a message
    * If you receive multiple copies of an extension, only the first
      one counts.
    
    This comes out of discussions on tor!525.
---
 proposals/332-ntor-v3-with-extra-data.md | 28 ++++++++++++++++++----------
 rend-spec-v3.txt                         | 26 +++++++++++++++++++++++++-
 2 files changed, 43 insertions(+), 11 deletions(-)

diff --git a/proposals/332-ntor-v3-with-extra-data.md b/proposals/332-ntor-v3-with-extra-data.md
index 4e55713..8e6dedc 100644
--- a/proposals/332-ntor-v3-with-extra-data.md
+++ b/proposals/332-ntor-v3-with-extra-data.md
@@ -338,20 +338,28 @@ We use the following meta-encoding for the contents of client and
 server messages.
 
     [Any number of times]:
-       TYPE     [one byte]
-       LEN      [one byte]
-       BODY     [LEN bytes]
-
-We do not specify specific TYPE semantics here; we leave those for
-other proposals.
+    EXTENSION
+       EXT_FIELD_TYPE     [one byte]
+       EXT_FIELD_LEN      [one byte]
+       EXT_FIELD          [EXT_FIELD_LEN bytes]
 
 All parties MUST reject messages that are not well-formed per the
 rules above.
 
-To avoid partitioning, clients MUST reject messages with TYPEs that
-they do not recognize.  (Therefore, whenever we specify a new server
-message TYPE, we must say that it can only be included if the client
-signals that it understands it.)
+We do not specify specific TYPE semantics here; we leave those for
+other proposals and specifications.
+
+Parties MUST ignore extensions with `EXT_FIELD_TYPE` bodies they do not
+recognize.
+
+Unless otherwise specified in the documentation for an extension type:
+* Each extension type SHOULD be sent only once in a message.
+* Parties MUST ignore any occurrences all occurrences of an extension
+  with a given type after the first such occurrence.
+* Extensions SHOULD be sent in numerically ascending order by type.
+
+(The above extension sorting and multiplicity rules are only defaults;
+they may be overridden in the description of individual extensions.)
 
 # A.3 How much space is available?
 
diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt
index 6a120eb..1a0b945 100644
--- a/rend-spec-v3.txt
+++ b/rend-spec-v3.txt
@@ -1548,9 +1548,17 @@ Table of contents:
    authentication key.
 
    The EXT_FIELD_TYPE, EXT_FIELD_LEN, EXT_FIELD entries are reserved for
-   future extensions to the introduction protocol. Extensions with
+   extensions to the introduction protocol. Extensions with
    unrecognized EXT_FIELD_TYPE values must be ignored.
 
+   Unless otherwise specified in the documentation for an extension type:
+      * Each extension type SHOULD be sent only once in a message.
+      * Parties MUST ignore any occurrences all occurrences of an extension
+        with a given type after the first such occurrence.
+      * Extensions SHOULD be sent in numerically ascending order by type.
+   (The above extension sorting and multiplicity rules are only defaults;
+   they may be overridden in the descriptions of individual extensions.)
+
    The HANDSHAKE_AUTH field contains the MAC of all earlier fields in
    the cell using as its key the shared per-circuit material ("KH")
    generated during the circuit extension protocol; see tor-spec.txt
@@ -1685,6 +1693,10 @@ Table of contents:
    Older versions of Tor send back an empty INTRO_ESTABLISHED cell instead.
    Services must accept an empty INTRO_ESTABLISHED cell from a legacy relay.
 
+   The same rules for multiplicity, ordering, and handling unknown types
+   apply to the extension fields here as described [EST_INTRO] above.
+
+
 3.2. Sending an INTRODUCE1 cell to the introduction point. [SEND_INTRO1]
 
    In order to participate in the introduction protocol, a client must
@@ -1737,6 +1749,10 @@ Table of contents:
    INTRODUCE2 cell with exactly the same contents to the service, and sends an
    INTRODUCE_ACK response to the client.
 
+   The same rules for multiplicity, ordering, and handling unknown types
+   apply to the extension fields here as described [EST_INTRO] above.
+
+
 3.2.2. INTRODUCE_ACK cell format. [INTRO_ACK]
 
    An INTRODUCE_ACK cell has the following fields:
@@ -1755,6 +1771,10 @@ Table of contents:
      [00 02] -- Bad message format
      [00 03] -- Can't relay cell to service
 
+   The same rules for multiplicity, ordering, and handling unknown types
+   apply to the extension fields here as described [EST_INTRO] above.
+
+
 3.3. Processing an INTRODUCE2 cell at the hidden service. [PROCESS_INTRO2]
 
    Upon receiving an INTRODUCE2 cell, the hidden service host checks whether
@@ -1831,6 +1851,10 @@ Table of contents:
        shared key with the hidden service client.
      * A set of shared keys to use for end-to-end encryption.
 
+   The same rules for multiplicity, ordering, and handling unknown types
+   apply to the extension fields here as described [EST_INTRO] above.
+
+
 3.3.1. Introduction handshake encryption requirements [INTRO-HANDSHAKE-REQS]
 
    When decoding the encrypted information in an INTRODUCE2 cell, a