diff --git a/i2p2www/spec/proposals/159-ssu2.rst b/i2p2www/spec/proposals/159-ssu2.rst index 3b17ac30..a19efe04 100644 --- a/i2p2www/spec/proposals/159-ssu2.rst +++ b/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 - 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. +- Message 3 part 2 padding block is recommended. -- Total length of both Message 3 AEAD frames (parts 1 and 2) is 65535 bytes; - part 1 is 48 bytes so part 2 max frame length is 65487; - part 2 max plaintext length excluding MAC is 65471. +- There may be no space, or only a small amount of space, available for + I2NP blocks, depending on the MTU and the Router Info size. + 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 | - +----+----+----+----+ + - | (Alice RI in handshake msg 3 part 2) | + | 2 | size |flag|frag| | + +----+----+----+----+----+ + + | | + + 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 - flg :: 1 byte flags - bit order: 76543210 + size :: 2 bytes, big endian, 2 + fragment size + flag :: 1 byte flags + 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') }}