Prop. 159 more sections

i2p2www/spec/proposals/159-ssu2.rst

@@ -2773,6 +2773,9 @@ Alice sends to Bob.
 Long header.
 Noise content: Alice's ephemeral key X
 Noise payload: datetime and padding blocks
+Max payload size: MTU - 108 (IPv4) or MTU - 128 (IPv6)
+For 1280 MTU: Max payload is 1172 (IPv4) or 1152 (IPv6)
+For 1500 MTU: Max payload is 1392 (IPv4) or 1372 (IPv6)
 
 (Payload Security Properties)
 
@@ -2905,8 +2908,6 @@ Unencrypted data (Poly1305 authentication tag not shown):
 
   X :: 32 bytes, X25519 ephemeral key, little endian
 
-  options :: options block, 16 bytes, see below
-
 {% endhighlight %}
 
 
@@ -3047,6 +3048,9 @@ Bob sends to Alice.
 
 Noise content: Bob's ephemeral key Y
 Noise payload: datetime, options, and padding blocks
+Max payload size: MTU - 108 (IPv4) or MTU - 128 (IPv6)
+For 1280 MTU: Max payload is 1172 (IPv4) or 1152 (IPv6)
+For 1500 MTU: Max payload is 1392 (IPv4) or 1372 (IPv6)
 
 (Payload Security Properties)
 
@@ -3293,6 +3297,9 @@ Alice sends to Bob.
 
 Noise content: Alice's static key
 Noise payload: Alice's RouterInfo, options, data, and padding blocks
+Max payload size: MTU - 105 (IPv4) or MTU - 125 (IPv6)
+For 1280 MTU: Max payload is 1175 (IPv4) or 1155 (IPv6)
+For 1500 MTU: Max payload is 1395 (IPv4) or 1375 (IPv6)
 
 (Payload Security Properties)
 
@@ -3426,11 +3433,13 @@ Notes
 - Bob must perform the usual Router Info validation.
   Ensure the signature type is supported, verify the signature,
   verify the timestamp is within bounds, and any other checks necessary.
+  See below for notes on handling fragmented Router Infos.
 
 - Bob must verify that Alice's static key received in the first frame matches
   the static key in the Router Info. Bob must first search the Router Info for
   a NTCP or SSU2 Router Address with a matching version (v) option.
   See Published Router Info and Unpublished Router Info sections below.
+  See below for notes on handling fragmented Router Infos.
 
 - If Bob has an older version of Alice's RouterInfo in his netdb, verify
   that the static key in the router info is the same in both, if present,
@@ -3454,15 +3463,14 @@ Notes
   4) Padding block (optional)
   This frame must never contain any other block type.
 
-- Message 3 part 2 padding may not be required if Alice includes one or more I2NP blocks
+- Message 3 part 2 padding block is recommended.
-  in the Session Confirmed.
-  As Alice will generally, but not always, have an I2NP message to send to Bob
-  (that's why she connected to him), this is the recommended implementation,
-  for efficiency and to ensure the effectiveness of the random padding.
 
-- Total length of both Message 3 AEAD frames (parts 1 and 2) is 65535 bytes;
+- There may be no space, or only a small amount of space, available for
-  part 1 is 48 bytes so part 2 max frame length is 65487;
+  I2NP blocks, depending on the MTU and the Router Info size.
-  part 2 max plaintext length excluding MAC is 65471.
+  Do NOT include I2NP blocks if the Router Info is fragmented.
+  The simplest implementation may be to never include I2NP blocks in
+  the Session Confirmed message, and send all I2NP blocks in
+  subsequent Data messages.
 
 
 Key Derivation Function (KDF) (for data phase)
@@ -3511,6 +3519,8 @@ Data Message (Type 6)
 ---------------------------
 
 Noise payload: All block types are allowed
+Max payload size: MTU - 57 (IPv4) or MTU - 77 (IPv6)
+For 1500 MTU: Max payload is 1443 (IPv4) or 1423 (IPv6)
 
 Starting with the 2nd part of Session Confirmed, all messages are inside
 an authenticated and encrypted ChaChaPoly payload.
@@ -3673,13 +3683,13 @@ Unencrypted data (Poly1305 authentication tag not shown):
   +----+----+----+----+----+----+----+----+
   |             Retry Token               |
   +----+----+----+----+----+----+----+----+
-  |     Noise payload (block data)        |
+  |    ChaCha20 payload (block data)      |
   +          (length varies)              +
   |                                       |
   +----+----+----+----+----+----+----+----+
 
 
-  Destination Connection ID :: Randomly generated by Alice
+  Destination Connection ID :: As received from Alice in Session Request
 
   type :: 9
 
@@ -3691,14 +3701,18 @@ Unencrypted data (Poly1305 authentication tag not shown):
 
   Packet Number :: 0 unless retransmitted or resent after Retry
 
-  Source Connection ID :: Randomly generated by Alice
+  Source Connection ID :: As received from Alice in Session Request
 
   Retry Token :: 8 byte unsigned integer, nonzero
 
-  options :: options block, 16 bytes, see below
-
 {% endhighlight %}
 
+Notes
+`````
+This is NOT a standard Noise message and is not part of the handshake.
+It is not bound to the Session Request message other than by connection IDs.
+It is not required to decrypt the Session Request Noise message to create this
+message in response.
 
 
 Hole Punch Message
@@ -3793,6 +3807,9 @@ Next Nonce                                 11           TBD
 ACK                                        12         varies 
 Partial ACK                                13         varies 
 NACK                                       14         varies 
+Relay Tag Request                          15            3      
+Relay Tag                                  16            7      
+Retry Token                                17           15      
 reserved for experimental features        255
 Padding                                   254         varies    
 reserved for future extension             255
@@ -3904,13 +3921,19 @@ Used in Session Confirmed part 2.
 Pass Alice's RouterInfo to Bob, or Bob's to Alice.
 Used optionally in the data phase.
 
+NOTE: Unlike in NTCP2, the Router Info may be fragmented.
+Session setup is not complete until all fragments are received.
+
+
 .. raw:: html
 
   {% highlight lang='dataspec' %}
 +----+----+----+----+----+----+----+----+
-  | 2  |  size   |flg |    RouterInfo     |
+  | 2  |  size   |flag|frag|              |
-  +----+----+----+----+                   +
+  +----+----+----+----+----+              +
-  | (Alice RI in handshake msg 3 part 2)  |
+  |                                       |
+  +       Router Info fragment            +
+  | (Alice RI in Sessopm Confirmed)       |
   ~ (Alice, Bob, or third-party           ~
   |  RI in data phase)                    |
   ~               .   .   .               ~
@@ -3918,11 +3941,16 @@ Used optionally in the data phase.
   +----+----+----+----+----+----+----+----+
 
   blk :: 2
-  size :: 2 bytes, big endian, size of flag + router info to follow
+  size :: 2 bytes, big endian, 2 + fragment size
-  flg :: 1 byte flags
+  flag :: 1 byte flags
-         bit order: 76543210
+         bit order: 76543210 (bit 7 is MSB)
          bit 0: 0 for local store, 1 for flood request
          bits 7-1: Unused, set to 0 for future compatibility
+  frag :: 1 byte fragment info:
+         bit order: 76543210 (bit 7 is MSB)
+         bits 7-4: fragment number 0-14, big endian
+         bits 3-0: total fragments 1-15, big endian
+
   routerinfo :: Alice's or Bob's RouterInfo
 
 
@@ -4422,6 +4450,63 @@ TODO Not required, put in ack block?
 {% endhighlight %}
 
 
+Relay Tag Request
+```````````````````````
+In the Session Request message.
+
+.. raw:: html
+
+  {% highlight lang='dataspec' %}
++----+----+----+
+  | 15 |    0    |
+  +----+----+----+
+
+  blk :: 15
+  size :: 2 bytes, big endian, value = 0
+
+{% endhighlight %}
+
+
+Relay Tag
+```````````
+In the Session Created message.
+
+.. raw:: html
+
+  {% highlight lang='dataspec' %}
++----+----+----+----+----+----+----+
+  | 16 |    4    |    relay tag      |
+  +----+----+----+----+----+----+----+
+
+  blk :: 16
+  size :: 2 bytes, big endian, value = 4
+  relay tag :: 4 bytes, big endian
+
+{% endhighlight %}
+
+
+Retry Token
+```````````````
+For a subsequent connection:
+
+.. raw:: html
+
+  {% highlight lang='dataspec' %}
++----+----+----+----+----+----+----+----+
+  | 17 |    4    |     expires       |    |
+  +----+----+----+----+----+----+----+    +
+            retry token              |
+  +----+----+----+----+----+----+----+
+
+  blk :: 17
+  size :: 2 bytes, big endian, value = 4
+  expires :: Unix timestamp, unsigned seconds.
+             Wraps around in 2106
+  retry token :: 8 bytes, big endian
+
+{% endhighlight %}
+
+
 Padding
 ```````
 This is for padding inside AEAD payloads.
@@ -4483,14 +4568,154 @@ Future work
   provides more information on the topic.
 
 
-Session Termination
+Replay Prevention
 =====================
 
-Message or block? TBD
+Both Session Request and Session Created messages must contain DateTime blocks.
+
+Both Alice and Bob validate that the time is within a valid skew (recommended +/- 2 minutes)
+and for replay prevention. Bob should reject duplicate Session Request messages
+even if the skew is valid, via a Bloom filter or other mechanism.
+
+Routers should use standard flow control and retransmission mechanisms to
+detect and drop duplicate data phase messages.
+
+
+
+Handshake Retransmission
+===========================
+
+Session Request
+----------------
+If no Session Created is received:
+
+Maintain same source and connection IDs and ephemeral key. Increment packet number.
+Re-encrypt Noise payload as AEAD (packet number) changed.
+Re-protect header, re-obfuscate header, as packet number changed.
+
+Recommended retransmission intervals: 3 and 6 seconds (3 and 9 seconds after first sent).
+Recommended timeout: 15 seconds total
+
+
+Session Created
+----------------
+If no Session Confirmed is received:
+
+Maintain same source and connection IDs and ephemeral key. Increment packet number.
+Re-encrypt Noise payload as AEAD (packet number) changed.
+Re-protect header, re-obfuscate header, as packet number changed.
+
+Recommended retransmission intervals: 3 and 6 seconds (3 and 9 seconds after first sent).
+Recommended timeout: 15 seconds total
+
+
+Session Confirmed
+------------------
+TODO there is no current mechanism for detecting or recovering from loss of Session Confirmed.
+We could use IK instead of XK, as it has only two messages in the handshake, but
+it uses an extra DH (4 instead of 3). SSU 1 has the same problem.
+
+
+Retry
+---------
+If no Session Request is received:
+
+Maintain same source and connection IDs. Increment packet number.
+Re-protect header, re-obfuscate header, as packet number changed.
+
+Recommended retransmission intervals: 3 and 6 seconds (3 and 9 seconds after first sent).
+Recommended timeout: 15 seconds total
+
+
+Total Timeout
+--------------
+Recommended total timeout for the handshake is 20 seconds.
+
+
+Retry Token
+=============
+
+The Retry Token in the Session Request header is used for DoS mitigation.
+
+If Bob does not accept the token in the Session Request message, Bob does NOT decrypt
+the message, as it requires an expensive DH operation.
+Bob simply sends a Retry message with a new token.
+
+If a subsequent Session Request message then is received with that token,
+Bob proceeds to decrypt that message and proceed with the handshake.
+
+The retry token may be a randomly-generated 8 byte value, if the generator of the token
+stores the values and associated IP and port (in-memory or persistently).
+Alternatively, the generator may generate an opaque value (for example,
+using the SipHash with a stored seed of the IP, port, and current hour or day)
+to create tokens that do not need to be saved in-memory.
+Note that this method may make it difficult to reject reused tokens.
+
+Tokens may only be used once.
+A token sent from Bob to Alice in a Retry message must be used immediately, and expires
+in a few seconds.
+A token sent in a Retry Token block in an established session
+may be used in a subsequent connection, and it
+expires at the time specified in that block.
+Expiration is specified by the sender; recommended values are
+one hour minimum, several hours or days maximum.
+A router should delete all its saved tokens if its IP, router hash, or keys change.
+Tokens may optionally be persisted across router restarts, implementation dependent.
+Acceptance of an unexpired token is not guaranteed; if Bob has forgotten or deleted
+his saved tokens, he will send a Retry to Alice.
+
+Retry Token blocks may be sent from Alice to Bob or Bob to Alice.
+They would typically be sent once, soon after session establishment.
+The token may be resent before or after expiration with a new expiration time,
+or a new token may be sent.
+
+A token is bound to the combination of source IP/port, destination IP/port,
+static keys, and router hashes. A token received on IPv4 may not be used
+for IPv6 or vice versa.
+
+
+
+
+
+Router Info Fragmentation
+===========================
+
+SSU 1 contains a mechanism for Router Identity fragmentation in the Session Confirmed message
+but it is unused, as the Router Identity is only 391 bytes
+(387 for old DSA-SHA1 routers) and so fragmentation was never required.
+The full Router Info was sent in a subsequent I2NP database store message in the data phase
+and was fragmented as necessary.
+
+In SSU2, the full Router Info is sent in the Session Confirmed message
+(as in NTCP2), and validation of the signature
+(and matching the static key in the Router Identity to that received in the Noise handshake)
+is a vital part of the handshake.
+
+Median Router Info sizes in the network are about 800 bytes, with a maximum size
+of about 2000 bytes (uncompressed) or 1300 bytes (compressed).
+Maximum Router Info sizes are expected to increase in the future,
+due to additional Router Addresses.
+If both SSU and SSU2 addresses are supported, or if multiple addresses for
+different IPv4 or IPv6 IPs are supported (currently supported by i2pd but not Java i2p)
+the sizes could increase significantly.
+
+While a typical MTU and Router Info size would allow the Router Info to be sent
+unfragmented, fragmentation will be necessary and this protocol must support it.
+The Router Info block contains a fragmentation field (unlike in NTCP2 where it is not required).
+
+If fragmentation is required, the first fragment is sent in the Session Confirmed message,
+and subsequent fragments are sent in Data messages.
+However, the session must be considered as in a pending state until all Router Info
+fragments are received by Bob.
+
+Alice must NOT send any I2NP blocks before all Router Info blocks are sent.
+Alice MAY send I2NP blocks in the same message as the last RouterInfo fragment.
+Bob MUST either queue or discard any I2NP blocks received from Alice before all Router Info blocks
+are received and the signature and static key are validated.
+Bob must NOT send any I2NP blocks to Alice before all Router Info blocks
+are received and the signature and static key are validated.
+
 
-Upon any normal or abnormal termination, routers should
-zero-out any in-memory ephemeral data, including handshake ephemeral keys,
-symmetric crypto keys, and related information.
 
 
 I2NP Message Fragmentation
@@ -4502,6 +4727,7 @@ Differences from SSU 1
 
 
 
+
 Congestion Control
 ====================
 
@@ -4509,23 +4735,160 @@ Sequence numbers, acks, backoff, retransmission
 
 
 
+Session Termination
+=====================
+
+Message or block? TBD
+
+Upon any normal or abnormal termination, routers should
+zero-out any in-memory ephemeral data, including handshake ephemeral keys,
+symmetric crypto keys, and related information.
+
+
+MTU
+========
+
+Requirements vary, based on whether the published address is shared with SSU 1.
+Current SSU 1 IPv4 minimum is 620, which is probably too small.
+
+SSU Address
+------------
+Shared address with SSU 1, must follow SSU 1 rules.
+IPv4: Default and max is 1484. Min is 620.
+(IPv4 MTU + 4) must be a multiple of 16.
+IPv6: Must be published, min is 1280 and the max is 1488.
+IPv6 MTU must be a multiple of 16.
+
+SSU2 Address
+------------
+Must follow SSU 1 rules.
+IPv4: Default and max is 1500. Min is TBD.
+IPv6: Default and max is 1500. Min is 1280.
+No multiple of 16 rules, but should probably be a multiple of 2 at least.
+
+PMTU Discovery
+---------------
+For SSU 1, current Java I2P performs PMTU discovery by starting with small packets and
+gradually increasing the size, or increasing based on received packet size.
+This is crude and greatly reduces the efficiency.
+Continuing this feature in SSU 2 is TBD.
+
+Recent studies [PMTU]_ suggest that a minimum for IPv4 of 1200 or more would work
+for more than 99% of connections. QUIC [RFC9000]_ requires a minimum IP
+packet size of 1280 bytes.
+
+quote [RFC9000]_:
+
+The maximum datagram size is defined as the largest size of UDP
+payload that can be sent across a network path using a single UDP
+datagram.  QUIC MUST NOT be used if the network path cannot support a
+maximum datagram size of at least 1200 bytes.
+
+QUIC assumes a minimum IP packet size of at least 1280 bytes.  This
+is the IPv6 minimum size [IPv6] and is also supported by most modern
+IPv4 networks.  Assuming the minimum IP header size of 40 bytes for
+IPv6 and 20 bytes for IPv4 and a UDP header size of 8 bytes, this
+results in a maximum datagram size of 1232 bytes for IPv6 and 1252
+bytes for IPv4.  Thus, modern IPv4 and all IPv6 network paths are
+expected to be able to support QUIC.
+
+Note: This requirement to support a UDP payload of 1200 bytes
+limits the space available for IPv6 extension headers to 32
+bytes or IPv4 options to 52 bytes if the path only supports the
+IPv6 minimum MTU of 1280 bytes.  This affects Initial packets
+and path validation.
+
+end quote
+
+
+Handshake Min Size
+-------------------------
+
+QUIC requires that Initial datagrams in both directions be at least 1200 bytes,
+to prevent amplification attacks. and ensure the PMTU supports it.
+
+We could require this for Session Request and Session Created,
+at substantial cost in bandwidth.
+Perhaps we could do this only if we don't have a retry token,
+or after a Retry message is received.
+
+
+Max Message Size
+------------------
+
+IPv4:
+No IP fragmentation is assumed.
+IP + datagram header is 28 bytes.
+This assumes no IPv4 options.
+Max message size is MTU - 28.
+Data phase header is 13 bytes and MAC is 16 bytes, totalling 29 bytes.
+Payload size is MTU - 57.
+Max data phase payload is 1443 for a max 1500 MTU.
+Max data phase payload is 1223 for a min 1280 MTU.
+
+
+IPv6:
+No IP fragmentation is allowed.
+IP + datagram header is 48 bytes.
+This assumes no IPv6 extension headers.
+Max message size is MTU - 48.
+Data phase header is 13 bytes and MAC is 16 bytes, totalling 29 bytes.
+Payload size is MTU - 77.
+Max data phase payload is 1423 for a max 1500 MTU.
+Max data phase payload is 1203 for a min 1280 MTU.
 
 
 
 Published Router Info
 =====================
 
+Address Properties
+-------------------
+
+The following address properties may be publiished, unchanged from SSU 1:
+
+- caps: [B,C,4,6] capabilities
+
+- host: IP (IPv4 or IPv6).
+  Shortened IPv6 address (with "::") is allowed.
+  May or may not be present if firewalled.
+  Host names are not allowed.
+
+- iexp[0-2]: Expiration of this introducer.
+  ASCII digits, in seconds since the epoch.
+  Only present if firewalled, and introducers are required.
+  Optional (even if other properties for this introducer are present).
+
+- ihost[0-2]: Introducer's IP (IPv4 or IPv6).
+  Shortened IPv6 address (with "::") is allowed.
+  Only present if firewalled, and introducers are required.
+  Host names are not allowed.
+
+- ikey[0-2]: Introducer's Base 64 introduction key.
+  Only present if firewalled, and introducers are required.
+
+- iport[0-2]: Introducer's port 1024 - 65535.
+  Only present if firewalled, and introducers are required.
+
+- itag[0-2]: Introducer's tag 1 - (2**32 - 1)
+  ASCII digits.
+  Only present if firewalled, and introducers are required.
+
+- key: Base 64 introduction key.
+
+- mtu: Optional. See MTU section above.
+
+- port: 1024 - 65535
+  May or may not be present if firewalled.
+
+
 
 Published Addresses
 -------------------
 
-
 The published RouterAddress (part of the RouterInfo) will have a
 protocol identifier of either "SSU" or "SSU2".
 
-The RouterAddress will generally contain "host" and "port" options, as in
-the current SSU protocol, if the router expects inbound connections.
-
 The RouterAddress must contain three options
 to indicate SSU2 support:
 
@@ -4602,6 +4965,8 @@ Alice may also simply add the "s" and "v" options to an existing published "SSU"
 Public Key and IV Rotation
 --------------------------
 
+Using the same static keys for NTCP2 and SSU2 is allowed, but not recommended.
+
 Due to caching of RouterInfos, routers must not rotate the static public key or IV
 while the router is up, whether in a published address or not. Routers must
 persistently store this key and IV for reuse after an immediate restart, so incoming
@@ -4738,6 +5103,42 @@ TBD
 
 
 
+Packet Overhead Analysis
+=========================
+
+Assumes IPv4, not including extra padding, not including IP and UDP header sizes.
+Padding is mod-16 padding for SSU 1 only.
+
+SSU 1
+
+Message              Header+MAC    Keys    Data    Padding  Total   Notes
+==================   ===========   =====   ======  =======  ======  =====
+Session Request      40            256        5      3       304    Incl. extended options
+Session Created      37            256       79      1       336    Incl. 64 byte Ed25519 sig
+Session Confirmed    37                     462     13       512    Incl. 391 byte ident and 64 byte sig
+Data (RI)            37                    1014             1051    Incl. 5 byte I2NP header, 1000 byte RI
+Data (1 full msg)    37                      14               51    Incl. 5 byte I2NP header
+==================   ===========   =====   ======  =======  ======  =====
+Total                                                       2254
+==================   ===========   =====   ======  =======  ======  =====
+
+
+SSU 2
+
+Message              Header+MAC    Keys    Data    Padding  Total   Notes
+==================   ===========   =====   ======  =======  ======  =====
+Session Request      48             32        7               87    DateTime block
+Session Created      48             32        7               87    DateTime block
+Session Confirmed    45             32     1003             1080    RI block
+Data (1 full msg)    13                      14               27     
+==================   ===========   =====   ======  =======  ======  =====
+Total                                                       1281
+==================   ===========   =====   ======  =======  ======  =====
+
+
+
+
+
 
 
 References
@@ -4761,6 +5162,9 @@ References
 .. [NTCP2]
     {{ site_url('docs/spec/ntcp2', True) }}
 
+.. [PMTU]
+    https://aura.abdn.ac.uk/bitstream/handle/2164/11693/tma2018_paper57.pdf
+
 .. [Prop104]
     {{ proposal_url('104') }}