From 12bc1d9df0d86490549cea35b1f0a540c3930c85 Mon Sep 17 00:00:00 2001 From: zzz Date: Sun, 12 Sep 2021 13:50:52 -0400 Subject: [PATCH] SSU2 proposal 159 outline --- i2p2www/spec/proposals/159-ssu2.rst | 4034 +++++++++++++++++++++++++++ 1 file changed, 4034 insertions(+) create mode 100644 i2p2www/spec/proposals/159-ssu2.rst diff --git a/i2p2www/spec/proposals/159-ssu2.rst b/i2p2www/spec/proposals/159-ssu2.rst new file mode 100644 index 00000000..4d5cd492 --- /dev/null +++ b/i2p2www/spec/proposals/159-ssu2.rst @@ -0,0 +1,4034 @@ +====== +SSU2 +====== +.. meta:: + :author: orignal, zlatinb, zzz + :created: 2021-09-12 + :thread: http://zzz.i2p/topics/2612 + :lastupdated: 2021-09-12 + :status: Open + :target: 0.9.55 + +.. contents:: + + + +Overview +======== + +This proposal describes an authenticated key agreement protocol to improve the +resistance of [SSU]_ to various forms of automated identification and attacks. + +The proposal is organized as follows: the security goals are presented, +followed by a discussion of the basic protocol. Next, a complete specification +of all protocol messages is given. Finally, router addresses and version +identification are discussed. An appendix discussing a generic attack on common +padding schemes is also included, as well as an appendix containing a number of +candidates for the authenticated cipher. + +As with other I2P transports, SSU2 is defined solely +for point-to-point (router-to-router) transport of I2NP messages. +It is not a general-purpose data pipe. + + +Motivation +========== + +SSU is the only remaining protocol layer that requires ElGamal, which is very slow. +The flow control for SSU is complex and does not work well. +Portions of SSU are vulnerable to address spoofing attacks. +The handshake does not use Noise. + + + +Design Goals +============ + +- Reduce CPU usage by eliminating ElGamal. Use X25519 for the DH. + +- Maintain the Peer Test and Relay functions, and increase security for them. + +- Make implementation easier by allowing for standard flow control + algorithms. + +- Increase speed and reduce latency. + +- Make packet identification easier, to reduce reliance on fallbacks and + heuristics that make the code overly complex. + +- (maybe) Support SSU 1 and 2 on a single port, auto-detect, and published as a single + "transport" (i.e. [RouterAddress]_) in the [NetDB]_. + +- Publish support for version 1 only, 2 only, or 1+2 in the NetDB in a separate + field, and default to version 1 only (don't bind version support to a + particular router version) + +- Ensure that all implementations (Java/i2pd/Go) can add version 2 + support (or not) on their own schedules + +- Add random padding to all SSU messages including handshake and data messages. + Provide options mechanism for both sides to request min and max padding + and/or padding distribution. Specifics of the padding distribution are + implementation-dependent and may or may not be specified in the protocol + itself. + +- Obfuscate the contents of messages that aren't encrypted (Session Created and Confirmed), + sufficiently so that DPI boxes and AV signatures can't easily classify them. + Also ensure that the messages going to a single peer or set of peers do not + have a similar pattern of bits. + +- Fix loss of bits in DH due to Java format [Ticket1112]_, possibly (probably?) + by switching to X25519. + +- Switch to a real key derivation function (KDF) rather than using the DH + result as-is + +- Add "probing resistance" (as Tor calls it); this includes replay resistance. + +- Maintain 2-way authenticated key exchange (2W-AKE). 1W-AKE is not sufficient + for our application. + +- Continue to use the variable-type, variable-length signatures (from the + published [RouterIdentity]_ signing key) as a part of authentication. Rely + on a static public key published in the RouterInfo as another part of + authentication. + +- Add options/version in handshake for future extensibility. + +- Add resistance to malicious MitM TCP segmentation if possible. + +- Don't add significantly to CPU required for connection setup; if possible, + reduce it significantly. + +- Add message authentication (MAC) using ChaCha/Poly1305. + +- Use a 3-message, one-round-trip handshake, as in [SSU]_. + +- Minimize protocol overhead before padding. While padding will be added, + overhead before padding is still overhead. + Low-bandwidth nodes must be able to use SSU2. + +- All padding must be covered by the MAC, unlike the end-of-packet padding in SSU. + +- Maintain timestamps for replay and skew detection. + +- Avoid any year 2038 issues in timestamps, must work until at least 2106. + +- Maintain a max I2NP message size of approximately 32K, as in SSU. + Increase to 64 KB? TBD + +- Include representatives of Java, C++, and Go router developers in the design. + + + +Non-Goals +--------- + +- Bullet-proof DPI resistance... that would be pluggable transports, + [Prop109]_. + +- A TLS-based (or HTTPS-lookalike) transport... that would be [Prop104]_. + +- It's OK to change the symmetric stream cryptography. + +- Timing-based DPI resistance (inter-message timing/delays can be + implementation-dependent; intra-message delays can be introduced at any + point, including before sending the random padding, for example). Artificial + delays (what obfs4 calls IAT or inter-arrival time) are independent of the + protocol itself. + +- Deniability of participating in a session (there's signatures in there). + +Non-goals that may be partially reconsidered or discussed: + +- The degree of protection against Deep Packet Inspection (DPI) + +- Post-Quantum (PQ) security + +- Deniability + + + +Security Goals +============== + +We consider three parties: + +- Alice, who wishes to establish a new session. +- Bob, with whom Alice wishes to establish a session. +- Mallory, the "man in the middle" between Alice and Bob. + +At most two participants can engage in active attacks. + +Alice and Bob are both in possession of a static key pair, which is contained +in their [RouterIdentity]_. + +The proposed protocol attempts to allow Alice and Bob to agree on a shared +secret key (K) under the following requirements: + +1) Private key security: neither Bob nor Mallory learns anything about Alice's + static private key. Symmetrically, Alice does not learn anything about Bob's + static private key. + +2) The session key K is only known by Alice and Bob. + +3) Perfect forward secrecy: the agreed upon session key remains secret in the + future, even when the static private keys of Alice and/or Bob are revealed + after the key has been agreed upon. + +4) Two-way authentication: Alice is certain that she has established a session + with Bob, and vice versa. + +5) Protection against online DPI: Ensure that it is not trivial to detect that + Alice and Bob are engaged in the protocol using only straightforward deep + packet inspection (DPI) techniques. See below. + +6) Limited deniability: neither Alice nor Bob can deny participation in the + protocol, but if either leaks the shared key the other party can deny the + authenticity of the contents of the transmitted data. + +The present proposal attempts to provide all five requirements based on the +Station-To-Station (STS) protocol [STS]_. Note that this protocol is also the +basis for the [SSU]_ protocol. + + +Additional DPI Discussion +------------------------- + +We assume two DPI components: + +1) Online DPI +````````````` + +Online DPI inspecting all flows in real-time. Connections may be blocked or +otherwise tampered with. Connection data or metadata may be identified and +stored for offline analysis. The online DPI does not have access to the I2P +network database. The online DPI has only limited real-time computational +capability, including length calculation, field inspection, and simple +calculations such as XOR. The online DPI does have the capability of fast +real-time cryptographic functions such as AES, AEAD, and hashing, but these +would be too expensive to apply to most or all flows. Any application of these +cryptographic operations would apply only to flows on IP/Port combinations +previously identified by offline analysis. The online DPI does not have the +capability of high-overhead cryptographic functions such as DH or elligator2. +The online DPI is not designed specifically to detect I2P, although it may have +limited classification rules for that purpose. + +It is a goal to prevent protocol identification by an online DPI. + +The notion of online or "straightforward" DPI is here taken to include the +following adversary capabilities: + +1) The ability to inspect all data sent or received by the target. + +2) The ability to perform operations on the observed data, such as + applying block ciphers or hash functions. + +3) The ability to store and compare with previously sent messages. + +4) The ability to modify, delay or fragment packets. + +However, the online DPI is assumed to have the following restrictions: + +5) The inability to map IP addresses to router hashes. While this is trivial + with real-time access to the network database, + it would require a DPI system specifically designed to target I2P. + +6) The inability to use timing information to detect the protocol. + +7) Generally speaking, the online DPI toolbox does not contain any built-in + tools that are specifically designed for I2P detection. This includes + creating "honeypots", which would for example include nonrandom padding in + their messages. Note that this does not exclude machine learning systems or + highly configurable DPI tools as long as they meet the other requirements. + +To counter payload analysis, it is ensured that all messages are +indistinguishable from random. This also requires their length to be random, +which is more complicated than just adding random padding. In fact, in Appendix +A, the authors argue that a naive (i.e. uniform) padding scheme does not +resolve the problem. Appendix A therefore proposes to include either random +delays or to develop an alternate padding scheme that can provide reasonable +protection for the proposed attack. + +To protect against the sixth entry above, implementations should include random +delays in the protocol. Such techniques are not covered by this proposal, but +they could also resolve the padding length issues. In summary, the proposal +provides good protection against payload analysis (when the considerations in +Appendix A are taken into account), but only limited protection against flow +analysis. + + +2) Offline DPI +`````````````` + +Offline DPI inspecting data stored by the online DPI for later analysis. +The offline DPI may be designed specifically to detect I2P. +The offline DPI does have real-time access to the I2P network database. +The offline DPI does have access to this and other I2P specifications. +The offline DPI has unlimited computational capability, including +all cryptographic functions defined in this specification. + +The offline DPI does not have the ability to block existing connections. The +offline DPI does have the capability to do near-realtime (within minutes of +setup) sending to host/port of parties, for example TCP RST. The offline DPI +does have the capability to do near-realtime (within minutes of setup) replay +of previous messages (modified or not) for "probing" or other reasons. + +It is not a goal to prevent protocol identification by an offline DPI. +All decoding of obfuscated data in the first two messages, which +is implemented by I2P routers, may also be implemented by the offline DPI. + +It is a goal to reject attempted connections using replay of previous messages. + + +Future work +``````````` + +TBD + + + + +Address Validation +--------------------------- + +Following is copied from QUIC [RFC-9000]_. + +Address validation ensures that an endpoint cannot be used for a +traffic amplification attack. In such an attack, a packet is sent to +a server with spoofed source address information that identifies a +victim. If a server generates more or larger packets in response to +that packet, the attacker can use the server to send more data toward +the victim than it would be able to send on its own. + +The primary defense against amplification attacks is verifying that a +peer is able to receive packets at the transport address that it +claims. Therefore, after receiving packets from an address that is +not yet validated, an endpoint MUST limit the amount of data it sends +to the unvalidated address to three times the amount of data received +from that address. This limit on the size of responses is known as +the anti-amplification limit. + +Address validation is performed both during connection establishment +(see Section 8.1) and during connection migration (see Section 8.2). + +Address Validation during Connection Establishment +``````````````````````````````````````````````````````` + +Connection establishment implicitly provides address validation for +both endpoints. In particular, receipt of a packet protected with +Handshake keys confirms that the peer successfully processed an +Initial packet. Once an endpoint has successfully processed a +Handshake packet from the peer, it can consider the peer address to +have been validated. + +Additionally, an endpoint MAY consider the peer address validated if +the peer uses a connection ID chosen by the endpoint and the +connection ID contains at least 64 bits of entropy. + +For the client, the value of the Destination Connection ID field in +its first Initial packet allows it to validate the server address as +a part of successfully processing any packet. Initial packets from +the server are protected with keys that are derived from this value +(see Section 5.2 of [QUIC-TLS]). Alternatively, the value is echoed +by the server in Version Negotiation packets (Section 6) or included +in the Integrity Tag in Retry packets (Section 5.8 of [QUIC-TLS]). + +Prior to validating the client address, servers MUST NOT send more +than three times as many bytes as the number of bytes they have +received. This limits the magnitude of any amplification attack that +can be mounted using spoofed source addresses. For the purposes of +avoiding amplification prior to address validation, servers MUST +count all of the payload bytes received in datagrams that are +uniquely attributed to a single connection. This includes datagrams +that contain packets that are successfully processed and datagrams +that contain packets that are all discarded. + +Clients MUST ensure that UDP datagrams containing Initial packets +have UDP payloads of at least 1200 bytes, adding PADDING frames as +necessary. A client that sends padded datagrams allows the server to +send more data prior to completing address validation. + +Loss of an Initial or Handshake packet from the server can cause a +deadlock if the client does not send additional Initial or Handshake +packets. A deadlock could occur when the server reaches its anti- +amplification limit and the client has received acknowledgments for +all the data it has sent. In this case, when the client has no +reason to send additional packets, the server will be unable to send +more data because it has not validated the client's address. To +prevent this deadlock, clients MUST send a packet on a Probe Timeout +(PTO); see Section 6.2 of [QUIC-RECOVERY]. Specifically, the client +MUST send an Initial packet in a UDP datagram that contains at least +1200 bytes if it does not have Handshake keys, and otherwise send a +Handshake packet. + +A server might wish to validate the client address before starting +the cryptographic handshake. QUIC uses a token in the Initial packet +to provide address validation prior to completing the handshake. +This token is delivered to the client during connection establishment +with a Retry packet (see Section 8.1.2) or in a previous connection +using the NEW_TOKEN frame (see Section 8.1.3). + +In addition to sending limits imposed prior to address validation, +servers are also constrained in what they can send by the limits set +by the congestion controller. Clients are only constrained by the +congestion controller. + +Token Construction +``````````````````````````````````````````````````````` + +A token sent in a NEW_TOKEN frame or a Retry packet MUST be +constructed in a way that allows the server to identify how it was +provided to a client. These tokens are carried in the same field but +require different handling from servers. + +Address Validation Using Retry Packets +``````````````````````````````````````````````````````` + +Upon receiving the client's Initial packet, the server can request +address validation by sending a Retry packet (Section 17.2.5) +containing a token. This token MUST be repeated by the client in all +Initial packets it sends for that connection after it receives the +Retry packet. + +In response to processing an Initial packet containing a token that +was provided in a Retry packet, a server cannot send another Retry +packet; it can only refuse the connection or permit it to proceed. + +As long as it is not possible for an attacker to generate a valid +token for its own address (see Section 8.1.4) and the client is able +to return that token, it proves to the server that it received the +token. + +A server can also use a Retry packet to defer the state and +processing costs of connection establishment. Requiring the server +to provide a different connection ID, along with the +original_destination_connection_id transport parameter defined in +Section 18.2, forces the server to demonstrate that it, or an entity +it cooperates with, received the original Initial packet from the +client. Providing a different connection ID also grants a server +some control over how subsequent packets are routed. This can be +used to direct connections to a different server instance. + +If a server receives a client Initial that contains an invalid Retry +token but is otherwise valid, it knows the client will not accept +another Retry token. The server can discard such a packet and allow +the client to time out to detect handshake failure, but that could +impose a significant latency penalty on the client. Instead, the +server SHOULD immediately close (Section 10.2) the connection with an +INVALID_TOKEN error. Note that a server has not established any +state for the connection at this point and so does not enter the +closing period. + +A flow showing the use of a Retry packet is shown in Figure 9. + +.. raw:: html + + {% highlight %} +Client Server + + Initial[0]: CRYPTO[CH] -> + + <- Retry+Token + + Initial+Token[1]: CRYPTO[CH] -> + + Initial[0]: CRYPTO[SH] ACK[1] + Handshake[0]: CRYPTO[EE, CERT, CV, FIN] + <- 1-RTT[0]: STREAM[1, "..."] + + Figure 9: Example Handshake with Retry +{% endhighlight %} + + + +Address Validation for Future Connections +``````````````````````````````````````````````````````` + +A server MAY provide clients with an address validation token during +one connection that can be used on a subsequent connection. Address +validation is especially important with 0-RTT because a server +potentially sends a significant amount of data to a client in +response to 0-RTT data. + +The server uses the NEW_TOKEN frame (Section 19.7) to provide the +client with an address validation token that can be used to validate +future connections. In a future connection, the client includes this +token in Initial packets to provide address validation. The client +MUST include the token in all Initial packets it sends, unless a +Retry replaces the token with a newer one. The client MUST NOT use +the token provided in a Retry for future connections. Servers MAY +discard any Initial packet that does not carry the expected token. + +Unlike the token that is created for a Retry packet, which is used +immediately, the token sent in the NEW_TOKEN frame can be used after +some period of time has passed. Thus, a token SHOULD have an +expiration time, which could be either an explicit expiration time or +an issued timestamp that can be used to dynamically calculate the +expiration time. A server can store the expiration time or include +it in an encrypted form in the token. + +A token issued with NEW_TOKEN MUST NOT include information that would +allow values to be linked by an observer to the connection on which +it was issued. For example, it cannot include the previous +connection ID or addressing information, unless the values are +encrypted. A server MUST ensure that every NEW_TOKEN frame it sends +is unique across all clients, with the exception of those sent to +repair losses of previously sent NEW_TOKEN frames. Information that +allows the server to distinguish between tokens from Retry and +NEW_TOKEN MAY be accessible to entities other than the server. + +It is unlikely that the client port number is the same on two +different connections; validating the port is therefore unlikely to +be successful. + +A token received in a NEW_TOKEN frame is applicable to any server +that the connection is considered authoritative for (e.g., server +names included in the certificate). When connecting to a server for +which the client retains an applicable and unused token, it SHOULD +include that token in the Token field of its Initial packet. +Including a token might allow the server to validate the client +address without an additional round trip. A client MUST NOT include +a token that is not applicable to the server that it is connecting +to, unless the client has the knowledge that the server that issued +the token and the server the client is connecting to are jointly +managing the tokens. A client MAY use a token from any previous +connection to that server. + +A token allows a server to correlate activity between the connection +where the token was issued and any connection where it is used. +Clients that want to break continuity of identity with a server can +discard tokens provided using the NEW_TOKEN frame. In comparison, a +token obtained in a Retry packet MUST be used immediately during the +connection attempt and cannot be used in subsequent connection +attempts. + +A client SHOULD NOT reuse a token from a NEW_TOKEN frame for +different connection attempts. Reusing a token allows connections to +be linked by entities on the network path; see Section 9.5. + +Clients might receive multiple tokens on a single connection. Aside +from preventing linkability, any token can be used in any connection +attempt. Servers can send additional tokens to either enable address +validation for multiple connection attempts or replace older tokens +that might become invalid. For a client, this ambiguity means that +sending the most recent unused token is most likely to be effective. +Though saving and using older tokens have no negative consequences, +clients can regard older tokens as being less likely to be useful to +the server for address validation. + +When a server receives an Initial packet with an address validation +token, it MUST attempt to validate the token, unless it has already +completed address validation. If the token is invalid, then the +server SHOULD proceed as if the client did not have a validated +address, including potentially sending a Retry packet. Tokens +provided with NEW_TOKEN frames and Retry packets can be distinguished +by servers (see Section 8.1.1), and the latter can be validated more +strictly. If the validation succeeds, the server SHOULD then allow +the handshake to proceed. + +Note: The rationale for treating the client as unvalidated +rather than discarding the packet is that the client might have +received the token in a previous connection using the NEW_TOKEN +frame, and if the server has lost state, it might be unable to +validate the token at all, leading to connection failure if the +packet is discarded. + +In a stateless design, a server can use encrypted and authenticated +tokens to pass information to clients that the server can later +recover and use to validate a client address. Tokens are not +integrated into the cryptographic handshake, and so they are not +authenticated. For instance, a client might be able to reuse a +token. To avoid attacks that exploit this property, a server can +limit its use of tokens to only the information needed to validate +client addresses. + +Clients MAY use tokens obtained on one connection for any connection +attempt using the same version. When selecting a token to use, +clients do not need to consider other properties of the connection +that is being attempted, including the choice of possible application +protocols, session tickets, or other connection properties. + +Address Validation Token Integrity +``````````````````````````````````````````````````````` + +An address validation token MUST be difficult to guess. Including a +random value with at least 128 bits of entropy in the token would be +sufficient, but this depends on the server remembering the value it +sends to clients. + +A token-based scheme allows the server to offload any state +associated with validation to the client. For this design to work, +the token MUST be covered by integrity protection against +modification or falsification by clients. Without integrity +protection, malicious clients could generate or guess values for +tokens that would be accepted by the server. Only the server +requires access to the integrity protection key for tokens. + +There is no need for a single well-defined format for the token +because the server that generates the token also consumes it. Tokens +sent in Retry packets SHOULD include information that allows the +server to verify that the source IP address and port in client +packets remain constant. + +Tokens sent in NEW_TOKEN frames MUST include information that allows +the server to verify that the client IP address has not changed from +when the token was issued. Servers can use tokens from NEW_TOKEN +frames in deciding not to send a Retry packet, even if the client +address has changed. If the client IP address has changed, the +server MUST adhere to the anti-amplification limit; see Section 8. +Note that in the presence of NAT, this requirement might be +insufficient to protect other hosts that share the NAT from +amplification attacks. + +Attackers could replay tokens to use servers as amplifiers in DDoS +attacks. To protect against such attacks, servers MUST ensure that +replay of tokens is prevented or limited. Servers SHOULD ensure that +tokens sent in Retry packets are only accepted for a short time, as +they are returned immediately by clients. Tokens that are provided +in NEW_TOKEN frames (Section 19.7) need to be valid for longer but +SHOULD NOT be accepted multiple times. Servers are encouraged to +allow tokens to be used only once, if possible; tokens MAY include +additional information about clients to further narrow applicability +or reuse. + +Path Validation +``````````````````````````````````````````````````````` + +Path validation is used by both peers during connection migration +(see Section 9) to verify reachability after a change of address. In +path validation, endpoints test reachability between a specific local +address and a specific peer address, where an address is the 2-tuple +of IP address and port. + +Path validation tests that packets sent on a path to a peer are +received by that peer. Path validation is used to ensure that +packets received from a migrating peer do not carry a spoofed source +address. + +Path validation does not validate that a peer can send in the return +direction. Acknowledgments cannot be used for return path validation +because they contain insufficient entropy and might be spoofed. +Endpoints independently determine reachability on each direction of a +path, and therefore return reachability can only be established by +the peer. + +Path validation can be used at any time by either endpoint. For +instance, an endpoint might check that a peer is still in possession +of its address after a period of quiescence. + +Path validation is not designed as a NAT traversal mechanism. Though +the mechanism described here might be effective for the creation of +NAT bindings that support NAT traversal, the expectation is that one +endpoint is able to receive packets without first having sent a +packet on that path. Effective NAT traversal needs additional +synchronization mechanisms that are not provided here. + +An endpoint MAY include other frames with the PATH_CHALLENGE and +PATH_RESPONSE frames used for path validation. In particular, an +endpoint can include PADDING frames with a PATH_CHALLENGE frame for +Path Maximum Transmission Unit Discovery (PMTUD); see Section 14.2.1. +An endpoint can also include its own PATH_CHALLENGE frame when +sending a PATH_RESPONSE frame. + +An endpoint uses a new connection ID for probes sent from a new local +address; see Section 9.5. When probing a new path, an endpoint can +ensure that its peer has an unused connection ID available for +responses. Sending NEW_CONNECTION_ID and PATH_CHALLENGE frames in +the same packet, if the peer's active_connection_id_limit permits, +ensures that an unused connection ID will be available to the peer +when sending a response. + +An endpoint can choose to simultaneously probe multiple paths. The +number of simultaneous paths used for probes is limited by the number +of extra connection IDs its peer has previously supplied, since each +new local address used for a probe requires a previously unused +connection ID. + +Initiating Path Validation +``````````````````````````````````````````````````````` + +To initiate path validation, an endpoint sends a PATH_CHALLENGE frame +containing an unpredictable payload on the path to be validated. + +An endpoint MAY send multiple PATH_CHALLENGE frames to guard against +packet loss. However, an endpoint SHOULD NOT send multiple +PATH_CHALLENGE frames in a single packet. + +An endpoint SHOULD NOT probe a new path with packets containing a +PATH_CHALLENGE frame more frequently than it would send an Initial +packet. This ensures that connection migration is no more load on a +new path than establishing a new connection. + +The endpoint MUST use unpredictable data in every PATH_CHALLENGE +frame so that it can associate the peer's response with the +corresponding PATH_CHALLENGE. + +An endpoint MUST expand datagrams that contain a PATH_CHALLENGE frame +to at least the smallest allowed maximum datagram size of 1200 bytes, +unless the anti-amplification limit for the path does not permit +sending a datagram of this size. Sending UDP datagrams of this size +ensures that the network path from the endpoint to the peer can be +used for QUIC; see Section 14. + +When an endpoint is unable to expand the datagram size to 1200 bytes +due to the anti-amplification limit, the path MTU will not be +validated. To ensure that the path MTU is large enough, the endpoint +MUST perform a second path validation by sending a PATH_CHALLENGE +frame in a datagram of at least 1200 bytes. This additional +validation can be performed after a PATH_RESPONSE is successfully +received or when enough bytes have been received on the path that +sending the larger datagram will not result in exceeding the anti- +amplification limit. + +Unlike other cases where datagrams are expanded, endpoints MUST NOT +discard datagrams that appear to be too small when they contain +PATH_CHALLENGE or PATH_RESPONSE. + +Path Validation Responses +``````````````````````````````````````````````````````` + +On receiving a PATH_CHALLENGE frame, an endpoint MUST respond by +echoing the data contained in the PATH_CHALLENGE frame in a +PATH_RESPONSE frame. An endpoint MUST NOT delay transmission of a +packet containing a PATH_RESPONSE frame unless constrained by +congestion control. + +A PATH_RESPONSE frame MUST be sent on the network path where the +PATH_CHALLENGE frame was received. This ensures that path validation +by a peer only succeeds if the path is functional in both directions. +This requirement MUST NOT be enforced by the endpoint that initiates +path validation, as that would enable an attack on migration; see +Section 9.3.3. + +An endpoint MUST expand datagrams that contain a PATH_RESPONSE frame +to at least the smallest allowed maximum datagram size of 1200 bytes. +This verifies that the path is able to carry datagrams of this size +in both directions. However, an endpoint MUST NOT expand the +datagram containing the PATH_RESPONSE if the resulting data exceeds +the anti-amplification limit. This is expected to only occur if the +received PATH_CHALLENGE was not sent in an expanded datagram. + +An endpoint MUST NOT send more than one PATH_RESPONSE frame in +response to one PATH_CHALLENGE frame; see Section 13.3. The peer is +expected to send more PATH_CHALLENGE frames as necessary to evoke +additional PATH_RESPONSE frames. + +Successful Path Validation +``````````````````````````````````````````````````````` + +Path validation succeeds when a PATH_RESPONSE frame is received that +contains the data that was sent in a previous PATH_CHALLENGE frame. +A PATH_RESPONSE frame received on any network path validates the path +on which the PATH_CHALLENGE was sent. + +If an endpoint sends a PATH_CHALLENGE frame in a datagram that is not +expanded to at least 1200 bytes and if the response to it validates +the peer address, the path is validated but not the path MTU. As a +result, the endpoint can now send more than three times the amount of +data that has been received. However, the endpoint MUST initiate +another path validation with an expanded datagram to verify that the +path supports the required MTU. + +Receipt of an acknowledgment for a packet containing a PATH_CHALLENGE +frame is not adequate validation, since the acknowledgment can be +spoofed by a malicious peer. + +Failed Path Validation +``````````````````````````````````````````````````````` + +Path validation only fails when the endpoint attempting to validate +the path abandons its attempt to validate the path. + +Endpoints SHOULD abandon path validation based on a timer. When +setting this timer, implementations are cautioned that the new path +could have a longer round-trip time than the original. A value of +three times the larger of the current PTO or the PTO for the new path +(using kInitialRtt, as defined in [QUIC-RECOVERY]) is RECOMMENDED. + +This timeout allows for multiple PTOs to expire prior to failing path +validation, so that loss of a single PATH_CHALLENGE or PATH_RESPONSE +frame does not cause path validation failure. + +Note that the endpoint might receive packets containing other frames +on the new path, but a PATH_RESPONSE frame with appropriate data is +required for path validation to succeed. + +When an endpoint abandons path validation, it determines that the +path is unusable. This does not necessarily imply a failure of the +connection -- endpoints can continue sending packets over other paths +as appropriate. If no paths are available, an endpoint can wait for +a new path to become available or close the connection. An endpoint +that has no valid network path to its peer MAY signal this using the +NO_VIABLE_PATH connection error, noting that this is only possible if +the network path exists but does not support the required MTU +(Section 14). + +A path validation might be abandoned for other reasons besides +failure. Primarily, this happens if a connection migration to a new +path is initiated while a path validation on the old path is in +progress. + +Connection Migration +---------------------------- + +Following is copied from QUIC [RFC-9000]_. + +The use of a connection ID allows connections to survive changes to +endpoint addresses (IP address and port), such as those caused by an +endpoint migrating to a new network. This section describes the +process by which an endpoint migrates to a new address. + +The design of QUIC relies on endpoints retaining a stable address for +the duration of the handshake. An endpoint MUST NOT initiate +connection migration before the handshake is confirmed, as defined in +Section 4.1.2 of [QUIC-TLS]. + +If the peer sent the disable_active_migration transport parameter, an +endpoint also MUST NOT send packets (including probing packets; see +Section 9.1) from a different local address to the address the peer +used during the handshake, unless the endpoint has acted on a +preferred_address transport parameter from the peer. If the peer +violates this requirement, the endpoint MUST either drop the incoming +packets on that path without generating a Stateless Reset or proceed +with path validation and allow the peer to migrate. Generating a +Stateless Reset or closing the connection would allow third parties +in the network to cause connections to close by spoofing or otherwise +manipulating observed traffic. + +Not all changes of peer address are intentional, or active, +migrations. The peer could experience NAT rebinding: a change of +address due to a middlebox, usually a NAT, allocating a new outgoing +port or even a new outgoing IP address for a flow. An endpoint MUST +perform path validation (Section 8.2) if it detects any change to a +peer's address, unless it has previously validated that address. + +When an endpoint has no validated path on which to send packets, it +MAY discard connection state. An endpoint capable of connection +migration MAY wait for a new path to become available before +discarding connection state. + +This document limits migration of connections to new client +addresses, except as described in Section 9.6. Clients are +responsible for initiating all migrations. Servers do not send non- +probing packets (see Section 9.1) toward a client address until they +see a non-probing packet from that address. If a client receives +packets from an unknown server address, the client MUST discard these +packets. + +Probing a New Path +````````````````````````` + +An endpoint MAY probe for peer reachability from a new local address +using path validation (Section 8.2) prior to migrating the connection +to the new local address. Failure of path validation simply means +that the new path is not usable for this connection. Failure to +validate a path does not cause the connection to end unless there are +no valid alternative paths available. + +PATH_CHALLENGE, PATH_RESPONSE, NEW_CONNECTION_ID, and PADDING frames +are "probing frames", and all other frames are "non-probing frames". +A packet containing only probing frames is a "probing packet", and a +packet containing any other frame is a "non-probing packet". + +Initiating Connection Migration +````````````````````````````````````` + +An endpoint can migrate a connection to a new local address by +sending packets containing non-probing frames from that address. + +Each endpoint validates its peer's address during connection +establishment. Therefore, a migrating endpoint can send to its peer +knowing that the peer is willing to receive at the peer's current +address. Thus, an endpoint can migrate to a new local address +without first validating the peer's address. + +To establish reachability on the new path, an endpoint initiates path +validation (Section 8.2) on the new path. An endpoint MAY defer path +validation until after a peer sends the next non-probing frame to its +new address. + +When migrating, the new path might not support the endpoint's current +sending rate. Therefore, the endpoint resets its congestion +controller and RTT estimate, as described in Section 9.4. + +The new path might not have the same ECN capability. Therefore, the +endpoint validates ECN capability as described in Section 13.4. + +Responding to Connection Migration +``````````````````````````````````````````` + +Receiving a packet from a new peer address containing a non-probing +frame indicates that the peer has migrated to that address. + +If the recipient permits the migration, it MUST send subsequent +packets to the new peer address and MUST initiate path validation +(Section 8.2) to verify the peer's ownership of the address if +validation is not already underway. If the recipient has no unused +connection IDs from the peer, it will not be able to send anything on +the new path until the peer provides one; see Section 9.5. + +An endpoint only changes the address to which it sends packets in +response to the highest-numbered non-probing packet. This ensures +that an endpoint does not send packets to an old peer address in the +case that it receives reordered packets. + +An endpoint MAY send data to an unvalidated peer address, but it MUST +protect against potential attacks as described in Sections 9.3.1 and +9.3.2. An endpoint MAY skip validation of a peer address if that +address has been seen recently. In particular, if an endpoint +returns to a previously validated path after detecting some form of +spurious migration, skipping address validation and restoring loss +detection and congestion state can reduce the performance impact of +the attack. + +After changing the address to which it sends non-probing packets, an +endpoint can abandon any path validation for other addresses. + +Receiving a packet from a new peer address could be the result of a +NAT rebinding at the peer. + +After verifying a new client address, the server SHOULD send new +address validation tokens (Section 8) to the client. + +Peer Address Spoofing +````````````````````````` + +It is possible that a peer is spoofing its source address to cause an +endpoint to send excessive amounts of data to an unwilling host. If +the endpoint sends significantly more data than the spoofing peer, +connection migration might be used to amplify the volume of data that +an attacker can generate toward a victim. + +As described in Section 9.3, an endpoint is required to validate a +peer's new address to confirm the peer's possession of the new +address. Until a peer's address is deemed valid, an endpoint limits +the amount of data it sends to that address; see Section 8. In the +absence of this limit, an endpoint risks being used for a denial-of- +service attack against an unsuspecting victim. + +If an endpoint skips validation of a peer address as described above, +it does not need to limit its sending rate. + +On-Path Address Spoofing +````````````````````````` + +An on-path attacker could cause a spurious connection migration by +copying and forwarding a packet with a spoofed address such that it +arrives before the original packet. The packet with the spoofed +address will be seen to come from a migrating connection, and the +original packet will be seen as a duplicate and dropped. After a +spurious migration, validation of the source address will fail +because the entity at the source address does not have the necessary +cryptographic keys to read or respond to the PATH_CHALLENGE frame +that is sent to it even if it wanted to. + +To protect the connection from failing due to such a spurious +migration, an endpoint MUST revert to using the last validated peer +address when validation of a new peer address fails. Additionally, +receipt of packets with higher packet numbers from the legitimate +peer address will trigger another connection migration. This will +cause the validation of the address of the spurious migration to be +abandoned, thus containing migrations initiated by the attacker +injecting a single packet. + +If an endpoint has no state about the last validated peer address, it +MUST close the connection silently by discarding all connection +state. This results in new packets on the connection being handled +generically. For instance, an endpoint MAY send a Stateless Reset in +response to any further incoming packets. + +Off-Path Packet Forwarding +``````````````````````````````````` + +An off-path attacker that can observe packets might forward copies of +genuine packets to endpoints. If the copied packet arrives before +the genuine packet, this will appear as a NAT rebinding. Any genuine +packet will be discarded as a duplicate. If the attacker is able to +continue forwarding packets, it might be able to cause migration to a +path via the attacker. This places the attacker on-path, giving it +the ability to observe or drop all subsequent packets. + +This style of attack relies on the attacker using a path that has +approximately the same characteristics as the direct path between +endpoints. The attack is more reliable if relatively few packets are +sent or if packet loss coincides with the attempted attack. + +A non-probing packet received on the original path that increases the +maximum received packet number will cause the endpoint to move back +to that path. Eliciting packets on this path increases the +likelihood that the attack is unsuccessful. Therefore, mitigation of +this attack relies on triggering the exchange of packets. + +In response to an apparent migration, endpoints MUST validate the +previously active path using a PATH_CHALLENGE frame. This induces +the sending of new packets on that path. If the path is no longer +viable, the validation attempt will time out and fail; if the path is +viable but no longer desired, the validation will succeed but only +results in probing packets being sent on the path. + +An endpoint that receives a PATH_CHALLENGE on an active path SHOULD +send a non-probing packet in response. If the non-probing packet +arrives before any copy made by an attacker, this results in the +connection being migrated back to the original path. Any subsequent +migration to another path restarts this entire process. + +This defense is imperfect, but this is not considered a serious +problem. If the path via the attack is reliably faster than the +original path despite multiple attempts to use that original path, it +is not possible to distinguish between an attack and an improvement +in routing. + +An endpoint could also use heuristics to improve detection of this +style of attack. For instance, NAT rebinding is improbable if +packets were recently received on the old path; similarly, rebinding +is rare on IPv6 paths. Endpoints can also look for duplicated +packets. Conversely, a change in connection ID is more likely to +indicate an intentional migration rather than an attack. + +Loss Detection and Congestion Control +````````````````````````````````````````` + +The capacity available on the new path might not be the same as the +old path. Packets sent on the old path MUST NOT contribute to +congestion control or RTT estimation for the new path. + +On confirming a peer's ownership of its new address, an endpoint MUST +immediately reset the congestion controller and round-trip time +estimator for the new path to initial values (see Appendices A.3 and +B.3 of [QUIC-RECOVERY]) unless the only change in the peer's address +is its port number. Because port-only changes are commonly the +result of NAT rebinding or other middlebox activity, the endpoint MAY +instead retain its congestion control state and round-trip estimate +in those cases instead of reverting to initial values. In cases +where congestion control state retained from an old path is used on a +new path with substantially different characteristics, a sender could +transmit too aggressively until the congestion controller and the RTT +estimator have adapted. Generally, implementations are advised to be +cautious when using previous values on a new path. + +There could be apparent reordering at the receiver when an endpoint +sends data and probes from/to multiple addresses during the migration +period, since the two resulting paths could have different round-trip +times. A receiver of packets on multiple paths will still send ACK +frames covering all received packets. + +While multiple paths might be used during connection migration, a +single congestion control context and a single loss recovery context +(as described in [QUIC-RECOVERY]) could be adequate. For instance, +an endpoint might delay switching to a new congestion control context +until it is confirmed that an old path is no longer needed (such as +the case described in Section 9.3.3). + +A sender can make exceptions for probe packets so that their loss +detection is independent and does not unduly cause the congestion +controller to reduce its sending rate. An endpoint might set a +separate timer when a PATH_CHALLENGE is sent, which is canceled if +the corresponding PATH_RESPONSE is received. If the timer fires +before the PATH_RESPONSE is received, the endpoint might send a new +PATH_CHALLENGE and restart the timer for a longer period of time. +This timer SHOULD be set as described in Section 6.2.1 of +[QUIC-RECOVERY] and MUST NOT be more aggressive. + +Privacy Implications of Connection Migration +````````````````````````````````````````````````` + +Using a stable connection ID on multiple network paths would allow a +passive observer to correlate activity between those paths. An +endpoint that moves between networks might not wish to have their +activity correlated by any entity other than their peer, so different +connection IDs are used when sending from different local addresses, +as discussed in Section 5.1. For this to be effective, endpoints +need to ensure that connection IDs they provide cannot be linked by +any other entity. + +At any time, endpoints MAY change the Destination Connection ID they +transmit with to a value that has not been used on another path. + +An endpoint MUST NOT reuse a connection ID when sending from more +than one local address -- for example, when initiating connection +migration as described in Section 9.2 or when probing a new network +path as described in Section 9.1. + +Similarly, an endpoint MUST NOT reuse a connection ID when sending to +more than one destination address. Due to network changes outside +the control of its peer, an endpoint might receive packets from a new +source address with the same Destination Connection ID field value, +in which case it MAY continue to use the current connection ID with +the new remote address while still sending from the same local +address. + +These requirements regarding connection ID reuse apply only to the +sending of packets, as unintentional changes in path without a change +in connection ID are possible. For example, after a period of +network inactivity, NAT rebinding might cause packets to be sent on a +new path when the client resumes sending. An endpoint responds to +such an event as described in Section 9.3. + +Using different connection IDs for packets sent in both directions on +each new network path eliminates the use of the connection ID for +linking packets from the same connection across different network +paths. Header protection ensures that packet numbers cannot be used +to correlate activity. This does not prevent other properties of +packets, such as timing and size, from being used to correlate +activity. + +An endpoint SHOULD NOT initiate migration with a peer that has +requested a zero-length connection ID, because traffic over the new +path might be trivially linkable to traffic over the old one. If the +server is able to associate packets with a zero-length connection ID +to the right connection, it means that the server is using other +information to demultiplex packets. For example, a server might +provide a unique address to every client -- for instance, using HTTP +alternative services [ALTSVC]. Information that might allow correct +routing of packets across multiple network paths will also allow +activity on those paths to be linked by entities other than the peer. + +A client might wish to reduce linkability by switching to a new +connection ID, source UDP port, or IP address (see [RFC8981]) when +sending traffic after a period of inactivity. Changing the address +from which it sends packets at the same time might cause the server +to detect a connection migration. This ensures that the mechanisms +that support migration are exercised even for clients that do not +experience NAT rebindings or genuine migrations. Changing address +can cause a peer to reset its congestion control state (see +Section 9.4), so addresses SHOULD only be changed infrequently. + +An endpoint that exhausts available connection IDs cannot probe new +paths or initiate migration, nor can it respond to probes or attempts +by its peer to migrate. To ensure that migration is possible and +packets sent on different paths cannot be correlated, endpoints +SHOULD provide new connection IDs before peers migrate; see +Section 5.1.1. If a peer might have exhausted available connection +IDs, a migrating endpoint could include a NEW_CONNECTION_ID frame in +all packets sent on a new network path. + +Server's Preferred Address +````````````````````````````` + +QUIC allows servers to accept connections on one IP address and +attempt to transfer these connections to a more preferred address +shortly after the handshake. This is particularly useful when +clients initially connect to an address shared by multiple servers +but would prefer to use a unicast address to ensure connection +stability. This section describes the protocol for migrating a +connection to a preferred server address. + +Migrating a connection to a new server address mid-connection is not +supported by the version of QUIC specified in this document. If a +client receives packets from a new server address when the client has +not initiated a migration to that address, the client SHOULD discard +these packets. + +Communicating a Preferred Address +`````````````````````````````````````` + +A server conveys a preferred address by including the +preferred_address transport parameter in the TLS handshake. + +Servers MAY communicate a preferred address of each address family +(IPv4 and IPv6) to allow clients to pick the one most suited to their +network attachment. + +Once the handshake is confirmed, the client SHOULD select one of the +two addresses provided by the server and initiate path validation +(see Section 8.2). A client constructs packets using any previously +unused active connection ID, taken from either the preferred_address +transport parameter or a NEW_CONNECTION_ID frame. + +As soon as path validation succeeds, the client SHOULD begin sending +all future packets to the new server address using the new connection +ID and discontinue use of the old server address. If path validation +fails, the client MUST continue sending all future packets to the +server's original IP address. + +Migration to a Preferred Address +```````````````````````````````````` + +A client that migrates to a preferred address MUST validate the +address it chooses before migrating; see Section 21.5.3. + +A server might receive a packet addressed to its preferred IP address +at any time after it accepts a connection. If this packet contains a +PATH_CHALLENGE frame, the server sends a packet containing a +PATH_RESPONSE frame as per Section 8.2. The server MUST send non- +probing packets from its original address until it receives a non- +probing packet from the client at its preferred address and until the +server has validated the new path. + +The server MUST probe on the path toward the client from its +preferred address. This helps to guard against spurious migration +initiated by an attacker. + +Once the server has completed its path validation and has received a +non-probing packet with a new largest packet number on its preferred +address, the server begins sending non-probing packets to the client +exclusively from its preferred IP address. The server SHOULD drop +newer packets for this connection that are received on the old IP +address. The server MAY continue to process delayed packets that are +received on the old IP address. + +The addresses that a server provides in the preferred_address +transport parameter are only valid for the connection in which they +are provided. A client MUST NOT use these for other connections, +including connections that are resumed from the current connection. + +Interaction of Client Migration and Preferred Address +`````````````````````````````````````````````````````````` + +A client might need to perform a connection migration before it has +migrated to the server's preferred address. In this case, the client +SHOULD perform path validation to both the original and preferred +server address from the client's new address concurrently. + +If path validation of the server's preferred address succeeds, the +client MUST abandon validation of the original address and migrate to +using the server's preferred address. If path validation of the +server's preferred address fails but validation of the server's +original address succeeds, the client MAY migrate to its new address +and continue sending to the server's original address. + +If packets received at the server's preferred address have a +different source address than observed from the client during the +handshake, the server MUST protect against potential attacks as +described in Sections 9.3.1 and 9.3.2. In addition to intentional +simultaneous migration, this might also occur because the client's +access network used a different NAT binding for the server's +preferred address. + +Servers SHOULD initiate path validation to the client's new address +upon receiving a probe packet from a different address; see +Section 8. + +A client that migrates to a new address SHOULD use a preferred +address from the same address family for the server. + +The connection ID provided in the preferred_address transport +parameter is not specific to the addresses that are provided. This +connection ID is provided to ensure that the client has a connection +ID available for migration, but the client MAY use this connection ID +on any path. + +Use of IPv6 Flow Label and Migration +`````````````````````````````````````````` + +Endpoints that send data using IPv6 SHOULD apply an IPv6 flow label +in compliance with [RFC6437], unless the local API does not allow +setting IPv6 flow labels. + +The flow label generation MUST be designed to minimize the chances of +linkability with a previously used flow label, as a stable flow label +would enable correlating activity on multiple paths; see Section 9.5. + +[RFC6437] suggests deriving values using a pseudorandom function to +generate flow labels. Including the Destination Connection ID field +in addition to source and destination addresses when generating flow +labels ensures that changes are synchronized with changes in other +observable identifiers. A cryptographic hash function that combines +these inputs with a local secret is one way this might be +implemented. + + +Security Considerations +--------------------------- + +Following is copied from QUIC [RFC-9000]_. + +The goal of QUIC is to provide a secure transport connection. +Section 21.1 provides an overview of those properties; subsequent +sections discuss constraints and caveats regarding these properties, +including descriptions of known attacks and countermeasures. + +Overview of Security Properties +`````````````````````````````````````````````` + +A complete security analysis of QUIC is outside the scope of this +document. This section provides an informal description of the +desired security properties as an aid to implementers and to help +guide protocol analysis. + +QUIC assumes the threat model described in [SEC-CONS] and provides +protections against many of the attacks that arise from that model. + +For this purpose, attacks are divided into passive and active +attacks. Passive attackers have the ability to read packets from the +network, while active attackers also have the ability to write +packets into the network. However, a passive attack could involve an +attacker with the ability to cause a routing change or other +modification in the path taken by packets that comprise a connection. + +Attackers are additionally categorized as either on-path attackers or +off-path attackers. An on-path attacker can read, modify, or remove +any packet it observes such that the packet no longer reaches its +destination, while an off-path attacker observes the packets but +cannot prevent the original packet from reaching its intended +destination. Both types of attackers can also transmit arbitrary +packets. This definition differs from that of Section 3.5 of +[SEC-CONS] in that an off-path attacker is able to observe packets. + +Properties of the handshake, protected packets, and connection +migration are considered separately. + +Handshake +`````````````````````````````````````````````` + +The QUIC handshake incorporates the TLS 1.3 handshake and inherits +the cryptographic properties described in Appendix E.1 of [TLS13]. +Many of the security properties of QUIC depend on the TLS handshake +providing these properties. Any attack on the TLS handshake could +affect QUIC. + +Any attack on the TLS handshake that compromises the secrecy or +uniqueness of session keys, or the authentication of the +participating peers, affects other security guarantees provided by +QUIC that depend on those keys. For instance, migration (Section 9) +depends on the efficacy of confidentiality protections, both for the +negotiation of keys using the TLS handshake and for QUIC packet +protection, to avoid linkability across network paths. + +An attack on the integrity of the TLS handshake might allow an +attacker to affect the selection of application protocol or QUIC +version. + +In addition to the properties provided by TLS, the QUIC handshake +provides some defense against DoS attacks on the handshake. + +Anti-Amplification +`````````````````````````````````````````````` + +Address validation (Section 8) is used to verify that an entity that +claims a given address is able to receive packets at that address. +Address validation limits amplification attack targets to addresses +for which an attacker can observe packets. + +Prior to address validation, endpoints are limited in what they are +able to send. Endpoints cannot send data toward an unvalidated +address in excess of three times the data received from that address. + +Note: The anti-amplification limit only applies when an +endpoint responds to packets received from an unvalidated +address. The anti-amplification limit does not apply to +clients when establishing a new connection or when initiating +connection migration. + +Server-Side DoS +`````````````````````````````````````````````` + +Computing the server's first flight for a full handshake is +potentially expensive, requiring both a signature and a key exchange +computation. In order to prevent computational DoS attacks, the +Retry packet provides a cheap token exchange mechanism that allows +servers to validate a client's IP address prior to doing any +expensive computations at the cost of a single round trip. After a +successful handshake, servers can issue new tokens to a client, which +will allow new connection establishment without incurring this cost. + +On-Path Handshake Termination +`````````````````````````````````````````````` + +An on-path or off-path attacker can force a handshake to fail by +replacing or racing Initial packets. Once valid Initial packets have +been exchanged, subsequent Handshake packets are protected with the +Handshake keys, and an on-path attacker cannot force handshake +failure other than by dropping packets to cause endpoints to abandon +the attempt. + +An on-path attacker can also replace the addresses of packets on +either side and therefore cause the client or server to have an +incorrect view of the remote addresses. Such an attack is +indistinguishable from the functions performed by a NAT. + +Parameter Negotiation +`````````````````````````````````````````````` + +The entire handshake is cryptographically protected, with the Initial +packets being encrypted with per-version keys and the Handshake and +later packets being encrypted with keys derived from the TLS key +exchange. Further, parameter negotiation is folded into the TLS +transcript and thus provides the same integrity guarantees as +ordinary TLS negotiation. An attacker can observe the client's +transport parameters (as long as it knows the version-specific salt) +but cannot observe the server's transport parameters and cannot +influence parameter negotiation. + +Connection IDs are unencrypted but integrity protected in all +packets. + +This version of QUIC does not incorporate a version negotiation +mechanism; implementations of incompatible versions will simply fail +to establish a connection. + +Protected Packets +`````````````````````````````````````````````` + +Packet protection (Section 12.1) applies authenticated encryption to +all packets except Version Negotiation packets, though Initial and +Retry packets have limited protection due to the use of version- +specific keying material; see [QUIC-TLS] for more details. This +section considers passive and active attacks against protected +packets. + +Both on-path and off-path attackers can mount a passive attack in +which they save observed packets for an offline attack against packet +protection at a future time; this is true for any observer of any +packet on any network. + +An attacker that injects packets without being able to observe valid +packets for a connection is unlikely to be successful, since packet +protection ensures that valid packets are only generated by endpoints +that possess the key material established during the handshake; see +Sections 7 and 21.1.1. Similarly, any active attacker that observes +packets and attempts to insert new data or modify existing data in +those packets should not be able to generate packets deemed valid by +the receiving endpoint, other than Initial packets. + +A spoofing attack, in which an active attacker rewrites unprotected +parts of a packet that it forwards or injects, such as the source or +destination address, is only effective if the attacker can forward +packets to the original endpoint. Packet protection ensures that the +packet payloads can only be processed by the endpoints that completed +the handshake, and invalid packets are ignored by those endpoints. + +An attacker can also modify the boundaries between packets and UDP +datagrams, causing multiple packets to be coalesced into a single +datagram or splitting coalesced packets into multiple datagrams. +Aside from datagrams containing Initial packets, which require +padding, modification of how packets are arranged in datagrams has no +functional effect on a connection, although it might change some +performance characteristics. + +Connection Migration +`````````````````````````````````````````````` + +Connection migration (Section 9) provides endpoints with the ability +to transition between IP addresses and ports on multiple paths, using +one path at a time for transmission and receipt of non-probing +frames. Path validation (Section 8.2) establishes that a peer is +both willing and able to receive packets sent on a particular path. +This helps reduce the effects of address spoofing by limiting the +number of packets sent to a spoofed address. + +This section describes the intended security properties of connection +migration under various types of DoS attacks. + +On-Path Active Attacks +`````````````````````````````````````````````` + +An attacker that can cause a packet it observes to no longer reach +its intended destination is considered an on-path attacker. When an +attacker is present between a client and server, endpoints are +required to send packets through the attacker to establish +connectivity on a given path. + +An on-path attacker can: + +* Inspect packets + +* Modify IP and UDP packet headers + +* Inject new packets + +* Delay packets + +* Reorder packets + +* Drop packets + +* Split and merge datagrams along packet boundaries + +An on-path attacker cannot: + +* Modify an authenticated portion of a packet and cause the + recipient to accept that packet + +An on-path attacker has the opportunity to modify the packets that it +observes; however, any modifications to an authenticated portion of a +packet will cause it to be dropped by the receiving endpoint as +invalid, as packet payloads are both authenticated and encrypted. + +QUIC aims to constrain the capabilities of an on-path attacker as +follows: + +1. An on-path attacker can prevent the use of a path for a + connection, causing the connection to fail if it cannot use a + different path that does not contain the attacker. This can be + achieved by dropping all packets, modifying them so that they + fail to decrypt, or other methods. + +2. An on-path attacker can prevent migration to a new path for which + the attacker is also on-path by causing path validation to fail + on the new path. + +3. An on-path attacker cannot prevent a client from migrating to a + path for which the attacker is not on-path. + +4. An on-path attacker can reduce the throughput of a connection by + delaying packets or dropping them. + +5. An on-path attacker cannot cause an endpoint to accept a packet + for which it has modified an authenticated portion of that + packet. + +Off-Path Active Attacks +`````````````````````````````````````````````` + +An off-path attacker is not directly on the path between a client and +server but could be able to obtain copies of some or all packets sent +between the client and the server. It is also able to send copies of +those packets to either endpoint. + +An off-path attacker can: + +* Inspect packets + +* Inject new packets + +* Reorder injected packets + +An off-path attacker cannot: + +* Modify packets sent by endpoints + +* Delay packets + +* Drop packets + +* Reorder original packets + +An off-path attacker can create modified copies of packets that it +has observed and inject those copies into the network, potentially +with spoofed source and destination addresses. + +For the purposes of this discussion, it is assumed that an off-path +attacker has the ability to inject a modified copy of a packet into +the network that will reach the destination endpoint prior to the +arrival of the original packet observed by the attacker. In other +words, an attacker has the ability to consistently "win" a race with +the legitimate packets between the endpoints, potentially causing the +original packet to be ignored by the recipient. + +It is also assumed that an attacker has the resources necessary to +affect NAT state. In particular, an attacker can cause an endpoint +to lose its NAT binding and then obtain the same port for use with +its own traffic. + +QUIC aims to constrain the capabilities of an off-path attacker as +follows: + +1. An off-path attacker can race packets and attempt to become a + "limited" on-path attacker. + +2. An off-path attacker can cause path validation to succeed for + forwarded packets with the source address listed as the off-path + attacker as long as it can provide improved connectivity between + the client and the server. + +3. An off-path attacker cannot cause a connection to close once the + handshake has completed. + +4. An off-path attacker cannot cause migration to a new path to fail + if it cannot observe the new path. + +5. An off-path attacker can become a limited on-path attacker during + migration to a new path for which it is also an off-path + attacker. + +6. An off-path attacker can become a limited on-path attacker by + affecting shared NAT state such that it sends packets to the + server from the same IP address and port that the client + originally used. + +Limited On-Path Active Attacks +`````````````````````````````````````````````` + +A limited on-path attacker is an off-path attacker that has offered +improved routing of packets by duplicating and forwarding original +packets between the server and the client, causing those packets to +arrive before the original copies such that the original packets are +dropped by the destination endpoint. + +A limited on-path attacker differs from an on-path attacker in that +it is not on the original path between endpoints, and therefore the +original packets sent by an endpoint are still reaching their +destination. This means that a future failure to route copied +packets to the destination faster than their original path will not +prevent the original packets from reaching the destination. + +A limited on-path attacker can: + +* Inspect packets + +* Inject new packets + +* Modify unencrypted packet headers + +* Reorder packets + +A limited on-path attacker cannot: + +* Delay packets so that they arrive later than packets sent on the + original path + +* Drop packets + +* Modify the authenticated and encrypted portion of a packet and + cause the recipient to accept that packet + +A limited on-path attacker can only delay packets up to the point +that the original packets arrive before the duplicate packets, +meaning that it cannot offer routing with worse latency than the +original path. If a limited on-path attacker drops packets, the +original copy will still arrive at the destination endpoint. + +QUIC aims to constrain the capabilities of a limited off-path +attacker as follows: + +1. A limited on-path attacker cannot cause a connection to close + once the handshake has completed. + +2. A limited on-path attacker cannot cause an idle connection to + close if the client is first to resume activity. + +3. A limited on-path attacker can cause an idle connection to be + deemed lost if the server is the first to resume activity. + +Note that these guarantees are the same guarantees provided for any +NAT, for the same reasons. + +Handshake Denial of Service +`````````````````````````````````````````````` + +As an encrypted and authenticated transport, QUIC provides a range of +protections against denial of service. Once the cryptographic +handshake is complete, QUIC endpoints discard most packets that are +not authenticated, greatly limiting the ability of an attacker to +interfere with existing connections. + +Once a connection is established, QUIC endpoints might accept some +unauthenticated ICMP packets (see Section 14.2.1), but the use of +these packets is extremely limited. The only other type of packet +that an endpoint might accept is a stateless reset (Section 10.3), +which relies on the token being kept secret until it is used. + +During the creation of a connection, QUIC only provides protection +against attacks from off the network path. All QUIC packets contain +proof that the recipient saw a preceding packet from its peer. + +Addresses cannot change during the handshake, so endpoints can +discard packets that are received on a different network path. + +The Source and Destination Connection ID fields are the primary means +of protection against an off-path attack during the handshake; see +Section 8.1. These are required to match those set by a peer. +Except for Initial and Stateless Resets, an endpoint only accepts +packets that include a Destination Connection ID field that matches a +value the endpoint previously chose. This is the only protection +offered for Version Negotiation packets. + +The Destination Connection ID field in an Initial packet is selected +by a client to be unpredictable, which serves an additional purpose. +The packets that carry the cryptographic handshake are protected with +a key that is derived from this connection ID and a salt specific to +the QUIC version. This allows endpoints to use the same process for +authenticating packets that they receive as they use after the +cryptographic handshake completes. Packets that cannot be +authenticated are discarded. Protecting packets in this fashion +provides a strong assurance that the sender of the packet saw the +Initial packet and understood it. + +These protections are not intended to be effective against an +attacker that is able to receive QUIC packets prior to the connection +being established. Such an attacker can potentially send packets +that will be accepted by QUIC endpoints. This version of QUIC +attempts to detect this sort of attack, but it expects that endpoints +will fail to establish a connection rather than recovering. For the +most part, the cryptographic handshake protocol [QUIC-TLS] is +responsible for detecting tampering during the handshake. + +Endpoints are permitted to use other methods to detect and attempt to +recover from interference with the handshake. Invalid packets can be +identified and discarded using other methods, but no specific method +is mandated in this document. + +Amplification Attack +`````````````````````````````````````````````` + +An attacker might be able to receive an address validation token +(Section 8) from a server and then release the IP address it used to +acquire that token. At a later time, the attacker can initiate a +0-RTT connection with a server by spoofing this same address, which +might now address a different (victim) endpoint. The attacker can +thus potentially cause the server to send an initial congestion +window's worth of data towards the victim. + +Servers SHOULD provide mitigations for this attack by limiting the +usage and lifetime of address validation tokens; see Section 8.1.3. + +Optimistic ACK Attack +`````````````````````````````````````````````` + +An endpoint that acknowledges packets it has not received might cause +a congestion controller to permit sending at rates beyond what the +network supports. An endpoint MAY skip packet numbers when sending +packets to detect this behavior. An endpoint can then immediately +close the connection with a connection error of type +PROTOCOL_VIOLATION; see Section 10.2. + +Request Forgery Attacks +`````````````````````````````````````````````` + +A request forgery attack occurs where an endpoint causes its peer to +issue a request towards a victim, with the request controlled by the +endpoint. Request forgery attacks aim to provide an attacker with +access to capabilities of its peer that might otherwise be +unavailable to the attacker. For a networking protocol, a request +forgery attack is often used to exploit any implicit authorization +conferred on the peer by the victim due to the peer's location in the +network. + +For request forgery to be effective, an attacker needs to be able to +influence what packets the peer sends and where these packets are +sent. If an attacker can target a vulnerable service with a +controlled payload, that service might perform actions that are +attributed to the attacker's peer but are decided by the attacker. + +For example, cross-site request forgery [CSRF] exploits on the Web +cause a client to issue requests that include authorization cookies +[COOKIE], allowing one site access to information and actions that +are intended to be restricted to a different site. + +As QUIC runs over UDP, the primary attack modality of concern is one +where an attacker can select the address to which its peer sends UDP +datagrams and can control some of the unprotected content of those +packets. As much of the data sent by QUIC endpoints is protected, +this includes control over ciphertext. An attack is successful if an +attacker can cause a peer to send a UDP datagram to a host that will +perform some action based on content in the datagram. + +This section discusses ways in which QUIC might be used for request +forgery attacks. + +This section also describes limited countermeasures that can be +implemented by QUIC endpoints. These mitigations can be employed +unilaterally by a QUIC implementation or deployment, without +potential targets for request forgery attacks taking action. +However, these countermeasures could be insufficient if UDP-based +services do not properly authorize requests. + +Because the migration attack described in Section 21.5.4 is quite +powerful and does not have adequate countermeasures, QUIC server +implementations should assume that attackers can cause them to +generate arbitrary UDP payloads to arbitrary destinations. QUIC +servers SHOULD NOT be deployed in networks that do not deploy ingress +filtering [BCP38] and also have inadequately secured UDP endpoints. + +Although it is not generally possible to ensure that clients are not +co-located with vulnerable endpoints, this version of QUIC does not +allow servers to migrate, thus preventing spoofed migration attacks +on clients. Any future extension that allows server migration MUST +also define countermeasures for forgery attacks. + +Control Options for Endpoints +`````````````````````````````````````````````` + +QUIC offers some opportunities for an attacker to influence or +control where its peer sends UDP datagrams: + +* initial connection establishment (Section 7), where a server is + able to choose where a client sends datagrams -- for example, by + populating DNS records; + +* preferred addresses (Section 9.6), where a server is able to + choose where a client sends datagrams; + +* spoofed connection migrations (Section 9.3.1), where a client is + able to use source address spoofing to select where a server sends + subsequent datagrams; and + +* spoofed packets that cause a server to send a Version Negotiation + packet (Section 21.5.5). + +In all cases, the attacker can cause its peer to send datagrams to a +victim that might not understand QUIC. That is, these packets are +sent by the peer prior to address validation; see Section 8. + +Outside of the encrypted portion of packets, QUIC offers an endpoint +several options for controlling the content of UDP datagrams that its +peer sends. The Destination Connection ID field offers direct +control over bytes that appear early in packets sent by the peer; see +Section 5.1. The Token field in Initial packets offers a server +control over other bytes of Initial packets; see Section 17.2.2. + +There are no measures in this version of QUIC to prevent indirect +control over the encrypted portions of packets. It is necessary to +assume that endpoints are able to control the contents of frames that +a peer sends, especially those frames that convey application data, +such as STREAM frames. Though this depends to some degree on details +of the application protocol, some control is possible in many +protocol usage contexts. As the attacker has access to packet +protection keys, they are likely to be capable of predicting how a +peer will encrypt future packets. Successful control over datagram +content then only requires that the attacker be able to predict the +packet number and placement of frames in packets with some amount of +reliability. + +This section assumes that limiting control over datagram content is +not feasible. The focus of the mitigations in subsequent sections is +on limiting the ways in which datagrams that are sent prior to +address validation can be used for request forgery. + +Request Forgery with Client Initial Packets +`````````````````````````````````````````````` + +An attacker acting as a server can choose the IP address and port on +which it advertises its availability, so Initial packets from clients +are assumed to be available for use in this sort of attack. The +address validation implicit in the handshake ensures that -- for a +new connection -- a client will not send other types of packets to a +destination that does not understand QUIC or is not willing to accept +a QUIC connection. + +Initial packet protection (Section 5.2 of [QUIC-TLS]) makes it +difficult for servers to control the content of Initial packets sent +by clients. A client choosing an unpredictable Destination +Connection ID ensures that servers are unable to control any of the +encrypted portion of Initial packets from clients. + +However, the Token field is open to server control and does allow a +server to use clients to mount request forgery attacks. The use of +tokens provided with the NEW_TOKEN frame (Section 8.1.3) offers the +only option for request forgery during connection establishment. + +Clients, however, are not obligated to use the NEW_TOKEN frame. +Request forgery attacks that rely on the Token field can be avoided +if clients send an empty Token field when the server address has +changed from when the NEW_TOKEN frame was received. + +Clients could avoid using NEW_TOKEN if the server address changes. +However, not including a Token field could adversely affect +performance. Servers could rely on NEW_TOKEN to enable the sending +of data in excess of the three-times limit on sending data; see +Section 8.1. In particular, this affects cases where clients use +0-RTT to request data from servers. + +Sending a Retry packet (Section 17.2.5) offers a server the option to +change the Token field. After sending a Retry, the server can also +control the Destination Connection ID field of subsequent Initial +packets from the client. This also might allow indirect control over +the encrypted content of Initial packets. However, the exchange of a +Retry packet validates the server's address, thereby preventing the +use of subsequent Initial packets for request forgery. + +Request Forgery with Preferred Addresses +`````````````````````````````````````````````` + +Servers can specify a preferred address, which clients then migrate +to after confirming the handshake; see Section 9.6. The Destination +Connection ID field of packets that the client sends to a preferred +address can be used for request forgery. + +A client MUST NOT send non-probing frames to a preferred address +prior to validating that address; see Section 8. This greatly +reduces the options that a server has to control the encrypted +portion of datagrams. + +This document does not offer any additional countermeasures that are +specific to the use of preferred addresses and can be implemented by +endpoints. The generic measures described in Section 21.5.6 could be +used as further mitigation. + +Request Forgery with Spoofed Migration +`````````````````````````````````````````` + +Clients are able to present a spoofed source address as part of an +apparent connection migration to cause a server to send datagrams to +that address. + +The Destination Connection ID field in any packets that a server +subsequently sends to this spoofed address can be used for request +forgery. A client might also be able to influence the ciphertext. + +A server that only sends probing packets (Section 9.1) to an address +prior to address validation provides an attacker with only limited +control over the encrypted portion of datagrams. However, +particularly for NAT rebinding, this can adversely affect +performance. If the server sends frames carrying application data, +an attacker might be able to control most of the content of +datagrams. + +This document does not offer specific countermeasures that can be +implemented by endpoints, aside from the generic measures described +in Section 21.5.6. However, countermeasures for address spoofing at +the network level -- in particular, ingress filtering [BCP38] -- are +especially effective against attacks that use spoofing and originate +from an external network. + +Request Forgery with Version Negotiation +````````````````````````````````````````````````````` + +Clients that are able to present a spoofed source address on a packet +can cause a server to send a Version Negotiation packet +(Section 17.2.1) to that address. + +The absence of size restrictions on the connection ID fields for +packets of an unknown version increases the amount of data that the +client controls from the resulting datagram. The first byte of this +packet is not under client control and the next four bytes are zero, +but the client is able to control up to 512 bytes starting from the +fifth byte. + +No specific countermeasures are provided for this attack, though +generic protections (Section 21.5.6) could apply. In this case, +ingress filtering [BCP38] is also effective. + +Generic Request Forgery Countermeasures +````````````````````````````````````````````````````` + +The most effective defense against request forgery attacks is to +modify vulnerable services to use strong authentication. However, +this is not always something that is within the control of a QUIC +deployment. This section outlines some other steps that QUIC +endpoints could take unilaterally. These additional steps are all +discretionary because, depending on circumstances, they could +interfere with or prevent legitimate uses. + +Services offered over loopback interfaces often lack proper +authentication. Endpoints MAY prevent connection attempts or +migration to a loopback address. Endpoints SHOULD NOT allow +connections or migration to a loopback address if the same service +was previously available at a different interface or if the address +was provided by a service at a non-loopback address. Endpoints that +depend on these capabilities could offer an option to disable these +protections. + +Similarly, endpoints could regard a change in address to a link-local +address [RFC4291] or an address in a private-use range [RFC1918] from +a global, unique-local [RFC4193], or non-private address as a +potential attempt at request forgery. Endpoints could refuse to use +these addresses entirely, but that carries a significant risk of +interfering with legitimate uses. Endpoints SHOULD NOT refuse to use +an address unless they have specific knowledge about the network +indicating that sending datagrams to unvalidated addresses in a given +range is not safe. + +Endpoints MAY choose to reduce the risk of request forgery by not +including values from NEW_TOKEN frames in Initial packets or by only +sending probing frames in packets prior to completing address +validation. Note that this does not prevent an attacker from using +the Destination Connection ID field for an attack. + +Endpoints are not expected to have specific information about the +location of servers that could be vulnerable targets of a request +forgery attack. However, it might be possible over time to identify +specific UDP ports that are common targets of attacks or particular +patterns in datagrams that are used for attacks. Endpoints MAY +choose to avoid sending datagrams to these ports or not send +datagrams that match these patterns prior to validating the +destination address. Endpoints MAY retire connection IDs containing +patterns known to be problematic without using them. + +Note: Modifying endpoints to apply these protections is more +efficient than deploying network-based protections, as +endpoints do not need to perform any additional processing when +sending to an address that has been validated. + +Slowloris Attacks +````````````````````````````````````````````````````` + +The attacks commonly known as Slowloris [SLOWLORIS] try to keep many +connections to the target endpoint open and hold them open as long as +possible. These attacks can be executed against a QUIC endpoint by +generating the minimum amount of activity necessary to avoid being +closed for inactivity. This might involve sending small amounts of +data, gradually opening flow control windows in order to control the +sender rate, or manufacturing ACK frames that simulate a high loss +rate. + +QUIC deployments SHOULD provide mitigations for the Slowloris +attacks, such as increasing the maximum number of clients the server +will allow, limiting the number of connections a single IP address is +allowed to make, imposing restrictions on the minimum transfer speed +a connection is allowed to have, and restricting the length of time +an endpoint is allowed to stay connected. + +Stream Fragmentation and Reassembly Attacks +````````````````````````````````````````````````````` + +An adversarial sender might intentionally not send portions of the +stream data, causing the receiver to commit resources for the unsent +data. This could cause a disproportionate receive buffer memory +commitment and/or the creation of a large and inefficient data +structure at the receiver. + +An adversarial receiver might intentionally not acknowledge packets +containing stream data in an attempt to force the sender to store the +unacknowledged stream data for retransmission. + +The attack on receivers is mitigated if flow control windows +correspond to available memory. However, some receivers will +overcommit memory and advertise flow control offsets in the aggregate +that exceed actual available memory. The overcommitment strategy can +lead to better performance when endpoints are well behaved, but +renders endpoints vulnerable to the stream fragmentation attack. + +QUIC deployments SHOULD provide mitigations for stream fragmentation +attacks. Mitigations could consist of avoiding overcommitting +memory, limiting the size of tracking data structures, delaying +reassembly of STREAM frames, implementing heuristics based on the age +and duration of reassembly holes, or some combination of these. + +Stream Commitment Attack +````````````````````````````````````````````````````` + +An adversarial endpoint can open a large number of streams, +exhausting state on an endpoint. The adversarial endpoint could +repeat the process on a large number of connections, in a manner +similar to SYN flooding attacks in TCP. + +Normally, clients will open streams sequentially, as explained in +Section 2.1. However, when several streams are initiated at short +intervals, loss or reordering can cause STREAM frames that open +streams to be received out of sequence. On receiving a higher- +numbered stream ID, a receiver is required to open all intervening +streams of the same type; see Section 3.2. Thus, on a new +connection, opening stream 4000000 opens 1 million and 1 client- +initiated bidirectional streams. + +The number of active streams is limited by the +initial_max_streams_bidi and initial_max_streams_uni transport +parameters as updated by any received MAX_STREAMS frames, as +explained in Section 4.6. If chosen judiciously, these limits +mitigate the effect of the stream commitment attack. However, +setting the limit too low could affect performance when applications +expect to open a large number of streams. + +Peer Denial of Service +````````````````````````````````````````````````````` + +QUIC and TLS both contain frames or messages that have legitimate +uses in some contexts, but these frames or messages can be abused to +cause a peer to expend processing resources without having any +observable impact on the state of the connection. + +Messages can also be used to change and revert state in small or +inconsequential ways, such as by sending small increments to flow +control limits. + +If processing costs are disproportionately large in comparison to +bandwidth consumption or effect on state, then this could allow a +malicious peer to exhaust processing capacity. + +While there are legitimate uses for all messages, implementations +SHOULD track cost of processing relative to progress and treat +excessive quantities of any non-productive packets as indicative of +an attack. Endpoints MAY respond to this condition with a connection +error or by dropping packets. + +Explicit Congestion Notification Attacks +````````````````````````````````````````````````````` + +An on-path attacker could manipulate the value of ECN fields in the +IP header to influence the sender's rate. [RFC3168] discusses +manipulations and their effects in more detail. + +A limited on-path attacker can duplicate and send packets with +modified ECN fields to affect the sender's rate. If duplicate +packets are discarded by a receiver, an attacker will need to race +the duplicate packet against the original to be successful in this +attack. Therefore, QUIC endpoints ignore the ECN field in an IP +packet unless at least one QUIC packet in that IP packet is +successfully processed; see Section 13.4. + +Stateless Reset Oracle +````````````````````````````````````````````````````` + +Stateless resets create a possible denial-of-service attack analogous +to a TCP reset injection. This attack is possible if an attacker is +able to cause a stateless reset token to be generated for a +connection with a selected connection ID. An attacker that can cause +this token to be generated can reset an active connection with the +same connection ID. + +If a packet can be routed to different instances that share a static +key -- for example, by changing an IP address or port -- then an +attacker can cause the server to send a stateless reset. To defend +against this style of denial of service, endpoints that share a +static key for stateless resets (see Section 10.3.2) MUST be arranged +so that packets with a given connection ID always arrive at an +instance that has connection state, unless that connection is no +longer active. + +More generally, servers MUST NOT generate a stateless reset if a +connection with the corresponding connection ID could be active on +any endpoint using the same static key. + +In the case of a cluster that uses dynamic load balancing, it is +possible that a change in load-balancer configuration could occur +while an active instance retains connection state. Even if an +instance retains connection state, the change in routing and +resulting stateless reset will result in the connection being +terminated. If there is no chance of the packet being routed to the +correct instance, it is better to send a stateless reset than wait +for the connection to time out. However, this is acceptable only if +the routing cannot be influenced by an attacker. + +Version Downgrade +````````````````````````````````````````````````````` + +This document defines QUIC Version Negotiation packets (Section 6), +which can be used to negotiate the QUIC version used between two +endpoints. However, this document does not specify how this +negotiation will be performed between this version and subsequent +future versions. In particular, Version Negotiation packets do not +contain any mechanism to prevent version downgrade attacks. Future +versions of QUIC that use Version Negotiation packets MUST define a +mechanism that is robust against version downgrade attacks. + +Targeted Attacks by Routing +````````````````````````````````````````````````````` + +Deployments should limit the ability of an attacker to target a new +connection to a particular server instance. Ideally, routing +decisions are made independently of client-selected values, including +addresses. Once an instance is selected, a connection ID can be +selected so that later packets are routed to the same instance. + +Traffic Analysis +````````````````````````````````````````````````````` + +The length of QUIC packets can reveal information about the length of +the content of those packets. The PADDING frame is provided so that +endpoints have some ability to obscure the length of packet content; +see Section 19.1. + +Defeating traffic analysis is challenging and the subject of active +research. Length is not the only way that information might leak. +Endpoints might also reveal sensitive information through other side +channels, such as the timing of packets. + + + + + +Noise Protocol Framework +======================== + +This proposal provides the requirements based on the Noise Protocol Framework +[NOISE]_ (Revision 33, 2017-10-04). +Noise has similar properties to the Station-To-Station protocol +[STS]_, which is the basis for the [SSU]_ protocol. In Noise parlance, Alice +is the initiator, and Bob is the responder. + +SSU2 is based on the Noise protocol Noise_XK_25519_ChaChaPoly_SHA256. +(The actual identifier for the initial key derivation function +is "Noise_XKaesobfse+hs2+hs3_25519_ChaChaPoly_SHA256" +to indicate I2P extensions - see KDF 1 section below) +This Noise protocol uses the following primitives: + +- Handshake Pattern: XK + Alice transmits her key to Bob (X) + Alice knows Bob's static key already (K) + +- DH Function: X25519 + X25519 DH with a key length of 32 bytes as specified in [RFC-7748]_. + +- Cipher Function: ChaChaPoly + AEAD_CHACHA20_POLY1305 as specified in [RFC-7539]_ section 2.8. + 12 byte nonce, with the first 4 bytes set to zero. + +- Hash Function: SHA256 + Standard 32-byte hash, already used extensively in I2P. + + +Additions to the Framework +========================== + +This proposal defines the following enhancements to +Noise_XK_25519_ChaChaPoly_SHA256. These generally follow the guidelines in +[NOISE]_ section 13. + +1) Cleartext ephemeral keys are obfuscated with AES encryption using a known + key and IV. This is quicker than elligator2. + + + +New Cryptographic Primitives for I2P +==================================== + +None? +Investigate other hash functions to replace SHA256. + + + + +Processing overhead estimate +============================ + +TBD + + +Messages +======== + +All SSU2 messages are less than or equal to TBD bytes in length. The message +format is based on Noise messages, with modifications for framing and indistinguishability. +Implementations using standard Noise libraries may need to pre-process received +messages to/from the Noise message format. All encrypted fields are AEAD +ciphertexts. + + +The establishment sequence is as follows: + +.. raw:: html + + {% highlight %} +Alice Bob + + SessionRequest -------------------> + <------------------- SessionCreated + SessionConfirmed -----------------> +{% endhighlight %} + +Using Noise terminology, the establishment and data sequence is as follows: +(Payload Security Properties) + +.. raw:: html + + {% highlight lang='text' %} +XK(s, rs): Authentication Confidentiality + <- s + ... + -> e, es 0 2 + <- e, ee 2 1 + -> s, se 2 5 + <- 2 5 +{% endhighlight %} + + +Once a session has been established, Alice and Bob can exchange Data messages. + +All message types (SessionRequest, SessionCreated, SessionConfirmed, Data and +TimeSync) are specified in this section. + +Some notations:: + + - RH_A = Router Hash for Alice (32 bytes) + - RH_B = Router Hash for Bob (32 bytes) + + +Packet Header +--------------- + +All packets start with an obfuscated header. + +TBD + + + + + +Authenticated Encryption +------------------------ + +There are three separate authenticated encryption instances (CipherStates). +One during the handshake phase, and two (transmit and receive) for the data phase. +Each has its own key from a KDF. + +Encrypted/authenticated data will be represented as + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + + + | Encrypted and authenticated data | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ +{% endhighlight %} + + +ChaCha20/Poly1305 +````````````````` + +Encrypted and authenticated data format. + +Inputs to the encryption/decryption functions: + +.. raw:: html + + {% highlight lang='dataspec' %} + +k :: 32 byte cipher key, as generated from KDF + + nonce :: Counter-based nonce, 12 bytes. + Starts at 0 and incremented for each message. + First four bytes are always zero. + Last eight bytes are the counter, little-endian encoded. + Maximum value is 2**64 - 2. + Connection must be dropped and restarted after + it reaches that value. + The value 2**64 - 1 must never be sent. + + ad :: In handshake phase: + Associated data, 32 bytes. + The SHA256 hash of all preceding data. + In data phase: + Zero bytes + + data :: Plaintext data, 0 or more bytes + +{% endhighlight %} + +Output of the encryption function, input to the decryption function: + +.. raw:: html + + {% highlight lang='dataspec' %} + ++----+----+----+----+----+----+----+----+ + | | + + + + | ChaCha20 encrypted data | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + | Poly1305 Message Authentication Code | + + (MAC) + + | 16 bytes | + +----+----+----+----+----+----+----+----+ + + encrypted data :: Same size as plaintext data, 0 - 65519 bytes + + MAC :: Poly1305 message authentication code, 16 bytes + +{% endhighlight %} + +For ChaCha20, what is described here corresponds to [RFC-7539]_, which is also +used similarly in TLS [RFC-7905]_. + +Notes +````` +- Since ChaCha20 is a stream cipher, plaintexts need not be padded. + Additional keystream bytes are discarded. + +- The key for the cipher (256 bits) is agreed upon by means of the SHA256 KDF. + The details of the KDF for each message are in separate sections below. + + +AEAD Error Handling +``````````````````` +- In all messages, the AEAD message size is known in advance. + On an AEAD authentication failure, recipient must halt further message processing and close the + connection without responding. This should be an abnormal close (TCP RST). + +- For probing resistance, in Session Request, after an AEAD failure, Bob should + set a random timeout (range TBD) and then read a random number of bytes (range TBD) + before closing the socket. Bob should maintain a blacklist of IPs with + repeated failures. + + +Key Derivation Function (KDF) (for Session Request) +------------------------------------------------------- + +The KDF generates a handshake phase cipher key k from the DH result, +using HMAC-SHA256(key, data) as defined in [RFC-2104]_. +These are the InitializeSymmetric(), MixHash(), and MixKey() functions, +exactly as defined in the Noise spec. + +.. raw:: html + + {% highlight lang='text' %} + +This is the "e" message pattern: + + // Define protocol_name. + Set protocol_name = "Noise_XKaesobfse+hs2+hs3_25519_ChaChaPoly_SHA256" + (48 bytes, US-ASCII encoded, no NULL termination). + + // Define Hash h = 32 bytes + h = SHA256(protocol_name); + + Define ck = 32 byte chaining key. Copy the h data to ck. + Set ck = h + + Define rs = Bob's 32-byte static key as published in the RouterInfo + + // MixHash(null prologue) + h = SHA256(h); + + // up until here, can all be precalculated by Alice for all outgoing connections + + // Alice must validate that Bob's static key is a valid point on the curve here. + + // Bob static key + // MixHash(rs) + // || below means append + h = SHA256(h || rs); + + // up until here, can all be precalculated by Bob for all incoming connections + + This is the "e" message pattern: + + Alice generates her ephemeral DH key pair e. + + // Alice ephemeral key X + // MixHash(e.pubkey) + // || below means append + h = SHA256(h || e.pubkey); + + // h is used as the associated data for the AEAD in Session Request + // Retain the Hash h for the Session Created KDF + + + End of "e" message pattern. + + This is the "es" message pattern: + + // DH(e, rs) == DH(s, re) + Define input_key_material = 32 byte DH result of Alice's ephemeral key and Bob's static key + Set input_key_material = X25519 DH result + + // MixKey(DH()) + + Define temp_key = 32 bytes + Define HMAC-SHA256(key, data) as in [RFC-2104]_ + // Generate a temp key from the chaining key and DH result + // ck is the chaining key, defined above + temp_key = HMAC-SHA256(ck, input_key_material) + // overwrite the DH result in memory, no longer needed + input_key_material = (all zeros) + + // Output 1 + // Set a new chaining key from the temp key + // byte() below means a single byte + ck = HMAC-SHA256(temp_key, byte(0x01)). + + // Output 2 + // Generate the cipher key k + Define k = 32 bytes + // || below means append + // byte() below means a single byte + k = HMAC-SHA256(temp_key, ck || byte(0x02)). + // overwrite the temp_key in memory, no longer needed + temp_key = (all zeros) + + // retain the chaining key ck for Session Created KDF + + + End of "es" message pattern. + +{% endhighlight %} + + + + +1) SessionRequest +------------------ + +Alice sends to Bob. + +Noise content: Alice's ephemeral key X +Noise payload: 16 byte option block +Non-noise payload: Random padding + +(Payload Security Properties) + +.. raw:: html + + {% highlight lang='text' %} +XK(s, rs): Authentication Confidentiality + -> e, es 0 2 + + Authentication: None (0). + This payload may have been sent by any party, including an active attacker. + + Confidentiality: 2. + Encryption to a known recipient, forward secrecy for sender compromise + only, vulnerable to replay. This payload is encrypted based only on DHs + involving the recipient's static key pair. If the recipient's static + private key is compromised, even at a later date, this payload can be + decrypted. This message can also be replayed, since there's no ephemeral + contribution from the recipient. + + "e": Alice generates a new ephemeral key pair and stores it in the e + variable, writes the ephemeral public key as cleartext into the + message buffer, and hashes the public key along with the old h to + derive a new h. + + "es": A DH is performed between the Alice's ephemeral key pair and the + Bob's static key pair. The result is hashed along with the old ck to + derive a new ck and k, and n is set to zero. + + +{% endhighlight %} + +The X value is encrypted to ensure payload indistinguishably +and uniqueness, which are necessary DPI countermeasures. +We use AES encryption to achieve this, +rather than more complex and slower alternatives such as elligator2. +Asymmetric encryption to Bob's router public key would be far too slow. +AES encryption uses Bob's router hash as the key and Bob's IV as published +in the network database. + +AES encryption is for DPI resistance only. +Any party knowing Bob's router hash, and IV, which are published in the network database, +may decrypt the X value in this message. + +The padding is not encrypted by Alice. +It may be necessary for Bob to decrypt the padding, +to inhibit timing attacks. + + +Raw contents: + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + obfuscated with RH_B + + | AES-CBC-256 encrypted X | + + (32 bytes) + + | | + + + + | | + +----+----+----+----+----+----+----+----+ + | | + + + + | ChaChaPoly frame | + + (32 bytes) + + | k defined in KDF for Session Request | + + n = 0 + + | see KDF for associated data | + +----+----+----+----+----+----+----+----+ + | unencrypted authenticated | + ~ padding (optional) ~ + | length defined in options block | + +----+----+----+----+----+----+----+----+ + + X :: 32 bytes, AES-256-CBC encrypted X25519 ephemeral key, little endian + key: RH_B + iv: As published in Bobs network database entry + + padding :: Random data, 0 or more bytes. + Total message length must be 65535 bytes or less. + Total message length must be 287 bytes or less if + Bob is publishing his address as NTCP + (see Version Detection section below). + Alice and Bob will use the padding data in the KDF for Session Created. + It is authenticated so that any tampering will cause the + next message to fail. + +{% endhighlight %} + +Unencrypted data (Poly1305 authentication tag not shown): + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + + + | X | + + (32 bytes) + + | | + + + + | | + +----+----+----+----+----+----+----+----+ + | options | + + (16 bytes) + + | | + +----+----+----+----+----+----+----+----+ + | unencrypted authenticated | + + padding (optional) + + | length defined in options block | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + X :: 32 bytes, X25519 ephemeral key, little endian + + options :: options block, 16 bytes, see below + + padding :: Random data, 0 or more bytes. + Total message length must be 65535 bytes or less. + Total message length must be 287 bytes or less if + Bob is publishing his address as "NTCP" + (see Version Detection section below) + Alice and Bob will use the padding data in the KDF for Session Created. + It is authenticated so that any tampering will cause the + next message to fail. + +{% endhighlight %} + +Options block: +Note: All fields are big-endian. + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | id | ver| padLen | m3p2len | Rsvd(0) | + +----+----+----+----+----+----+----+----+ + | tsA | Reserved (0) | + +----+----+----+----+----+----+----+----+ + + id :: 1 byte, the network ID (currently 2, except for test networks) + As of 0.9.42. See proposal 147. + + ver :: 1 byte, protocol version (currently 2) + + padLen :: 2 bytes, length of the padding, 0 or more + Min/max guidelines TBD. Random size from 0 to 31 bytes minimum? + (Distribution to be determined, see Appendix A.) + + m3p2Len :: 2 bytes, length of the the second AEAD frame in SessionConfirmed + See notes below + + Rsvd :: 2 bytes, set to 0 for compatibility with future options + + tsA :: 4 bytes, Unix timestamp, unsigned seconds. + Wraps around in 2106 + + Reserved :: 4 bytes, set to 0 for compatibility with future options + +{% endhighlight %} + +Notes +````` +- When the published address is "NTCP", Bob supports both NTCP and SSU2 on the + same port. For compatibility, when initiating a connection to an address + published as "NTCP", Alice must limit the maximum size of this message, + including padding, to 287 bytes or less. This facilitates automatic protocol + identification by Bob. When published as "SSU2", there is no size + restriction. See the Published Addresses and Version Detection sections + below. + +- The unique X value in the initial AES block ensure that the ciphertext is + different for every session. + +- Bob must reject connections where the timestamp value is too far off from the + current time. Call the maximum delta time "D". Bob must maintain a local + cache of previously-used handshake values and reject duplicates, to prevent + replay attacks. Values in the cache must have a lifetime of at least 2*D. + The cache values are implementation-dependent, however the 32-byte X value + (or its encrypted equivalent) may be used. + +- Diffie-Hellman ephemeral keys may never be reused, to prevent cryptographic attacks, + and reuse will be rejected as a replay attack. + +- The "KE" and "auth" options must be compatible, i.e. the shared secret K must + be of the appropriate size. If more "auth" options are added, this could + implicitly change the meaning of the "KE" flag to use a different KDF or a + different truncation size. + +- Bob must validate that Alice's ephemeral key is a valid point on the curve + here. + +- Padding should be limited to a reasonable amount. Bob may reject connections + with excessive padding. Bob will specify his padding options in Session Created. + Min/max guidelines TBD. Random size from 0 to 31 bytes minimum? + (Distribution to be determined, see Appendix A.) + +- On any error, including AEAD, DH, timestamp, apparent replay, or key + validation failure, Bob must halt further message processing and close the + connection without responding. This should be an abnormal close (TCP RST). + For probing resistance, after an AEAD failure, Bob should + set a random timeout (range TBD) and then read a random number of bytes (range TBD), + before closing the socket. + +- DoS Mitigation: DH is a relatively expensive operation. As with the previous NTCP protocol, + routers should take all necessary measures to prevent CPU or connection exhaustion. + Place limits on maximum active connections and maximum connection setups in progress. + Enforce read timeouts (both per-read and total for "slowloris"). + Limit repeated or simultaneous connections from the same source. + Maintain blacklists for sources that repeatedly fail. + Do not respond to AEAD failure. + +- To facilitate rapid version detection and handshaking, implementations must + ensure that Alice buffers and then flushes the entire contents of the first + message at once, including the padding. This increases the likelihood that + the data will be contained in a single TCP packet (unless segmented by the OS + or middleboxes), and received all at once by Bob. Additionally, + implementations must ensure that Bob buffers and then flushes the entire + contents of the second message at once, including the padding. and that Bob + buffers and then flushes the entire contents of the third message at once. + This is also for efficiency and to ensure the effectiveness of the random + padding. + +- "ver" field: The overall Noise protocol, extensions, and NTCP protocol + including payload specifications, indicating SSU2. + This field may be used to indicate support for future changes. + +- Bob must fail the connection if any incoming data remains after validating + Session Request and reading in the padding. There should be no extra data from Alice, + as Bob has not responded with Session Created yet. + +- The network ID field is used to quickly identify cross-network connections. + If this field is nonzero, and does not match Bob's network ID, + Bob should disconnect and block future connections. + As of 0.9.42. See proposal 147 for more information. + + + +Key Derivation Function (KDF) (for Session Created and Session Confirmed part 1) +---------------------------------------------------------------------------------- + +.. raw:: html + + {% highlight lang='text' %} + + // take h saved from Session Request KDF + // MixHash(ciphertext) + h = SHA256(h || 32 byte encrypted payload from Session Request) + + // MixHash(padding) + // Only if padding length is nonzero + h = SHA256(h || random padding from Session Request) + + This is the "e" message pattern: + + Bob generates his ephemeral DH key pair e. + + // h is from KDF for Session Request + // Bob ephemeral key Y + // MixHash(e.pubkey) + // || below means append + h = SHA256(h || e.pubkey); + + // h is used as the associated data for the AEAD in Session Created + // Retain the Hash h for the Session Confirmed KDF + + End of "e" message pattern. + + This is the "ee" message pattern: + + // DH(e, re) + Define input_key_material = 32 byte DH result of Alice's ephemeral key and Bob's ephemeral key + Set input_key_material = X25519 DH result + // overwrite Alice's ephemeral key in memory, no longer needed + // Alice: + e(public and private) = (all zeros) + // Bob: + re = (all zeros) + + // MixKey(DH()) + + Define temp_key = 32 bytes + Define HMAC-SHA256(key, data) as in [RFC-2104]_ + // Generate a temp key from the chaining key and DH result + // ck is the chaining key, from the KDF for Session Request + temp_key = HMAC-SHA256(ck, input_key_material) + // overwrite the DH result in memory, no longer needed + input_key_material = (all zeros) + + // Output 1 + // Set a new chaining key from the temp key + // byte() below means a single byte + ck = HMAC-SHA256(temp_key, byte(0x01)). + + // Output 2 + // Generate the cipher key k + Define k = 32 bytes + // || below means append + // byte() below means a single byte + k = HMAC-SHA256(temp_key, ck || byte(0x02)). + // overwrite the temp_key in memory, no longer needed + temp_key = (all zeros) + + // retain the chaining key ck for Session Confirmed KDF + + End of "ee" message pattern. + +{% endhighlight %} + + +2) SessionCreated +------------------ + +Bob sends to Alice. + +Noise content: Bob's ephemeral key Y +Noise payload: 16 byte option block +Non-noise payload: Random padding + +(Payload Security Properties) + +.. raw:: html + + {% highlight lang='text' %} +XK(s, rs): Authentication Confidentiality + <- e, ee 2 1 + + Authentication: 2. + Sender authentication resistant to key-compromise impersonation (KCI). + The sender authentication is based on an ephemeral-static DH ("es" or "se") + between the sender's static key pair and the recipient's ephemeral key pair. + Assuming the corresponding private keys are secure, this authentication cannot be forged. + + Confidentiality: 1. + Encryption to an ephemeral recipient. + This payload has forward secrecy, since encryption involves an ephemeral-ephemeral DH ("ee"). + However, the sender has not authenticated the recipient, + so this payload might be sent to any party, including an active attacker. + + + "e": Bob generates a new ephemeral key pair and stores it in the e variable, + writes the ephemeral public key as cleartext into the message buffer, + and hashes the public key along with the old h to derive a new h. + + "ee": A DH is performed between the Bob's ephemeral key pair and the Alice's ephemeral key pair. + The result is hashed along with the old ck to derive a new ck and k, and n is set to zero. + +{% endhighlight %} + +The Y value is encrypted to ensure payload indistinguishably and uniqueness, +which are necessary DPI countermeasures. We use AES encryption to achieve +this, rather than more complex and slower alternatives such as elligator2. +Asymmetric encryption to Alice's router public key would be far too slow. AES +encryption uses Bob's router hash as the key and the AES state from Session Request +(which was initialized with Bob's IV as published in the network database). + +AES encryption is for DPI resistance only. Any party knowing Bob's router hash +and IV, which are published in the network database, and captured the first 32 +bytes of Session Request, may decrypt the Y value in this message. + + +Raw contents: + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + obfuscated with RH_B + + | AES-CBC-256 encrypted Y | + + (32 bytes) + + | | + + + + | | + +----+----+----+----+----+----+----+----+ + | ChaChaPoly frame | + + Encrypted and authenticated data + + | 32 bytes | + + k defined in KDF for Session Created + + | n = 0; see KDF for associated data | + + + + | | + +----+----+----+----+----+----+----+----+ + | unencrypted authenticated | + + padding (optional) + + | length defined in options block | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + Y :: 32 bytes, AES-256-CBC encrypted X25519 ephemeral key, little endian + key: RH_B + iv: Using AES state from Session Request + +{% endhighlight %} + +Unencrypted data (Poly1305 auth tag not shown): + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + + + | Y | + + (32 bytes) + + | | + + + + | | + +----+----+----+----+----+----+----+----+ + | options | + + (16 bytes) + + | | + +----+----+----+----+----+----+----+----+ + | unencrypted authenticated | + + padding (optional) + + | length defined in options block | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + Y :: 32 bytes, X25519 ephemeral key, little endian + + options :: options block, 16 bytes, see below + + padding :: Random data, 0 or more bytes. + Total message length must be 65535 bytes or less. + Alice and Bob will use the padding data in the KDF for Session Confirmed part 1. + It is authenticated so that any tampering will cause the + next message to fail. + +{% endhighlight %} + +Notes +````` + +- Alice must validate that Bob's ephemeral key is a valid point on the curve + here. + +- Padding should be limited to a reasonable amount. + Alice may reject connections with excessive padding. + Alice will specify her padding options in Session Confirmed. + Min/max guidelines TBD. Random size from 0 to 31 bytes minimum? + (Distribution to be determined, see Appendix A.) + +- On any error, including AEAD, DH, timestamp, apparent replay, or key + validation failure, Alice must halt further message processing and close the + connection without responding. This should be an abnormal close (TCP RST). + +- To facilitate rapid handshaking, implementations must ensure that Bob buffers + and then flushes the entire contents of the first message at once, including + the padding. This increases the likelihood that the data will be contained + in a single TCP packet (unless segmented by the OS or middleboxes), and + received all at once by Alice. This is also for efficiency and to ensure the + effectiveness of the random padding. + +- Alice must fail the connection if any incoming data remains after validating + Session Created and reading in the padding. There should be no extra data from Bob, + as Alice has not responded with Session Confirmed yet. + + +Options block: +Note: All fields are big-endian. + +.. raw:: html + + {% highlight lang='dataspec' %} + ++----+----+----+----+----+----+----+----+ + | Rsvd(0) | padLen | Reserved (0) | + +----+----+----+----+----+----+----+----+ + | tsB | Reserved (0) | + +----+----+----+----+----+----+----+----+ + + Reserved :: 10 bytes total, set to 0 for compatibility with future options + + padLen :: 2 bytes, big endian, length of the padding, 0 or more + Min/max guidelines TBD. Random size from 0 to 31 bytes minimum? + (Distribution to be determined, see Appendix A.) + + tsB :: 4 bytes, big endian, Unix timestamp, unsigned seconds. + Wraps around in 2106 + +{% endhighlight %} + +Notes +````` +- Alice must reject connections where the timestamp value is too far off from + the current time. Call the maximum delta time "D". Alice must maintain a + local cache of previously-used handshake values and reject duplicates, to + prevent replay attacks. Values in the cache must have a lifetime of at least + 2*D. The cache values are implementation-dependent, however the 32-byte Y + value (or its encrypted equivalent) may be used. + +Issues +`````` +- Include min/max padding options here? + + + +Encryption for for Session Confirmed part 1, using Session Created KDF) +--------------------------------------------------------------------------- + +.. raw:: html + + {% highlight lang='text' %} + + // take h saved from Session Created KDF + // MixHash(ciphertext) + h = SHA256(h || 24 byte encrypted payload from Session Created) + + // MixHash(padding) + // Only if padding length is nonzero + h = SHA256(h || random padding from Session Created) + // h is used as the associated data for the AEAD in Session Confirmed part 1, below + + This is the "s" message pattern: + + Define s = Alice's static public key, 32 bytes + + // EncryptAndHash(s.publickey) + // EncryptWithAd(h, s.publickey) + // AEAD_ChaCha20_Poly1305(key, nonce, associatedData, data) + // k is from Session Request + // n is 1 + ciphertext = AEAD_ChaCha20_Poly1305(k, n++, h, s.publickey) + // MixHash(ciphertext) + // || below means append + h = SHA256(h || ciphertext); + + // h is used as the associated data for the AEAD in Session Confirmed part 2 + + End of "s" message pattern. + +{% endhighlight %} + + +Key Derivation Function (KDF) (for Session Confirmed part 2) +-------------------------------------------------------------- + +.. raw:: html + + {% highlight lang='text' %} + +This is the "se" message pattern: + + // DH(s, re) == DH(e, rs) + Define input_key_material = 32 byte DH result of Alice's static key and Bob's ephemeral key + Set input_key_material = X25519 DH result + // overwrite Bob's ephemeral key in memory, no longer needed + // Alice: + re = (all zeros) + // Bob: + e(public and private) = (all zeros) + + // MixKey(DH()) + + Define temp_key = 32 bytes + Define HMAC-SHA256(key, data) as in [RFC-2104]_ + // Generate a temp key from the chaining key and DH result + // ck is the chaining key, from the KDF for Session Request + temp_key = HMAC-SHA256(ck, input_key_material) + // overwrite the DH result in memory, no longer needed + input_key_material = (all zeros) + + // Output 1 + // Set a new chaining key from the temp key + // byte() below means a single byte + ck = HMAC-SHA256(temp_key, byte(0x01)). + + // Output 2 + // Generate the cipher key k + Define k = 32 bytes + // || below means append + // byte() below means a single byte + k = HMAC-SHA256(temp_key, ck || byte(0x02)). + + // h from Session Confirmed part 1 is used as the associated data for the AEAD in Session Confirmed part 2 + + // EncryptAndHash(payload) + // EncryptWithAd(h, payload) + // AEAD_ChaCha20_Poly1305(key, nonce, associatedData, data) + // n is 0 + ciphertext = AEAD_ChaCha20_Poly1305(k, n++, h, payload) + // MixHash(ciphertext) + // || below means append + h = SHA256(h || ciphertext); + + // retain the chaining key ck for the data phase KDF + // retain the hash h for the data phase Additional Symmetric Key (SipHash) KDF + + End of "se" message pattern. + + // overwrite the temp_key in memory, no longer needed + temp_key = (all zeros) + +{% endhighlight %} + + +3) SessionConfirmed +-------------------- + +Alice sends to Bob. + +Noise content: Alice's static key +Noise payload: Alice's RouterInfo and random padding +Non-noise payload: none + +(Payload Security Properties) + + +.. raw:: html + + {% highlight lang='text' %} +XK(s, rs): Authentication Confidentiality + -> s, se 2 5 + + Authentication: 2. + Sender authentication resistant to key-compromise impersonation (KCI). The + sender authentication is based on an ephemeral-static DH ("es" or "se") + between the sender's static key pair and the recipient's ephemeral key + pair. Assuming the corresponding private keys are secure, this + authentication cannot be forged. + + Confidentiality: 5. + Encryption to a known recipient, strong forward secrecy. This payload is + encrypted based on an ephemeral-ephemeral DH as well as an ephemeral-static + DH with the recipient's static key pair. Assuming the ephemeral private + keys are secure, and the recipient is not being actively impersonated by an + attacker that has stolen its static private key, this payload cannot be + decrypted. + + "s": Alice writes her static public key from the s variable into the + message buffer, encrypting it, and hashes the output along with the old h + to derive a new h. + + "se": A DH is performed between the Alice's static key pair and the Bob's + ephemeral key pair. The result is hashed along with the old ck to derive a + new ck and k, and n is set to zero. + +{% endhighlight %} + +This contains two ChaChaPoly frames. +The first is Alice's encrypted static public key. +The second is the Noise payload: Alice's encrypted RouterInfo, optional +options, and optional padding. They use different keys, because the MixKey() +function is called in between. + + +Raw contents: + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + ChaChaPoly frame (48 bytes) + + | Encrypted and authenticated | + + Alice static key S + + | (32 bytes) | + + + + | k defined in KDF for Session Created | + + n = 1 + + | see KDF for associated data | + + + + | | + +----+----+----+----+----+----+----+----+ + | | + + Length specified in Session Request + + | | + + ChaChaPoly frame + + | Encrypted and authenticated | + + + + | Alice RouterInfo | + + using block format 2 + + | Alice Options (optional) | + + using block format 1 + + | Arbitrary padding | + + using block format 254 + + | | + + + + | k defined in KDF for | + + Session Confirmed part 2 + + | n = 0 | + + see KDF for associated data + + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + S :: 32 bytes, ChaChaPoly encrypted Alice's X25519 static key, little endian + inside 48 byte ChaChaPoly frame + +{% endhighlight %} + +Unencrypted data (Poly1305 auth tags not shown): + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | | + + + + | S | + + Alice static key + + | (32 bytes) | + + + + | | + + + + +----+----+----+----+----+----+----+----+ + | | + + + + | | + + + + | Alice RouterInfo block | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + | | + + Optional Options block + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + | | + + Optional Padding block + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + S :: 32 bytes, Alice's X25519 static key, little endian + + +{% endhighlight %} + + +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. + +- 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. + +- 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, + and if the older version is less than XXX old (see key rotate time below) + +- Bob must validate that Alice's static key is a valid point on the curve here. + +- Options should be included, to specify padding parameters. + +- On any error, including AEAD, RI, DH, timestamp, or key validation failure, + Bob must halt further message processing and close the connection without + responding. This should be an abnormal close (TCP RST). + +- To facilitate rapid handshaking, implementations must ensure that Alice + buffers and then flushes the entire contents of the third message at once, + including both AEAD frames. + This increases the likelihood that the data will be contained in a single TCP + packet (unless segmented by the OS or middleboxes), and received all at once + by Bob. This is also for efficiency and to ensure the effectiveness of the + random padding. + +- Message 3 part 2 frame length: The length of this frame (including MAC) is + sent by Alice in Session Request. See that message for important notes on allowing + enough room for padding. + +- Message 3 part 2 frame content: This format of this frame is the same as the + format of data phase frames, except that the length of the frame is sent + by Alice in Session Request. See below for the data phase frame format. + The frame must contain 1 to 3 blocks in the following order: + 1) Alice's Router Info block (required) + 2) Options block (optional) + 3) Padding block (optional) + This frame must never contain any other block type. + +- Message 3 part 2 padding is not required if Alice appends a data phase frame + (optionally containing padding) to the end of Session Confirmed and sends both at once, + as it will appear as one big stream of bytes to an observer. + 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; + part 1 is 48 bytes so part 2 max frame length is 65487; + part 2 max plaintext length excluding MAC is 65471. + + +Key Derivation Function (KDF) (for data phase) +---------------------------------------------- + +The data phase uses a zero-length associated data input. + + +The KDF generates two cipher keys k_ab and k_ba from the chaining key ck, +using HMAC-SHA256(key, data) as defined in [RFC-2104]_. +This is the Split() function, exactly as defined in the Noise spec. + +.. raw:: html + + {% highlight lang='text' %} + +ck = from handshake phase + + // k_ab, k_ba = HKDF(ck, zerolen) + // ask_master = HKDF(ck, zerolen, info="ask") + + // zerolen is a zero-length byte array + temp_key = HMAC-SHA256(ck, zerolen) + // overwrite the chaining key in memory, no longer needed + ck = (all zeros) + + // Output 1 + // cipher key, for Alice transmits to Bob (Noise doesn't make clear which is which, but Java code does) + k_ab = HMAC-SHA256(temp_key, byte(0x01)). + + // Output 2 + // cipher key, for Bob transmits to Alice (Noise doesn't make clear which is which, but Java code does) + k_ba = HMAC-SHA256(temp_key, k_ab || byte(0x02)). + + +{% endhighlight %} + + + + +4) Data Phase +------------- + +Noise payload: As defined below, including random padding +Non-noise payload: none + +Starting with the 2nd part of Session Confirmed, all messages are inside +an authenticated and encrypted ChaChaPoly "frame" +with a prepended two-byte obfuscated length. +All padding is inside the frame. +Inside the frame is a standard format with zero or more "blocks". +Each block has a one-byte type and a two-byte length. +Types include date/time, I2NP message, options, termination, and padding. + +Note: Bob may, but is not required, to send his RouterInfo to Alice as +his first message to Alice in the data phase. + +(Payload Security Properties) + + +.. raw:: html + + {% highlight lang='text' %} +XK(s, rs): Authentication Confidentiality + <- 2 5 + -> 2 5 + + Authentication: 2. + Sender authentication resistant to key-compromise impersonation (KCI). + The sender authentication is based on an ephemeral-static DH ("es" or "se") + between the sender's static key pair and the recipient's ephemeral key pair. + Assuming the corresponding private keys are secure, this authentication cannot be forged. + + Confidentiality: 5. + Encryption to a known recipient, strong forward secrecy. + This payload is encrypted based on an ephemeral-ephemeral DH as well as + an ephemeral-static DH with the recipient's static key pair. + Assuming the ephemeral private keys are secure, and the recipient is not being actively impersonated + by an attacker that has stolen its static private key, this payload cannot be decrypted. + +{% endhighlight %} + +Notes +````` +- For efficiency and to minimize identification of the length field, + implementations must ensure that the sender buffers and then flushes the entire contents + of data messages at once, including the length field and the AEAD frame. + This increases the likelihood that the data will be contained in a single TCP packet + (unless segmented by the OS or middleboxes), and received all at once the other party. + This is also for efficiency and to ensure the effectiveness of the random padding. + +- The router may choose to terminate the session on AEAD error, or may continue to attempt communications. + If continuing, the router should terminate after repeated errors. + + + + + +Raw contents +```````````` + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + |obf size | | + +----+----+ + + | | + + ChaChaPoly frame + + | Encrypted and authenticated | + + key is k_ab for Alice to Bob + + | key is k_ba for Bob to Alice | + + as defined in KDF for data phase + + | n starts at 0 and increments | + + for each frame in that direction + + | no associated data | + + 16 bytes minimum + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + obf size :: 2 bytes length obfuscated with SipHash + when de-obfuscated: 16 - 65535 + + Minimum size including length field is 18 bytes. + Maximum size including length field is 65537 bytes. + Obfuscated length is 2 bytes. + Maximum ChaChaPoly frame is 65535 bytes. + +{% endhighlight %} + + +Unencrypted data +```````````````` +There are zero or more blocks in the encrypted frame. +Each block contains a one-byte identifier, a two-byte length, +and zero or more bytes of data. + +For extensibility, receivers must ignore blocks with unknown identifiers, +and treat them as padding. + +Encrypted data is 65535 bytes max, including a 16-byte authentication header, +so the max unencrypted data is 65519 bytes. + +(Poly1305 auth tag not shown): + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + |blk | size | data | + +----+----+----+ + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + |blk | size | data | + +----+----+----+ + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + ~ . . . ~ + + blk :: 1 byte + 0 for datetime + 1 for options + 2 for RouterInfo + 3 for I2NP message + 4 for termination + 224-253 reserved for experimental features + 254 for padding + 255 reserved for future extension + size :: 2 bytes, big endian, size of data to follow, 0 - 65516 + data :: the data + + Maximum ChaChaPoly frame is 65535 bytes. + Poly1305 tag is 16 bytes + Maximum total block size is 65519 bytes + Maximum single block size is 65519 bytes + Block type is 1 byte + Block length is 2 bytes + Maximum single block data size is 65516 bytes. + +{% endhighlight %} + + +Block Ordering Rules +```````````````````` +In the Session Confirmed part 2, order must be: +RouterInfo, followed by Options if present, followed by Padding if present. +No other blocks are allowed. + +In the data phase, order is unspecified, except for the +following requirements: +Padding, if present, must be the last block. +Termination, if present, must be the last block except for Padding. + +There may be multiple I2NP blocks in a single frame. +Multiple Padding blocks are not allowed in a single frame. +Other block types probably won't have multiple blocks in +a single frame, but it is not prohibited. + + + +DateTime +```````` +Special case for time synchronization: + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+ + | 0 | 4 | timestamp | + +----+----+----+----+----+----+----+ + + blk :: 0 + size :: 2 bytes, big endian, value = 4 + timestamp :: Unix timestamp, unsigned seconds. + Wraps around in 2106 + +{% endhighlight %} + + +Options +``````` +Pass updated options. +Options include: Min and max padding. + +Options block will be variable length. + + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | 1 | size |tmin|tmax|rmin|rmax|tdmy| + +----+----+----+----+----+----+----+----+ + |tdmy| rdmy | tdelay | rdelay | | + ~----+----+----+----+----+----+----+ ~ + | more_options | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + blk :: 1 + size :: 2 bytes, big endian, size of options to follow, 12 bytes minimum + + tmin, tmax, rmin, rmax :: requested padding limits + tmin and rmin are for desired resistance to traffic analysis. + tmax and rmax are for bandwidth limits. + tmin and tmax are the transmit limits for the router sending this options block. + rmin and rmax are the receive limits for the router sending this options block. + Each is a 4.4 fixed-point float representing 0 to 15.9375 + (or think of it as an unsigned 8-bit integer divided by 16.0). + This is the ratio of padding to data. Examples: + Value of 0x00 means no padding + Value of 0x01 means add 6 percent padding + Value of 0x10 means add 100 percent padding + Value of 0x80 means add 800 percent (8x) padding + Alice and Bob will negotiate the minimum and maximum in each direction. + These are guidelines, there is no enforcement. + Sender should honor receiver's maximum. + Sender may or may not honor receiver's minimum, within bandwidth constraints. + + tdmy: Max dummy traffic willing to send, 2 bytes big endian, bytes/sec average + rdmy: Requested dummy traffic, 2 bytes big endian, bytes/sec average + tdelay: Max intra-message delay willing to insert, 2 bytes big endian, msec average + rdelay: Requested intra-message delay, 2 bytes big endian, msec average + + Padding distribution specified as additional parameters? + Random delay specified as additional parameters? + + more_options :: Format TBD + +{% endhighlight %} + + +Options Issues +`````````````` +- Options negotiation is TBD. + + +RouterInfo +`````````` +Pass Alice's RouterInfo to Bob. +Used in Session Confirmed part 2. +Pass Alice's RouterInfo to Bob, or Bob's to Alice. +Used optionally in the data phase. + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | 2 | size |flg | RouterInfo | + +----+----+----+----+ + + | (Alice RI in handshake msg 3 part 2) | + ~ (Alice, Bob, or third-party ~ + | RI in data phase) | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + blk :: 2 + size :: 2 bytes, big endian, size of flag + router info to follow + flg :: 1 byte flags + bit order: 76543210 + bit 0: 0 for local store, 1 for flood request + bits 7-1: Unused, set to 0 for future compatibility + routerinfo :: Alice's or Bob's RouterInfo + + +{% endhighlight %} + +Notes +````` +- When used in the data phase, receiver (Alice or Bob) shall validate that + it's the same Router Hash as originally sent (for Alice) or sent to (for Bob). + Then, treat it as a local I2NP DatabaseStore Message. Validate signature, + validate more recent timestamp, and store in the local netdb. + If the flag bit 0 is 1, and the receiving party is floodfill, + treat it as a DatabaseStore Message with a nonzero reply token, + and flood it to the nearest floodfills. + +- The Router Info is NOT compressed with gzip + (unlike in a DatabaseStore Message, where it is) + +- Flooding must not be requested unless there are published + RouterAddresses in the RouterInfo. The receiving router + must not flood the RouterInfo unless there are published + RouterAddresses in it. + +- Implementers must ensure that when reading a block, + malformed or malicious data will not cause reads to + overrun into the next block. + +- This protocol does not provide an acknowledgement that the RouterInfo + was received, stored, or flooded (either in the handshake or data phase). + If acknowledgement is desired, and the receiver is floodfill, + the sender should instead send a standard I2NP DatabaseStoreMessage + with a reply token. + + +Issues +`````` +- Could also be used in data phase, instead of a I2NP DatabaseStoreMessage. + For example, Bob could use it to start off the data phase. + +- Is it allowed for this to contain the RI for routers other than the + originator, as a general replacement for DatabaseStoreMessages, + e.g. for flooding by floodfills? + + +I2NP Message +```````````` + +An single I2NP message with a modified header. +I2NP messages may not be fragmented across blocks or +across ChaChaPoly frames. + +This uses the first 9 bytes from the standard NTCP I2NP header, +and removes the last 7 bytes of the header, as follows: +truncate the expiration from 8 to 4 bytes, +remove the 2 byte length (use the block size - 9), +and remove the one-byte SHA256 checksum. + + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | 3 | size |type| msg id | + +----+----+----+----+----+----+----+----+ + | short exp | message | + +----+----+----+----+ + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + blk :: 3 + size :: 2 bytes, big endian, size of type + msg id + exp + message to follow + I2NP message body size is (size - 9). + type :: 1 byte, I2NP msg type, see I2NP spec + msg id :: 4 bytes, big endian, I2NP message ID + short exp :: 4 bytes, big endian, I2NP message expiration, Unix timestamp, unsigned seconds. + Wraps around in 2106 + message :: I2NP message body + +{% endhighlight %} + +Notes +````` +- Implementers must ensure that when reading a block, + malformed or malicious data will not cause reads to + overrun into the next block. + + + +Termination +``````````` +Drop the connection. +This must be the last non-padding block in the frame. + + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | 4 | size | valid data frames | + +----+----+----+----+----+----+----+----+ + received | rsn| addl data | + +----+----+----+----+ + + ~ . . . ~ + +----+----+----+----+----+----+----+----+ + + blk :: 4 + size :: 2 bytes, big endian, value = 9 or more + valid data frames received :: The number of valid AEAD data phase frames received + (current receive nonce value) + 0 if error occurs in handshake phase + 8 bytes, big endian + rsn :: reason, 1 byte: + 0: normal close or unspecified + 1: termination received + 2: idle timeout + 3: router shutdown + 4: data phase AEAD failure + 5: incompatible options + 6: incompatible signature type + 7: clock skew + 8: padding violation + 9: AEAD framing error + 10: payload format error + 11: Session Request error + 12: Session Created error + 13: Session Confirmed error + 14: intra-frame read timeout + 15: RI signature verification fail + 16: s parameter missing, invalid, or mismatched in RouterInfo + 17: banned + addl data :: optional, 0 or more bytes, for future expansion, debugging, + or reason text. + Format unspecified and may vary based on reason code. + +{% endhighlight %} + +Notes +````` +Not all reasons may actually be used, implementation dependent. +Handshake failures will generally result in a close with TCP RST instead. +See notes in handshake message sections above. +Additional reasons listed are for consistency, logging, debugging, or if policy changes. + + + + +Padding +``````` +This is for padding inside AEAD frames. +Padding for messages 1 and 2 are outside AEAD frames. +All padding for Session Confirmed and the data phase are inside AEAD frames. + +Padding inside AEAD should roughly adhere to the negotiated parameters. +Bob sent his requested tx/rx min/max parameters in Session Created. +Alice sent her requested tx/rx min/max parameters in Session Confirmed. +Updated options may be sent during the data phase. +See options block information above. + +If present, this must be the last block in the frame. + + + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + |254 | size | padding | + +----+----+----+ + + | | + ~ . . . ~ + | | + +----+----+----+----+----+----+----+----+ + + blk :: 254 + size :: 2 bytes, big endian, size of padding to follow + padding :: random data + +{% endhighlight %} + +Notes +````` +- Padding strategies TBD. +- Minimum padding TBD. +- Padding-only frames are allowed. +- Padding defaults TBD. +- See options block for padding parameter negotiation +- See options block for min/max padding parameters +- Noise limits messages to 64KB. If more padding is necessary, send multiple frames. +- Router response on violation of negotiated padding is implementation-dependent. + + +Other block types +````````````````` +Implementations should ignore unknown block types for +forward compatibility, except in Session Confirmed part 2, where +unknown blocks are not allowed. + + +Future work +``````````` +- The padding length is either to be decided on a per-message basis and + estimates of the length distribution, or random delays should be added. + These countermeasures are to be included to resist DPI, as message sizes + would otherwise reveal that I2P traffic is being carried by the transport + protocol. The exact padding scheme is an area of future work, Appendix A + provides more information on the topic. + + +5) Termination +-------------- + +Connections may be terminated via normal or abnormal TCP socket close, +or, as Noise recommends, an explicit termination message. +The explicit termination message is defined in the data phase above. + +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. + + +Other Messages +================= + + +Peer Test +---------- + +TBD + + +Relay +------- + +Relay Request, Response, Intro + +TBD + + + + +Congestion Control +==================== + +Sequence numbers, acks, backoff, retransmission + + + + + + +Published Router Info +===================== + + +Published Addresses +------------------- + + +The published RouterAddress (part of the RouterInfo) will have a +protocol identifier of either "SSU" or "SSU2". + +The RouterAddress must contain "host" and "port" options, as in +the current SSU protocol. + +The RouterAddress must contain three options +to indicate SSU2 support: + +- s=(Base64 key) + The current Noise static public key (s) for this RouterAddress. + Base 64 encoded using the standard I2P Base 64 alphabet. + 32 bytes in binary, 44 bytes as Base 64 encoded, + little-endian X25519 public key. + +- i=(Base64 IV) + The current IV for encrypting the X value in Session Request for this RouterAddress. + Base 64 encoded using the standard I2P Base 64 alphabet. + 16 bytes in binary, 24 bytes as Base 64 encoded, + big-endian. + +- v=2 + The current version (2). + When published as "SSU", additional support for version 1 is implied. + Support for future versions will be with comma-separated values, + e.g. v=2,3 + Implementation should verify compatibility, including multiple + versions if a comma is present. Comma-separated versions must + be in numerical order. + +Alice must verify that all three options are present and valid +before connecting using the SSU2 protocol. + +When published as "SSU" with "s", "i", and "v" options, +the router must accept incoming connections on that host and port +for both SSU and SSU2 protocols, and automatically detect the protocol +version. + +When published as "SSU2" with "s", "i", and "v" options, +the router accepts incoming connections on that host and port +for the SSU2 protocol only. + +If a router supports both SSU1 and SSU2 connections but +does not implement automatic version detection for incoming connections, +it must advertise both "SSU" and "SSU2" addresses, and include +the SSU2 options in the "SSU2" address only. +The router should set a lower cost value (higher priority) +in the "SSU2" address than the "SSU" address, so SSU2 is preferred. + +If multiple SSU2 RouterAddresses (either as "SSU" or "SSU2") are published +in the same RouterInfo (for additional IP addresses or ports), +all addresses specifying the same port must contain the identical SSU2 options and values. +In particular, all must contain the same static key and iv. + + + +Unpublished SSU2 Address +------------------------- + +If Alice does not publish her SSU2 address (as "SSU" or "SSU2") for incoming connections, +she must publish a "SSU2" router address containing only her static key and SSU2 version, +so that Bob may validate the key after receiving Alice's RouterInfo in Session Confirmed part 2. + +- s=(Base64 key) + As defined above for published addresses. + +- v=2 + As defined above for published addresses. + +This router address will not contain "i", "host" or "port" options, +as these are not required for outbound SSU2 connections. +The published cost for this address does not strictly matter, as it is inbound only; +however, it may be helpful to other routers if the cost is set higher (lower priority) +than other addresses. The suggested value is 14. + +Alice may also simply add the "s" and "v" options to an existing published "SSU" address. + + + +Public Key and IV Rotation +-------------------------- + +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 +connections will continue to work, and restart times are not exposed. Routers +must persistently store, or otherwise determine, last-shutdown time, so that +the previous downtime may be calculated at startup. + +Subject to concerns about exposing restart times, routers may rotate this key or IV +at startup if the router was previously down for some time (a couple hours at +least). + +If the router has any published SSU2 RouterAddresses (as SSU or SSU2), the +minimum downtime before rotation should be much longer, for example one month, +unless the local IP address has changed or the router "rekeys". + +If the router has any published SSU RouterAddresses, but not SSU2 (as SSU or +SSU2) the minimum downtime before rotation should be longer, for example one +day, unless the local IP address has changed or the router "rekeys". This +applies even if the published SSU address has introducers. + +If the router does not have any published RouterAddresses (SSU, SSU2, or +SSU), the minimum downtime before rotation may be as short as two hours, even +if the IP address changes, unless the router "rekeys". + +If the router "rekeys" to a different Router Hash, it should generate a new +noise key and IV as well. + +Implementations must be aware that changing the static public key or IV will prohibit +incoming SSU2 connections from routers that have cached an older RouterInfo. +RouterInfo publishing, tunnel peer selection (including both OBGW and IB +closest hop), zero-hop tunnel selection, transport selection, and other +implementation strategies must take this into account. + +IV rotation is subject to identical rules as key rotation, except that IVs are not present +except in published RouterAddresses, so there is no IV for hidden or firewalled +routers. If anything changes (version, key, options?) it is recommended that +the IV change as well. + +Note: The minimum downtime before rekeying may be modified to ensure network +health, and to prevent reseeding by a router down for a moderate amount of +time. + + + + +Identity Hiding +``````````````` +Deniability is not a goal. See overview above. + +Each pattern is assigned properties describing the confidentiality supplied to +the initiator's static public key, and to the responder's static public key. +The underlying assumptions are that ephemeral private keys are secure, and that +parties abort the handshake if they receive a static public key from the other +party which they don't trust. + +This section only considers identity leakage through static public key fields +in handshakes. Of course, the identities of Noise participants might be +exposed through other means, including payload fields, traffic analysis, or +metadata such as IP addresses. + +Alice: (8) Encrypted with forward secrecy to an authenticated party. + +Bob: (3) Not transmitted, but a passive attacker can check candidates for the +responder's private key and determine whether the candidate is correct. + +Bob publishes his static public key in the netdb. Alice may or may not? + + + +Issues +`````` +- If Bob changes his static key, could fallback to a "XX" pattern? + + +Version Detection +================= + +TBD + + +Variants, Fallbacks, and General Issues +======================================= + +TBD + + + + + +References +========== + +.. [NetDB] + {{ site_url('docs/how/network-database', True) }} + +.. [NOISE] + https://noiseprotocol.org/noise.html + +.. [NTCP] + {{ site_url('docs/transport/ntcp', True) }} + +.. [NTCP2] + {{ site_url('docs/spec/ntcp2', True) }} + +.. [Prop104] + {{ proposal_url('104') }} + +.. [Prop109] + {{ proposal_url('109') }} + +.. [RFC-2104] + https://tools.ietf.org/html/rfc2104 + +.. [RFC-3526] + https://tools.ietf.org/html/rfc3526 + +.. [RFC-6151] + https://tools.ietf.org/html/rfc6151 + +.. [RFC-7539] + https://tools.ietf.org/html/rfc7539 + +.. [RFC-7748] + https://tools.ietf.org/html/rfc7748 + +.. [RFC-7905] + https://tools.ietf.org/html/rfc7905 + +.. [RFC-9000] + https://datatracker.ietf.org/doc/html/rfc9000 + +.. [RouterAddress] + {{ ctags_url('RouterAddress') }} + +.. [RouterIdentity] + {{ ctags_url('RouterIdentity') }} + +.. [SigningPublicKey] + {{ ctags_url('SigningPublicKey') }} + +.. [SipHash] + https://www.131002.net/siphash/ + +.. [SSU] + {{ site_url('docs/transport/ssu', True) }} + +.. [STS] + Diffie, W.; van Oorschot P. C.; Wiener M. J., Authentication and + Authenticated Key Exchanges + +.. [Ticket1112] + https://{{ i2pconv('trac.i2p2.i2p') }}/ticket/1112 + +.. [Ticket1849] + https://{{ i2pconv('trac.i2p2.i2p') }}/ticket/1849