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 ChaCha20, 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.

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 by packet injection. 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.

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.

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

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.

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

QUIC recommends endpoints that send data using IPv6 SHOULD apply an IPv6 flow label in compliance with [RFC-6437], unless the local API does not allow setting IPv6 flow labels.

Unfortunately, the Java API does not allow setting IPv6 flow labels.

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.

Long Header

The long header is 32 bytes. It is used before a session is created, for Token Request, SessionRequest, SessionCreated, and Retry. It is also used for out-of-session Peer Test and Hole Punch messages.

Before header encryption:

+----+----+----+----+----+----+----+----+
|      Destination Connection ID        |
+----+----+----+----+----+----+----+----+
|   Packet Number   |type| ver| id |flag|
+----+----+----+----+----+----+----+----+
|        Source Connection ID           |
+----+----+----+----+----+----+----+----+
|                 Token                 |
+----+----+----+----+----+----+----+----+

Destination ID :: 8 bytes, unsigned big endian integer

Packet Number :: 4 bytes, unsigned big endian integer

type :: The message type = 0, 1, 7, 9, 10, or 11

ver :: The protocol version, equal to 2

id :: 1 byte, the network ID (currently 2, except for test networks)

flag :: 1 byte, unused, set to 0 for future compatibility

Source ID :: 8 bytes, unsigned big endian integer

Token :: 8 bytes, unsigned big endian integer

Short Header

The short header is 16 bytes. It is used for Session Created and for Data messages. Uauthenticated messages such as Session Request, Retry, and Peer Test will always use the long header.

16 bytes is required, because the receiver must decrypt the first 16 bytes to get the message type, and then must decrypt an additional 16 bytes if it's actually a long header, as indicated by the message type.

For Session Confirmed, before header encryption:

+----+----+----+----+----+----+----+----+
|      Destination Connection ID        |
+----+----+----+----+----+----+----+----+
|   Packet Number   |type|frag|  flags  |
+----+----+----+----+----+----+----+----+

Destination ID :: 8 bytes, unsigned big endian integer

Packet Number :: 4 bytes, all zeros

type :: The message type = 2

frag :: 1 byte fragment info:
       bit order: 76543210 (bit 7 is MSB)
       bits 7-4: fragment number 0-14, big endian
       bits 3-0: total fragments 1-15, big endian

flags :: 2 bytes, unused, set to 0 for future compatibility

See the Session Confirmed Fragmentation section below for more information about the frag field.

For Data messages, before header encryption:

+----+----+----+----+----+----+----+----+
|      Destination Connection ID        |
+----+----+----+----+----+----+----+----+
|   Packet Number   |type|flag|moreflags|
+----+----+----+----+----+----+----+----+

Destination ID :: 8 bytes, unsigned big endian integer

Packet Number :: 4 bytes, unsigned big endian integer

type :: The message type = 6

flag :: 1 byte flags:
       bit order: 76543210 (bit 7 is MSB)
       bits 7-1: unused, set to 0 for future compatibility
       bits 0: when set to 1, immediate ack requested

moreflags :: 2 bytes, unused, set to 0 for future compatibility

Connection ID Numbering

Connection IDs must be randomly generated. Source and Destination IDs must NOT be identical, so that an on-path attacker cannot capture and send a packet back to the originator that looks valid. Do NOT use a counter to generate connection IDs, so that an on-path attacker cannot generate a packet that looks valid.

Unlike in QUIC, we do not change the connection IDs during or after the handshake, even after a Retry message. The IDs remain constant from the first message (Token Request or Session Request) to the last message (Data with Termination). Additionally, connection IDs do not change during or after path challenge or connection migration.

Also different than QUIC is that connection IDs in the headers are always header-encrypted. See below.

Packet Numbering

If no First Packet Number block is sent in the handshake, packets are numbered within a single session, for each direction, starting from 0, to a max of (2**32 -1). A session must be terminated, and a new session created, well before the max number of packets is sent.

If a First Packet Number block is sent in the handshake, packets are numbered within a single session, for that direction, starting from that packet number. The packet number may wrap around during the session. When a max of 2**32 packets have been sent, wrapping the packet number back to the first packet number, that session is no longer valid. A session must be terminated, and a new session created, well before the max number of packets is sent.

TODO key rotation, reduce max packet number?

Handshake packets that are determined to be lost are retransmitted whole, with the identical header including packet number. The handshake messages Session Request, Session Created, and Session Confirmed MUST be retransmitted with the same packet number and identical encrypted contents, so that the same chained hash will be used to encrypt the response. The Retry message is never transmitted.

Data phase packets that are determined to be lost are never retransmitted whole (except termination, see below). The same applies to the blocks that are contained within lost packets. Instead, the information that might be carried in blocks is sent again in new packets as needed. Data Packets are never retransmitted with the same packet number. Any retransmission of packet contents (whether or not the contents remain the same) must use the next unused packet number.

Retransmitting an unchanged whole packet as-is, with the same packet number, is not allowed for several reasons. For background see QUIC [RFC-9000] section 12.3.

• It's inefficient to store packets for retransmission
• A new packet data looks different to an on-path observer, can't tell it's retransmitted
• A new packet gets an updated ack block sent with it, not the old ack block
• You only retransmit what's necessary. some fragments could have been already retransmitted once and been acked
• You can fit as much as you need into each retransmitted packet if more is pending
• Endpoints that track all individual packets for the purposes of detecting duplicates are at risk of accumulating excessive state. The data required for detecting duplicates can be limited by maintaining a minimum packet number below which all packets are immediately dropped.
• This scheme is much more flexible

New packets are used to carry information that is determined to have been lost. In general, information is sent again when a packet containing that information is determined to be lost, and sending ceases when a packet containing that information is remain the same) acknowledged.

Exception: A data phase packet containing a Termination block may, but is not required to be, retransmitted whole, as-is. See the Session Termination section below.

The following packets contain a random packet number that is ignored:

• Session Request
• Session Created
• Token Request
• Retry
• Peer Test
• Hole Punch

For Alice, outbound packet numbering starts at 0 with Session Confirmed. For Bob, outbound packet numbering starts at 0 with first Data packet, which should be an ACK of the Session Confirmed. The packet numbers in an example standard handshake will be:

Alice                           Bob

SessionRequest (r)    ------------>
<-------------   SessionCreated (r)
SessionConfirmed (0)  ------------>
<-------------             Data (0) (Ack-only)
Data (1)              ------------> (May be sent before Ack is received)
<-------------             Data (1)
Data (2)              ------------>
Data (3)              ------------>
Data (4)              ------------>
<-------------             Data (2)

r = random packet number (ignored)
Token Request, Retry, and Peer Test
also have random packet numbers.

Any retransmission of handshake messages (SessionRequest, SessionCreated, or SessionConfirmed) must be resent unchanged, with the same packet number. Do not use different ephemeral keys or change the payload when retransmitting these messages.

Header Binding

The header (before obfuscation and protection) is always included in the associated data for the AEAD function, to cryptographically bind the header to the data.

Header Encryption

Header encryption has several goals. See the "Additional DPI Discussion" section above for background and assumptions.

• Prevent online DPI from identifying the protocol
• Prevent patterns in a series of messages in the same connection, except for handshake retransmissions
• Prevent patterns in messages of the same type in different connections
• Prevent decryption of handshake headers without knowledge of the introduction key found in the netdb
• Prevent identification of X25519 ephemeral keys without knowledge of the introduction key found in the netdb
• Prevent decryption of data phase packet number and type by any online or offline attacker
• Prevent injection of valid handshake packets by an on-path or off-path observer without knowledge of the introduction key found in the netdb
• Prevent injection of valid data packets by an on-path or off-path observer
• Allow rapid and efficient classification of incoming packets
• Provide "probing" resistance so that there is no response to a bad Session Request, or if there is a Retry response, the response is not identifiable as I2P without knowledge of the introduction key found in the netdb
• The Destination Connection ID is not critical data, and it's ok if it can be decrypted by an observer with knowledge of the introduction key found in the netdb
• The packet number of a data phase packet is an AEAD nonce and is critical data. It must not be decryptable by an observer even with knowledge of the introduction key found in the netdb. See [Nonces].

Headers are encrypted with known keys published in the network database or calculated later. In the handshake phase, this is for DPI resistance only, as the key is public and the key and nonces are reused, so it is effectively just obfuscation. Note that the header encryption is also used to obfuscate the ephemeral keys X (in Session Request) and Y (in Session Created).

See the Inbound Packet Handling section below for additional guidance.

Bytes 0-15 of all headers are encrypted using a header protection scheme by XORing with data calculated from known keys, using ChaCha20, similar to QUIC [RFC-9001] and [Nonces]. This ensures that the encrypted short header and the first part of the long header will appear to be random.

For Session Request and Session Created, bytes 16-31 of the long header and the 32-byte Noise ephemeral key are encrypted using ChaCha20. The unencrypted data is random, so the encrypted data will appear to be random.

For Retry, bytes 16-31 of the long header are encrypted using ChaCha20. The unencrypted data is random, so the encrypted data will appear to be random.

Unlike the QUIC [RFC-9001] header protection scheme, ALL parts of all headers, including destination and source connection IDs, are encrypted. QUIC [RFC-9001] and [Nonces] are primarily focused on encrypting the "critical" part of the header, i.e. the packet number (ChaCha20 nonce). While encrypting the session ID makes incoming packet classification a little more complex, it makes some attacks more difficult. QUIC defines different connection IDs for different phases, and for path challenge and connection migration. Here we use the same connection IDs throughout, as they are encrypted.

There are seven header protection key phases:

• Session Request and Token Request
• Session Created
• Retry
• Session Confirmed
• Data Phase
• Peer Test
• Hole Punch

Header encryption is designed to allow rapid classification of inbound packets, without complex heuristics or fallbacks. This is accomplished by using the same k_header_1 key for almost all inbound messages. Even when the source IP or port of a connection changes due to an actual IP change or NAT behavior, the packet may be rapidly mapped to a session with a single lookup of the connection ID.

Note that Session Created and Retry are the ONLY messages that require fallback processing for k_header_1 to decrypt the Connection ID, because they use the sender's (Bob's) intro key. ALL other messages use the receiver's intro key for k_header_1. The fallback processing need only look up pending outbound connections by source IP/port.

If the fallback processing by source IP/port fails to find a pending outbound connection, there could be several causes:

• Not an SSU2 message
• A corrupted SSU2 message
• The reply is spoofed or modified by an attacker
• Bob has a symmetric NAT
• Bob changed IP or port during processing of the message
• Bob sent the reply out a different interface

While additional fallback processing is possible to attempt to find the pending outbound connection and decrypt the connection ID using the k_header_1 for that connection, it is probably not necessary. If Bob has issues with his NAT or packet routing, it is probably better to let the connection fail. This design relies on endpoints retaining a stable address for the duration of the handshake.

See the Inbound Packet Handling sesion below for additional guidelines.

See the individual KDF sections below for the derivation of the header encryption keys for that phase.

Header Encryption KDF

// incoming encrypted packet
packet = incoming encrypted packet
len = packet.length

// take the next-to-last 12 bytes of the packet
iv = packet[len-24:len-13]
k_header_1 = header encryption key 1
data = {0, 0, 0, 0, 0, 0, 0, 0}
mask = ChaCha20.encrypt(k_header_1, iv, data)

// encrypt the first part of the header by XORing with the mask
packet[0:7] ^= mask[0:7]

// take the last 12 bytes of the packet
iv = packet[len-12:len-1]
k_header_2 = header encryption key 2
data = {0, 0, 0, 0, 0, 0, 0, 0}
mask = ChaCha20.encrypt(k_header_2, iv, data)

// encrypt the second part of the header by XORing with the mask
packet[8:15] ^= mask[0:7]


// For Session Request and Session Created only:
iv = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}

// encrypt the third part of the header and the ephemeral key
packet[16:63] = ChaCha20.encrypt(k_header_2, iv, packet[16:63])


// For Retry, Token Request, Peer Test, and Hole Punch only:
iv = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}

// encrypt the third part of the header
packet[16:31] = ChaCha20.encrypt(k_header_2, iv, packet[16:31])

This KDF uses the last 24 bytes of the packet as the IV for the two ChaCha20 operations. As all packets end with a 16 byte MAC, this requires that all packet payloads are a minimum of 8 bytes. This requirement is additionally documented in the message sections below.

Header Validation

After decrypting the first 8 bytes of the header, the receiver will know the Destination Connection ID. From there, the receiver knows what header encryption key to use for the remainder of the header, based on the key phase of the session.

Decrypting the next 8 bytes of the header will then reveal the message type and be able to determine if it is a short or long header. If it is a long header, the receiver must validate the version and netid fields. If the version is != 2, or the netid is != the expected value (generally 2, except in test networks), the receiver should drop the message.

ChaCha20/Poly1305

Encrypted and authenticated data format.

Inputs to the encryption/decryption functions:

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:
      The packet header, 16 bytes.

data :: Plaintext data, 0 or more bytes

Output of the encryption function, input to the decryption function:

+----+----+----+----+----+----+----+----+
|                                       |
+                                       +
|       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

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 discard the message.
• Bob should maintain a blacklist of IPs with repeated failures.

KDF for Initial ChainKey

// Define protocol_name.
Set protocol_name = "Noise_XKchaobfse+hs1+hs2+hs3_25519_ChaChaPoly_SHA256"
 (52 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

// MixHash(null prologue)
h = SHA256(h);

// up until here, can all be precalculated by Alice for all outgoing connections

// Bob's X25519 static keys
// bpk is published in routerinfo
bsk = GENERATE_PRIVATE()
bpk = DERIVE_PUBLIC(bsk)

// Bob static key
// MixHash(bpk)
// || below means append
h = SHA256(h || bpk);

// Bob introduction key
// bik is published in routerinfo
bik = RANDOM(32)

// up until here, can all be precalculated by Bob for all incoming connections

KDF for Session Request

// MixHash(header)
h = SHA256(h || header)

This is the "e" message pattern:

// Alice's X25519 ephemeral keys
aesk = GENERATE_PRIVATE()
aepk = DERIVE_PUBLIC(aesk)

// Alice ephemeral key X
// MixHash(aepk)
h = SHA256(h || aepk);

// 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)
sharedSecret = DH(aesk, bpk) = DH(bsk, aepk)

// MixKey(DH())
//[chainKey, k] = MixKey(sharedSecret)
// ChaChaPoly parameters to encrypt/decrypt
keydata = HKDF(chainKey, sharedSecret, "", 64)
chainKey = keydata[0:31]

// AEAD parameters
k = keydata[32:64]
n = 0
ad = h
ciphertext = ENCRYPT(k, n, payload, ad)

// retain the chainKey for Session Created KDF


End of "es" message pattern.

// Header encryption keys for this message
// bik = Bob's intro key
k_header_1 = bik
k_header_2 = bik

// Header encryption keys for next message (Session Created)
k_header_1 = bik
k_header_2 = HKDF(chainKey, ZEROLEN, "SessCreateHeader", 32)

// Header encryption keys for next message (Retry)
k_header_1 = bik
k_header_2 = bik

Payload

• DateTime block
• Options block (optional)
• Relay Tag Request block (optional)
• Padding block (optional)

The minimum payload size is 8 bytes. Since the DateTime block is only 7 bytes, at least one other block must be present.

Notes

• The unique X value in the initial ChaCha20 block ensure that the ciphertext is different for every session.
• To provide probing resistance, Bob should not send a Retry message in response to a Session Request message unless the message type, protocol version, and network ID fields in the Session Request message are valid.
• 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. Reject by sending a Retry message containing a zero token and a termination block.
• 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.) TODO UNLESS minimum packet size is enforced for PMTU.
• On most errors, including AEAD, DH, apparent replay, or key validation failure, Bob should halt further message processing and drop the message without responding.
• Bob MAY send a Retry message containing a zero token and a Termination block with a clock skew reason code if the timestamp in the DateTime block is too far skewed.
• 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. Alternatively, respond with a Retry message before the DH operation and AEAD validation.
• "ver" field: The overall Noise protocol, extensions, and SSU2 protocol including payload specifications, indicating SSU2. This field may be used to indicate support for future changes.
• The network ID field is used to quickly identify cross-network connections. If this field is does not match Bob's network ID, Bob should disconnect and block future connections.
• Bob must drop the message if the Source Connection ID equals the Destination Connection ID.

Payload

• DateTime block
• Address block
• Relay Tag block (optional)
• New Token block (optional)
• First Packet Number block (optional)
• Options block (optional)
• Termination block (not recommended, send in a retry message instead)
• Padding block (optional)

The minimum payload size is 8 bytes. Since the DateTime and Address blocks total more than that, the requirement is met with only those two blocks.

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.) TODO UNLESS minimum packet size is enforced for PMTU.
• 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.
• 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.
• Alice must drop the message if the source IP and port do not match the destination IP and port of the Session Request.
• Alice must drop the message if the Destination and Source Connection IDs do not match the Source and Destination Connection IDs of the Session Request.
• Bob sends a relay tag block if requested by Alice in the Session Request.

Issues

• Include min/max padding options here?

Payload

• RouterInfo block (must be the first block)
• Options block (optional)
• New Token block (optional)
• Relay Request block (optional)
• Peer Test block (optional)
• First Packet Number block (optional)
• I2NP, First Fragment, or Follow-on Fragment blocks (optional, but probably no room)
• Padding block (optional)

The minimum payload size is 8 bytes. Since the RouterInfo block will be well more than that, the requirement is met with only that block.

Notes

• Bob must perform the usual Router Info validation. Ensure the signature type is supported, verify the signature, verify the timestamp is within bounds, and any other checks necessary. See below for notes on handling fragmented Router Infos.
• Bob must verify that Alice's static key received in the first frame matches the static key in the Router Info. Bob must first search the Router Info for a NTCP or SSU2 Router Address with a matching version (v) option. See Published Router Info and Unpublished Router Info sections below. See below for notes on handling fragmented Router Infos.
• If Bob has an older version of Alice's RouterInfo in his netdb, verify that the static key in the router info is the same in both, if present, 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.
• 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 4 blocks in the following order: 1) Alice's Router Info block (required) 2) Options block (optional) 3) I2NP blocks (optional) 4) Padding block (optional) This frame must never contain any other block type. TODO: what about relay and peer test?
• Message 3 part 2 padding block is recommended.
• There may be no space, or only a small amount of space, available for I2NP blocks, depending on the MTU and the Router Info size. Do NOT include I2NP blocks if the Router Info is fragmented. The simplest implementation may be to never include I2NP blocks in the Session Confirmed message, and send all I2NP blocks in subsequent Data messages. See Router Info block section below for maximum block size.

Session Confirmed Fragmentation

The Session Confirmed message must contain the full signed Router Info from Alice so that Bob may perform several required checks:

• The static key "s" in the RI matches the static key in the handshake
• The introduction key "i" in the RI must be extracted and valid, to be used in the data phase
• The RI signature is valid

Unfortunately, the Router Info, even when gzip compressed in the RI block, may exceed the MTU. Therefore, the Session Confirmed may be fragmented across two or more packets. This is the ONLY case in the SSU2 protocol where an AEAD-protected payload is fragmented across two or more packets.

The headers for each packet are constructed as follows:

• ALL headers are short headers with the same packet number 0
• ALL headers contain a "frag" field, with the fragment number and total number of fragments
• The unencrypted header of fragment 0 is the associated data (AD) for the "jumbo" message
• Each header is encrypted using the last 24 bytes of data in THAT packet

Construct the series of packets as follows:

• Create a single RI block (fragment 0 of 1 in the RI block frag field). We do not use RI block fragmentation, that was for an alternate method of solving the same problem.
• Create a "jumbo" payload with the RI block and any other blocks to be included
• Calculate the total data size (not including the header), which is the payload size + 64 bytes for the static key and two MACs
• Calculate the space available in each packet, which is the MTU minus the IP header (20 or 40), minus the UDP header (8), minus the SSU2 short header (16). Total per-packet overhead is 44 (IPv4) or 64 (IPv6).
• Calculate the number of packets.
• Calculate the size of the data in the last packet. It must be greater than or equal to 24 bytes, so that header encryption will work. If it is too small, either add a padding block, OR increase the size of the padding block if already present, OR reduce the size of one of the other packets so that the last packet will be big enough.
• Create the unencrypted header for the first packet, with the total number of fragments in the frag field, and encrypt the "jumbo" payload with Noise, using the header as AD, as usual.
• Split up the encrypted jumbo packet into fragments
• Add an unencrypted header for each fragment 1-n
• Encrypt the header for each fragment 0-n. Each header uses the SAME k_header_1 and k_header_2 as defined above in the Session Confirmed KDF.
• Transmit all fragments

Reassembly process:

When Bob receives any Session Confirmed message, he decrypts the header, inspects the frag field, and determines that the Session Confirmed is fragmented. He does not (and cannot) decrypt the message until all fragments are received and reassembled.

• Preserve the header for fragment 0, as it is used as the Noise AD
• Discard the headers for other fragments before reassembly
• Reassemble the "jumbo" payload, with the header for fragment 0 as AD, and decrypt with Noise
• Validate the RI block as usual
• Proceed to the data phase and send ACK 0, as usual

There is no mechanism for Bob to ack individual fragments. When Bob receives all fragments, reassembles, decrypts, and validates the contents, Bob does a split() as usual, enters the data phase, and sends an ACK of packet number 0.

If Alice does not receive an ACK of packet number 0, she must retransmit all session confirmed packets as-is.

Examples:

For 1500 MTU over IPv6, max payload is 1372, RI block overhead is 5, max (gzip compressed) RI data size is 1367 (assuming no other blocks). With two packets, the overhead of the 2nd packet is 64, so it can hold another 1436 bytes of payload. So two packets is enough for a compressed RI up to 2803 bytes.

The largest compressed RI seen in the current network is about 1400 bytes; therefore, in practice, two fragments should be enough, even with a minimum 1280 MTU. The protocol allows for 15 fragments max.

Security analysis:

The integrity and security of a fragmented Session Confirmed is the same as that of an unfragmented one. Any alteration of any fragment will cause the Noise AEAD to fail after reassembly. The headers of the fragments after fragment 0 are only used to identify the fragment. Even if an on-path attacker had the k_header_2 key used to encrypt the header (unlikely, derived from the handshake), this would not allow the attacker to substitute a valid fragment.

Notes

• The router must drop a message with an AEAD error.

+----+----+----+----+----+----+----+----+
|  Short Header 16 bytes, ChaCha20      |
+  encrypted with intro key and         +
|  derived key, see Data Phase KDF      |
+----+----+----+----+----+----+----+----+
|   ChaCha20 data                       |
+   Encrypted and authenticated data    +
|  length varies                        |
+  k defined in Data Phase KDF          +
|  n = packet number from header        |
+                                       +
|                                       |
+----+----+----+----+----+----+----+----+
|                                       |
+        Poly1305 MAC (16 bytes)        +
|                                       |
+----+----+----+----+----+----+----+----+

Unencrypted data (Poly1305 auth tag not shown):

+----+----+----+----+----+----+----+----+
|      Destination Connection ID        |
+----+----+----+----+----+----+----+----+
|   Packet Number   |type|    flags     |
+----+----+----+----+----+----+----+----+
|     Noise payload (block data)        |
+          (length varies)              +
|                                       |
+----+----+----+----+----+----+----+----+

Destination ID :: As specified in session setup

Packet Number :: 4 byte big endian integer

type :: 6

flags :: 3 bytes, unused, set to 0 for future compatibility

Notes

• The minimum payload size is 8 bytes. This requirement will be met by any ACK, I2NP, First Fragment, or Follow-on Fragment block. If the requirement is not met, a Padding block must be included.
• Each packet number may only be used once. When retransmitting I2NP messages or fragments, a new packet number must be used.

Payload

• DateTime block
• Address block (required for messages 6 and 7, see note below)
• Peer Test block
• Padding block (optional)

The minimum payload size is 8 bytes. Since the Peer Test block totals more than that, the requirement is met with only this block.

In messages 5 and 7, the Peer Test block may be identical to the block from in-session messages 3 and 4, containing the agreement signed by Charlie, or it may be regenerated. Signature is optional.

In message 6, the Peer Test block may be identical to the block from in-session messages 1 and 2, containing the request signed by Alice, or it may be regenerated. Signature is optional.

Connection IDs: The two connection IDs are derived from the test nonce. For messages 5 and 7 sent from Charlie to Alice, the Destination Connection ID is two copies of the 4-byte big-endian test nonce, i.e. ((nonce << 32) | nonce). The Source Connection ID is the inverse of the Destination Connection ID, i.e. ~((nonce << 32) | nonce). For message 6 sent from Alice to Charlie, swap the two connection IDs.

Address block contents:

• In message 5: Not required.
• In message 6: Charlie's IP and port as selected from Charlie's RI.
• In message 7: Alice's actual IP and port message 6 was received from.

Payload

• DateTime block
• Address block
• Options block (optional)
• Termination block (optional, if session is rejected)
• Padding block (optional)

The minimum payload size is 8 bytes. Since the DateTime and Address blocks total more than that, the requirement is met with only those two blocks.

Notes

• To provide probing resistance, a router should not send a Retry message in response to a Session Request or Token Request message unless the message type, protocol version, and network ID fields in the Request message are valid.
• To limit the magnitude of any amplification attack that can be mounted using spoofed source addresses, the Retry message must not contain large amounts of padding. It is recommended that the Retry message be no larger than three times the size of the message it is responding to. Alternatively, use a simple method such as adding a random amount of padding in the range 1-64 bytes.

Payload

• DateTime block
• Padding block

The minimum payload size is 8 bytes.

Notes

• To provide probing resistance, a router should not send a Retry message in response to a Token Request message unless the message type, protocol version, and network ID fields in the Token Request message are valid.
• This is NOT a standard Noise message and is not part of the handshake. It is not bound to the Session Request message other than by connection IDs.
• On most errors, including AEAD, or apparent replay Bob should halt further message processing and drop the message without responding.
• 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.
• Bob MAY send a Retry message containing a zero token and a Termination block with a clock skew reason code if the timestamp in the DateTime block is too far skewed.
• Minimum size: TBD, same rules as for Session Created?

Payload

• DateTime block
• Address block
• Relay Response block
• Padding block (optional)

The minimum payload size is 8 bytes. Since the DateTime and Address blocks total more than that, the requirement is met with only those two blocks.

Connection IDs: The two connection IDs are derived from the relay nonce. The Destination Connection ID is two copies of the 4-byte big-endian relay nonce, i.e. ((nonce << 32) | nonce). The Source Connection ID is the inverse of the Destination Connection ID, i.e. ~((nonce << 32) | nonce).

Alice should ignore the token in the header. The token to be used in the Session Request is in the Relay Response block.

DateTime

For time synchronization:

+----+----+----+----+----+----+----+
| 0  |    4    |     timestamp     |
+----+----+----+----+----+----+----+

blk :: 0
size :: 2 bytes, big endian, value = 4
timestamp :: Unix timestamp, unsigned seconds.
             Wraps around in 2106

Notes:

• Unlike in SSU 1, there is no timestamp in the packet header for the data phase in SSU 2.
• Implementations should periodically send DateTime blocks in the data phase.
• Implementations must round to the nearest second to prevent clock bias in the network.

Options

Pass updated options. Options include: Min and max padding.

Options block will be variable length.

+----+----+----+----+----+----+----+----+
| 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

Options Issues:

• Options negotiation is TBD.

RouterInfo

Pass Alice's RouterInfo to Bob. Used in Session Confirmed part 2 payload only. Not to be used in the data phase; use an I2NP DatabaseStore Message instead.

Minimum Size: About 420 bytes, unless the router identity and signature in the router info are compressible, which is unlikely.

NOTE: The Router Info block is never fragmented. The frag field is always 0/1. See the Session Confirmed Fragmentation section above for more information.

+----+----+----+----+----+----+----+----+
| 2  |  size   |flag|frag|              |
+----+----+----+----+----+              +
|                                       |
+       Router Info fragment            +
| (Alice RI in Session Confirmed)       |
+ (Alice, Bob, or third-party           +
|  RI in data phase)                    |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 2
size :: 2 bytes, big endian, 2 + fragment size
flag :: 1 byte flags
       bit order: 76543210 (bit 7 is MSB)
       bit 0: 0 for local store, 1 for flood request
       bit 1: 0 for uncompressed, 1 for gzip compressed
       bits 7-2: Unused, set to 0 for future compatibility
frag :: 1 byte fragment info:
       bit order: 76543210 (bit 7 is MSB)
       bits 7-4: fragment number, always 0
       bits 3-0: total fragments, always 1, big endian

routerinfo :: Alice's or Bob's RouterInfo

Notes:

• The Router Info is optionally compressed with gzip, as indicated by flag bit 1. This is different from NTCP2, where it is never compressed, and from a DatabaseStore Message, where it always is compressed. Compression is optional because it usually is of little benefit for small Router Infos, where there is little compressible content, but is very beneficial for large Router Infos with several compressible Router Addresses. Compression is recommended if it allows a Router Info to fit in a single Session Confirmed packet without fragmentation.
• Maximum size of first or only fragment in the Session Confirmed message: MTU - 113 for IPv4 or MTU - 133 for IPv6. Assuming 1500 byte default MTU, and no other blocks in the message, 1387 for IPv4 or 1367 for IPv6. 97% of current router infos are smaller than 1367 witout gzipping. 99.9% of current router infos are smaller than 1367 when gzipped. Assuming 1280 byte minimum MTU, and no other blocks in the message, 1167 for IPv4 or 1147 for IPv6. 94% of current router infos are smaller than 1147 witout gzipping. 97% of current router infos are smaller than 1147 when gzipped.
• The frag byte is now unused, the Router Info block is never fragmented. The frag byte must be set to fragment 0, total fragments 1. See the Session Confirmed Fragmentation section above for more information.
• 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.
• This protocol does not provide an acknowledgment that the RouterInfo was stored or flooded. If acknowledgment is desired, and the receiver is floodfill, the sender should instead send a standard I2NP DatabaseStoreMessage with a reply token.

I2NP Message

A complete I2NP message with a modified header.

This uses the same 9 bytes for the I2NP header as in [NTCP2] (type, message id, short expiration).

+----+----+----+----+----+----+----+----+
| 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

Notes:

• This is the same 9-byte I2NP header format used in NTCP2.
• This is exactly the same format as the First Fragment block, but the block type indicates that this is a complete message.
• Maximum size including 9-byte I2NP header is MTU - 63 for IPv4 and MTU - 83 for IPv6.

First Fragment

The first fragment (fragment #0) of an I2NP message with a modified header.

This uses the same 9 bytes for the I2NP header as in [NTCP2] (type, message id, short expiration).

Total number of fragments is not specified.

+----+----+----+----+----+----+----+----+
| 4  |  size   |type|    msg id         |
+----+----+----+----+----+----+----+----+
|   short exp       |                   |
+----+----+----+----+                   +
|          partial message              |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 4
size :: 2 bytes, big endian, size of data to follow
        Fragment 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 :: Partial I2NP message body, bytes 0 - (size - 10)

Notes:

• This is the same 9-byte I2NP header format used in NTCP2.
• This is exactly the same format as the I2NP Message block, but the block type indicates that this is a the first fragment of a message.
• Partial message length must be greater than zero.
• As in SSU 1, it is recommended to send the last fragment first, so that the receiver knows the total number of fragments and can efficiently allocate receive buffers.
• Maximum size including 9-byte I2NP header is MTU - 63 for IPv4 and MTU - 83 for IPv6.

Follow-on Fragment

An additional fragment (fragment number greater than zero) of an I2NP message.

+----+----+----+----+----+----+----+----+
| 5  |  size   |frag|    msg id         |
+----+----+----+----+----+----+----+----+
|                                       |
+                                       +
|          partial message              |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 5
size :: 2 bytes, big endian, size of data to follow
        Fragment size is (size - 5).
frag :: Fragment info:
        Bit order: 76543210 (bit 7 is MSB)
        bits 7-1: fragment number 1 - 127 (0 not allowed)
        bit 0: isLast (1 = true)
msg id :: 4 bytes, big endian, I2NP message ID
message :: Partial I2NP message body

Notes:

• Partial message length must be greater than zero.
• As in SSU 1, it is recommended to send the last fragment first, so that the receiver knows the total number of fragments and can efficiently allocate receive buffers.
• As in SSU 1, the maximum fragment number is 127, but the practical limit is 63 or less. Implementations may limit the maximum to what is practical for a maximum I2NP message size of about 64 KB, which is about 55 fragments with a 1280 minimum MTU. See the Max I2NP Message Size section below.
• Maximum partial message size (not including frag and message id) is MTU - 68 for IPv4 and MTU - 88 for IPv6.

Termination

Drop the connection. This must be the last non-padding block in the payload.

+----+----+----+----+----+----+----+----+
| 6  |  size   |    valid data packets  |
+----+----+----+----+----+----+----+----+
    received   | rsn|     addl data     |
+----+----+----+----+                   +
~               .   .   .               ~
+----+----+----+----+----+----+----+----+

blk :: 6
size :: 2 bytes, big endian, value = 9 or more
valid received :: The number of valid packets 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: Timeout
       15: RI signature verification fail
       16: s parameter missing, invalid, or mismatched in RouterInfo
       17: banned
       18: bad token
       19: connection limits
       20: incompatible version
       21: wrong net ID
       22: replaced by new session
addl data :: optional, 0 or more bytes, for future expansion, debugging,
             or reason text.
             Format unspecified and may vary based on reason code.

Notes:

• Not all reasons may actually be used, implementation dependent. Most failures will generally result in the message being dropped, not a termination. See notes in handshake message sections above. Additional reasons listed are for consistency, logging, debugging, or if policy changes.
• It is recommended that an ACK block be included with the Termination block.
• In the data phase, for any reason other than "termination received", the peer should respond with a termination block with the reason "termination received".

RelayRequest

Sent in a Data message in-session, from Alice to Bob. See Relay Process section below.

+----+----+----+----+----+----+----+----+
|  7 |  size   |flag|       nonce       |
+----+----+----+----+----+----+----+----+
|     relay tag     |     timestamp     |
+----+----+----+----+----+----+----+----+
| ver| asz|AlicePort|  Alice IP address |
+----+----+----+----+----+----+----+----+
|              signature                |
+            length varies              +
|         64 bytes for Ed25519          |
~                                       ~
|                 . . .                 |
+----+----+----+----+----+----+----+----+

blk :: 7
size :: 2 bytes, big endian, size of data to follow
flag :: 1 byte flags, Unused, set to 0 for future compatibility

The data below here is covered
by the signature, and Bob forwards it unmodified.

nonce :: 4 bytes, randomly generated by Alice
relay tag :: 4 bytes, the itag from Charlie's RI
timestamp :: Unix timestamp, unsigned seconds.
             Wraps around in 2106
ver ::  1 byte SSU version to be used for the introduction:
       1: SSU 1
       2: SSU 2
asz :: 1 byte endpoint (port + IP) size (6 or 18)
AlicePort :: 2 byte Alice's port number, big endian
Alice IP :: (asz - 2) byte representation of Alice's IP address,
            network byte order
signature :: length varies, 64 bytes for Ed25519.
             Signature of prologue, Bob's hash,
             and signed data above, as signed by
             Alice.

Notes:

• The IP address is always included (unlike in SSU 1) and may be different than the IP used for the session.

Signature:

Alice signs the request and includes it in this block; Bob forwards it in the Relay Intro block to Charlie. Signature algorithm: Sign the following data with the Alice's router signing key:

• prologue: 16 bytes "RelayRequestData", not null-terminated (not included in the message)
• bhash: Bob's 32-byte router hash (not included in the message)
• chash: Charlie's 32-byte router hash (not included in the message)
• nonce: 4 byte nonce
• relay tag: 4 byte relay tag
• timestamp: 4 byte timestamp (seconds)
• ver: 1 byte SSU version
• asz: 1 byte endpoint (port + IP) size (6 or 18)
• AlicePort: 2 byte Alice's port number
• Alice IP: (asz - 2) byte Alice IP address

RelayResponse

Sent in a Data message in-session, from Charlie to Bob or from Bob to Alice, AND in the Hole Punch message from Charlie to Alice. See Relay Process section below.

+----+----+----+----+----+----+----+----+
|  8 |  size   |flag|code|    nonce
+----+----+----+----+----+----+----+----+
     |     timestamp     | ver| csz|Char
+----+----+----+----+----+----+----+----+
 Port|   Charlie IP addr |              |
+----+----+----+----+----+              +
|              signature                |
+            length varies              +
|         64 bytes for Ed25519          |
~                                       ~
|                 . . .                 |
+----+----+----+----+----+----+----+----+
|                 Token                 |
+----+----+----+----+----+----+----+----+

blk :: 8
size :: 2 bytes, 6
flag :: 1 byte flags, Unused, set to 0 for future compatibility
code :: 1 byte status code:
       0: accept
       1: rejected by Bob, reason unspecified
       2: rejected by Bob, Charlie is banned
       3: rejected by Bob, limit exceeded
       4: rejected by Bob, signature failure
       5: rejected by Bob, relay tag not found
       6: rejected by Bob, Alice RI not found
       7-63: other rejected by Bob codes TBD
       64: rejected by Charlie, reason unspecified
       65: rejected by Charlie, unsupported address
       66: rejected by Charlie, limit exceeded
       67: rejected by Charlie, signature failure
       68: rejected by Charlie, Alice is already connected
       69: rejected by Charlie, Alice is banned
       70: rejected by Charlie, Alice is unknown
       71-127: other rejected by Charlie codes TBD
       128: reject, source and reason unspecified
       129-255: other reject codes TBD

The data below is covered by the signature if the code is 0 (accept).
Bob forwards it unmodified.

nonce :: 4 bytes, as received from Bob or Alice

The data below is present only if the code is 0 (accept).

timestamp :: Unix timestamp, unsigned seconds.
             Wraps around in 2106
ver ::  1 byte SSU version to be used for the introduction:
       1: SSU 1
       2: SSU 2
csz :: 1 byte endpoint (port + IP) size (0 or 6 or 18)
       may be 0 for some rejection codes
CharliePort :: 2 byte Charlie's port number, big endian
               not present if csz is 0
Charlie IP :: (csz - 2) byte representation of Charlie's IP address,
              network byte order
              not present if csz is 0
signature :: length varies, 64 bytes for Ed25519.
             Signature of prologue, Bob's hash,
             and signed data above, as signed by
             Charlie.
             Not present if rejected by Bob.
token :: Token generated by Charlie for Alice to use
         in the Session Request.
         Only present if code is 0 (accept)

Notes:

The token must be used immediately by Alice in the Session Request.

Signature:

If Charlie agrees (response code 0) or rejects (response code 64 or higher), Charlie signs the response and includes it in this block; Bob forwards it in the Relay Response block to Alice. Signature algorithm: Sign the following data with the Charlie's router signing key:

• prologue: 16 bytes "RelayAgreementOK", not null-terminated (not included in the message)
• bhash: Bob's 32-byte router hash (not included in the message)
• nonce: 4 byte nonce
• timestamp: 4 byte timestamp (seconds)
• ver: 1 byte SSU version
• csz: 1 byte endpoint (port + IP) size (0 or 6 or 18)
• CharliePort: 2 byte Charlie's port number (not present if csz is 0)
• Charlie IP: (csz - 2) byte Charlie IP address (not present if csz is 0)

If Bob rejects (response code 1-63), Bob signs the response and includes it in this block. Signature algorithm: Sign the following data with the Bob's router signing key:

• prologue: 16 bytes "RelayAgreementOK", not null-terminated (not included in the message)
• bhash: Bob's 32-byte router hash (not included in the message)
• nonce: 4 byte nonce
• timestamp: 4 byte timestamp (seconds)
• ver: 1 byte SSU version
• csz: 1 byte = 0

RelayIntro

Sent in a Data message in-session, from Bob to Charlie. See Relay Process section below.

Must be preceded by a RouterInfo block, or I2NP DatabaseStore message block (or fragment), containing Alice's Router Info, either in the same payload (if there's room), or in a previous message.

+----+----+----+----+----+----+----+----+
|  9 |  size   |flag|                   |
+----+----+----+----+                   +
|                                       |
+                                       +
|         Alice Router Hash             |
+             32 bytes                  +
|                                       |
+                   +----+----+----+----+
|                   |      nonce        |
+----+----+----+----+----+----+----+----+
|     relay tag     |     timestamp     |
+----+----+----+----+----+----+----+----+
| ver| asz|AlicePort|  Alice IP address |
+----+----+----+----+----+----+----+----+
|              signature                |
+            length varies              +
|         64 bytes for Ed25519          |
~                                       ~
|                 . . .                 |
+----+----+----+----+----+----+----+----+

blk :: 9
size :: 2 bytes, big endian, size of data to follow
flag :: 1 byte flags, Unused, set to 0 for future compatibility
hash :: Alice's 32-byte router hash,

The data below here is covered
by the signature, as received from Alice in the Relay Request,
and Bob forwards it unmodified.

nonce :: 4 bytes, as received from Alice
relay tag :: 4 bytes, the itag from Charlie's RI
timestamp :: Unix timestamp, unsigned seconds.
             Wraps around in 2106
ver ::  1 byte SSU version to be used for the introduction:
       1: SSU 1
       2: SSU 2
asz :: 1 byte endpoint (port + IP) size (6 or 18)
AlicePort :: 2 byte Alice's port number, big endian
Alice IP :: (asz - 2) byte representation of Alice's IP address,
            network byte order
signature :: length varies, 64 bytes for Ed25519.
             Signature of prologue, Bob's hash,
             and signed data above, as signed by
             Alice.

Notes:

• For IPv4, Alice's IP address is always 4 bytes, because Alice is trying to connect to Charlie via IPv4. IPv6 is supported, and Alice's IP address may be 16 bytes.
• For IPv4, this message must be sent via an established IPv4 connection, as that's the only way that Bob knows Charlie's IPv4 address to return to Alice in the RelayResponse. IPv6 is supported, and this message may be sent via an established IPv6 connection.
• Any SSU address published with introducers must contain "4" or "6" in the "caps" option.

Signature:

Alice signs the request and Bob forwards it in this block to Charlie. Verification algorithm: Verify the following data with the Alice's router signing key:

• prologue: 16 bytes "RelayRequestData", not null-terminated (not included in the message)
• bhash: Bob's 32-byte router hash (not included in the message)
• chash: Charlie's 32-byte router hash (not included in the message)
• nonce: 4 byte nonce
• relay tag: 4 byte relay tag
• timestamp: 4 byte timestamp (seconds)
• ver: 1 byte SSU version
• asz: 1 byte endpoint (port + IP) size (6 or 18)
• AlicePort: 2 byte Alice's port number
• Alice IP: (asz - 2) byte Alice IP address

PeerTest

Sent either in a Data message in-session, or a Peer Test message out-of-session. See Peer Test Process section below.

For message 2, must be preceded by a RouterInfo block, or I2NP DatabaseStore message block (or fragment), containing Alice's Router Info, either in the same payload (if there's room), or in a previous message.

For message 4, if the relay is accepted (reason code 0), must be preceded by a RouterInfo block, or I2NP DatabaseStore message block (or fragment), containing Charlie's Router Info, either in the same payload (if there's room), or in a previous message.

+----+----+----+----+----+----+----+----+
| 10 |  size   | msg|code|flag|         |
+----+----+----+----+----+----+         +
| Alice router hash (message 2 only)    |
+             or                        +
| Charlie router hash (message 4 only)  |
+ or all zeros if rejected by Bob       +
| Not present in messages 1,3,5,6,7     |
+                             +----+----+
|                             | ver|
+----+----+----+----+----+----+----+----+
   nonce       |     timestamp     | asz|
+----+----+----+----+----+----+----+----+
|AlicePort|  Alice IP address |         |
+----+----+----+----+----+----+         +
|              signature                |
+            length varies              +
|         64 bytes for Ed25519          |
~                                       ~
|                 . . .                 |
+----+----+----+----+----+----+----+----+

blk :: 10
size :: 2 bytes, big endian, size of data to follow
msg :: 1 byte message number 1-7
code :: 1 byte status code:
       0: accept
       1: rejected by Bob, reason unspecified
       2: rejected by Bob, no Charlie available
       3: rejected by Bob, limit exceeded
       4: rejected by Bob, signature failure
       5: rejected by Bob, address unsupported
       6-63: other rejected by Bob codes TBD
       64: rejected by Charlie, reason unspecified
       65: rejected by Charlie, unsupported address
       66: rejected by Charlie, limit exceeded
       67: rejected by Charlie, signature failure
       68: rejected by Charlie, Alice is already connected
       69: rejected by Charlie, Alice is banned
       70: rejected by Charlie, Alice is unknown
       70-127: other rejected by Charlie codes TBD
       128: reject, source and reason unspecified
       129-255: other reject codes TBD
       reject codes only allowed in messages 3 and 4
flag :: 1 byte flags, Unused, set to 0 for future compatibility
hash :: Alice's or Charlie's 32-byte router hash,
        only present in messages 2 and 4.
        All zeros (fake hash) in message 4 if rejected by Bob.

For messages 1-4, the data below here is covered
by the signature, if present, and Bob forwards it unmodified.

ver :: 1 byte SSU version:
       1: SSU 1 (not supported)
       2: SSU 2 (required)
nonce :: 4 byte test nonce, big endian
timestamp :: Unix timestamp, unsigned seconds.
             Wraps around in 2106
asz :: 1 byte endpoint (port + IP) size (6 or 18)
AlicePort :: 2 byte Alice's port number, big endian
Alice IP :: (asz - 2) byte representation of Alice's IP address,
            network byte order
signature :: length varies, 64 bytes for Ed25519.
             Signature of prologue, Bob's hash,
             and signed data above, as signed by
             Alice or Charlie.
             Only present for messages 1-4.
             Optional in message 5-7.

Notes:

• Unlike in SSU 1, message 1 must include Alice's IP address and port.

• Testing of IPv6 addresses is supported, and Alice-Bob and Alice-Charlie communication may be via IPv6, if Bob and Charlie indicate support with a 'B' capability in their published IPv6 address. See Proposal 126 for details.

  Alice sends the request to Bob using an existing session over the transport (IPv4 or IPv6) that she wishes to test. When Bob receives a request from Alice via IPv4, Bob must select a Charlie that advertises an IPv4 address. When Bob receives a request from Alice via IPv6, Bob must select a Charlie that advertises an IPv6 address. The actual Bob-Charlie communication may be via IPv4 or IPv6 (i.e., independent of Alice's address type).

• Messages 1-4 must be contained in a Data message in an existing session.

• Bob must send Alice's RI to Charlie prior to sending message 2.

• Bob must send Charlie's RI to Alice prior to sending message 4, if accepted (reason code 0).

• Messages 5-7 must be contained in a Peer Test message out-of-session.

• Messages 5 and 7 may contain the same signed data as sent in messages 3 and 4, or it may be regenerated with a new timestamp. Signature is optional.

• Message 6 may contain the same signed data as sent in messages 1 and 2, or it may be regenerated with a new timestamp. Signature is optional.

Signatures:

Alice signs the request and includes it in message 1; Bob forwards it in message 2 to Charlie. Charlie signs the response and includes it in message 3; Bob forwards it in message 4 to Alice. Signature algorithm: Sign or verify the following data with the Alice's or Charlie's signing key:

• prologue: 16 bytes "PeerTestValidate", not null-terminated (not included in the message)
• bhash: Bob's 32-byte router hash (not included in the message)
• ahash: Alice's 32-byte router hash (Only used in the signature for messages 3 and 4; not included in message 3 or 4)
• ver: 1 byte SSU version
• nonce: 4 byte test nonce
• timestamp: 4 byte timestamp (seconds)
• asz: 1 byte endpoint (port + IP) size (6 or 18)
• AlicePort: 2 byte Alice's port number
• Alice IP: (asz - 2) byte Alice IP address

NextNonce

TODO only if we rotate keys

+----+----+----+----+----+----+----+----+
| 11 |  size   |      TBD               |
+----+----+----+                        +
|                                       |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 11
size :: 2 bytes, big endian, size of data to follow

Ack

4 byte ack through, followed by an ack count and zero or more nack/ack ranges.

This design is adapted and simplified from QUIC. The design goals are as follows:

• We want to efficiently encode a "bitfield", which is a sequence of bits representing acked packets.
• The bitfield is mostly 1's. Both the 1's and the 0's generally come in sequential "clumps".
• The amount of room in the packet available for acks varies.
• The most important bit is the highest numbered one. Lower numbered ones are less important. Below a certain distance from the highest bit, the oldest bits will be "forgotten" and never sent again.

The encoding specified below accomplishes these design goals, by sending the number of the highest bit that is set to 1, together with additional consecutive bits lower than that which are also set to 1. After that, if there is room, one or more "ranges" specifying the number of consectutive 0 bits and consecutive 1 bits lower than that. See QUIC [RFC-9000] section 13.2.3 for more background.

+----+----+----+----+----+----+----+----+
| 12 |  size   |    Ack Through    |acnt|
+----+----+----+----+----+----+----+----+
|  range  |  range  |     .   .   .     |
+----+----+----+----+                   +
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 12
size :: 2 bytes, big endian, size of data to follow,
        5 minimum
ack through :: highest packet number acked
acnt :: number of acks lower than ack through also acked,
        0-255
range :: If present,
         1 byte nack count followed by 1 byte ack count,
         0-255 each

Examples:

We want to ACK packet 10 only:

• Ack Through: 10
• acnt: 0
• no ranges are included

We want to ACK packets 8-10 only:

• Ack Through: 10
• acnt: 2
• no ranges are included

We want to ACK 10 9 8 6 5 2 1 0, and NACK 7 4 3. The encoding of the ACK Block is:

• Ack Through: 10
• acnt: 2 (ack 9 8)
• range: 1 2 (nack 7, ack 6 5)
• range: 2 3 (nack 4 3, ack 2 1 0)

Notes:

• Ranges may not be present. Max number of ranges is not specified, may be as many as will fit in the packet.
• Range nack may be zero if acking more than 255 consecutive packets.
• Range ack may be zero if nacking more than 255 consecutive packets.
• Range nack and ack may not both be zero.
• After the last range, packets are neither acked nor nacked. Length of the ack block and how old acks/nacks are handled is up to the sender of the ack block. See ack sections below for discussion.
• The ack through should be the highest packet number received, and any packets higher have not been received. However, in limited situations, it could be lower, such as acking a single packet that "fills in a hole", or a simplified implementation that does not maintain the state of all received packets. Above the highest received, packets are neither acked nor nacked, but after several ack blocks, it may be appropriate to go into fast retransmit mode.
• This format is a simplified version of that in QUIC. It is designed to efficiently encode a large number of ACKs, together with bursts of NACKs.
• ACK blocks are used to acknowledge data phase packets. They are only to be included for in-session data phase packets.

Address

2 byte port and 4 or 16 byte IP address. Alice's address, sent to Alice by Bob, or Bob's address, sent to Bob by Alice.

+----+----+----+----+----+----+----+----+
| 13 | 6 or 18 |   Port  | IP Address
+----+----+----+----+----+----+----+----+
     |
+----+

blk :: 13
size :: 2 bytes, big endian, 6 or 18
port :: 2 bytes, big endian
ip :: 4 byte IPv4 or 16 byte IPv6 address,
      big endian (network byte order)

Relay Tag Request

This may be sent by Alice in a Session Request, Session Confirmed, or Data message. Not supported in the Session Created message, as Bob doesn't have Alice's RI yet, and doesn't know if Alice supports relay. Also, if Bob is getting an incoming connection, he probably doesn't need introducers (except perhaps for the other type ipv4/ipv6).

When sent in the Session Request, Bob may respond with a Relay Tag in the Session Created message, or may choose to wait until receiving Alice's RouterInfo in the Session Confirmed to validate Alice's identity before responding in a Data message. If Bob does not wish to relay for Alice, he does not send a Relay Tag block.

+----+----+----+
| 15 |    0    |
+----+----+----+

blk :: 15
size :: 2 bytes, big endian, value = 0

Relay Tag

This may be sent by Bob in a Session Confirmed or Data message, in response to a Relay Tag Request from Alice.

When the Relay Tag Request is sent in the Session Request, Bob may respond with a Relay Tag in the Session Created message, or may choose to wait until receiving Alice's RouterInfo in the Session Confirmed to validate Alice's identity before responding in a Data message. If Bob does not wish to relay for Alice, he does not send a Relay Tag block.

+----+----+----+----+----+----+----+
| 16 |    4    |    relay tag      |
+----+----+----+----+----+----+----+

blk :: 16
size :: 2 bytes, big endian, value = 4
relay tag :: 4 bytes, big endian, nonzero

New Token

For a subsequent connection. Generally included in the Session Created and Session Confirmed messages. May also be sent again in the Data message of a long-lived session if the previous token expires.

+----+----+----+----+----+----+----+----+
| 17 |   12    |     expires       |
+----+----+----+----+----+----+----+----+
                token              |
+----+----+----+----+----+----+----+

blk :: 17
size :: 2 bytes, big endian, value = 12
expires :: Unix timestamp, unsigned seconds.
           Wraps around in 2106
token :: 8 bytes, big endian

Path Challenge

A Ping with arbitrary data to be returned in a Path Response, used as a keep-alive or to validate an IP/Port change.

+----+----+----+----+----+----+----+----+
| 18 |  size   |    Arbitrary Data      |
+----+----+----+                        +
|                                       |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 18
size :: 2 bytes, big endian, size of data to follow
data :: Arbitrary data to be returned in a Path Response
        length as selected by sender

Notes:

A minimum data size of 8 bytes, containing random data, is recommended but not required.

Path Response

A Pong with the data received in the Path Challenge, as reply to the Path Challenge, used as a keep-alive or to validate an IP/Port change.

+----+----+----+----+----+----+----+----+
| 19 |  size   |                        |
+----+----+----+                        +
|    Data received in Path Challenge    |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 19
size :: 2 bytes, big endian, size of data to follow
data :: As received in a Path Challenge

First Packet Number

Optionally included in the handshake in each direction, to specify the first packet number that will be sent. This provides more security for header encryption, similar to TCP.

Not fully specified, not currently supported.

+----+----+----+----+----+----+----+
| 20 |  size   |  First pkt number |
+----+----+----+----+----+----+----+

blk :: 20
size :: 4
pkt num :: The first packet number to be sent in the data phase

Congestion

This is block is designed to be an extensible method to exchange congestion control information. Congestion control can be complex and may evolve as we get more experience with the protocol in live testing, or after full rollout.

This keeps any congestion information out of the high-usage I2NP, First Fragment, Followon Fragment, and ACK blocks, where there is no space for flags allocated. While there are three bytes of unused flags in the Data packet header, that also provides limited space for extensibility, and weaker encryption protection.

While it is somewhat wasteful to use a 4-byte block for two bits of information, by putting this in a separate block, we can easily extend it with additional data such as current window sizes, measured RTT, or other flags. Experience has shown that flag bits alone is often insufficient and awkward for implementation of advanced congestion control schemes. Trying to add support for any possible congestion control feature in, for example, the ACK block, would waste space and add complexity to the parsing of that block.

Implementations should not assume that the other router supports any particular flag bit or feature included here, unless implementation is required by a future version of this specification.

This block should probably be the last non-padding block in the payload.

+----+----+----+----+
| 21 |  size   |flag|
+----+----+----+----+

blk :: 21
size :: 1 (or more if extended)
flag :: 1 byte flags
       bit order: 76543210 (bit 7 is MSB)
       bit 0: 1 to request immediate ack
       bit 1: 1 for explicit congestion notification (ECN)
       bits 7-2: Unused, set to 0 for future compatibility

Padding

This is for padding inside AEAD payloads. Padding for all messages are inside AEAD payloads.

Padding 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 payload.

+----+----+----+----+----+----+----+----+
|254 |  size   |      padding           |
+----+----+----+                        +
|                                       |
~               .   .   .               ~
|                                       |
+----+----+----+----+----+----+----+----+

blk :: 254
size :: 2 bytes, big endian, size of padding to follow
padding :: random data

Notes:

• Size = 0 is allowed.
• Padding strategies TBD.
• Minimum padding TBD.
• Padding-only payloads are allowed.
• Padding defaults TBD.
• See options block for padding parameter negotiation
• See options block for min/max padding parameters
• Do not exceed the MTU. If more padding is necessary, send multiple messages.
• Router response on violation of negotiated padding is implementation-dependent.
• 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 of [NTCP2] provides more information on the topic.

Peer Address Spoofing

A peer may 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.

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 that is sent to it even if it wanted to.

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.

Privacy Implications

QUIC [RFC-9000] specified changing connection IDs when changing network paths. 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. However, QUIC does not encrypt the connection IDs in the header. SSU2 does do that, so the privacy leak would require the passive observer to also have access to the network database to get the introduction key required to decrypt the connection ID. Even with the introduction key, this is not a strong attack, and we do not change connection IDs after migration in SSU2, as this would be a significant complication.

Introducer Selection

In SSU 1, introduction is relatively inexpensive, and Alice generally sends Relay Requests to all introducers. In SSU 2, introduction is more expensive, as a connection must first be established with an introducer. To minimize introduction latency and overhead, the recommended processing steps are as follows:

• Ignore any introducers that are expired based on the iexp value in the address
• If an SSU2 connection is already established to one or more introducers, pick one and send the Relay Request to that introducer only.
• Otherwise, if a Router Info is locally known for one or more introducers, pick one and connect to that introducer only.
• Otherwise, lookup the Router Infos for all introducers, connect to the introducer whose Router Info is received first.

Response Handling

In both SSU 1 and SSU 2, the Relay Response and Hole Punch may be received in either order, or may not be received at all.

In SSU 1, Alice usually receives the Relay Response (1 RTT) before the Hole Punch (1 1/2 RTT). It may not be well-documented in those specifications, but Alice must receive the Relay Response from Bob before continuing, to receive Charlie's IP. If the Hole Punch is received first, Alice will not recognize it, because it contains no data and the source IP is not recognized. After receiving the Relay Response, Alice should wait for EITHER receiving the Hole Punch from Charlie, OR a short delay (recommended 500 ms) before initiating the handshake with Charlie.

In SSU 2, Alice will usually receive the Hole Punch (1 1/2 RTT) before the Relay Response (2 RTT). The SSU 2 Hole Punch is easier to process than in SSU 1, because it is a full message with defined connection IDs (derived from the relay nonce) and contents including Charlie's IP. The Relay Response (Data message) and Hole Punch message contain the identical signed Relay Response block. Therefore, Alice may initiate the handshake with Charlie after EITHER receiving the Hole Punch from Charlie, OR receiving the Relay Response from Bob.

The signature verification of the Hole Punch includes the introducer's (Bob's) router hash. If Relay Requests have been sent to more than one introducer, there are several options to validate the signature:

• Try each hash to which a request was sent
• Use different nonces for each introducer, and use that to determine which introducer this Hole Punch was in response to
• Don't re-validate the signature if the contents are identical to that in the Relay Response, if already received
• Don't validate the signature at all

If Charlie is behind a symmetric NAT, his reported port in the Relay Response and Hole Punch may not be accurate. Therefore, Alice should check the UDP source port of the Hole Punch message, and use that if it is different than the reported port.

Introducers

When published as SSU or SSU2 with introducers, the following options are present:

• ih[0-2]=(Base64 hash) A router hash for an introducer. Base 64 encoded using the standard I2P Base 64 alphabet. 32 bytes in binary, 44 bytes as Base 64 encoded
• iexp[0-2]: Expiration of this introducer. Unchanged from SSU 1.
• itag[0-2]: Introducer's tag 1 - (2**32 - 1) Unchanged from SSU 1.

The following options are for SSU only and are not used for SSU2. In SSU2, Alice gets this information from Charlie's RI instead.

• ihost[0-2]
• ikey[0-2]
• itag[0-2]

A router must not publish host or port in the address when publishing introducers. A router must publish 4 and/or 6 caps in the address when publishing introducers to indicate support for IPv4 and/or IPv6. This is the same as the current practice for recent SSU 1 addresses.

Note: If published as SSU, and there is a mix of SSU 1 and SSU2 introducers, the SSU 1 introducers should be at the lower indexes and the SSU2 introducers should be at the higher indexes, for compatibility with older routers.

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 not, but must include it in the RI sent to Bob.

Summary

Initial processing of all inbound messages:

• Decrypt the first 8 bytes of the header (the Destination Connection ID) with the intro key
• Lookup the connection by the Destination Connection ID
• If the connection is found and is in the data phase, go to the data phase section
• If the connection is not found, go to the handshake section
• Note: Peer Test and Hole Punch messages may also be looked up by the Destination Connection ID created from the test or relay nonce.

Handshake messages (Session Request/Created/Confirmed, Retry, Token Request) and other out-of-session messages (Peer Test, Hole Punch) processing:

• Decrypt bytes 8-15 of the header (the packet type, version, and net ID) with the intro key. If it is a valid Session Request, Token Request, Peer Test, or Hole Punch, continue
• If not a valid message, lookup a pending outbound connection by the packet source IP/port, treat the packet as a Session Created or Retry. Re-decrypt the first 8 bytes of the header with the correct key, and the bytes 8-15 of the header (the packet type, version, and net ID). If it is a valid Session Created or Retry, continue
• If not a valid message, fail, or queue as a possible out-of-order data phase packet
• For Session Request/Created, Retry, Token Request, Peer Test, and Hole Punch, decrypt bytes 16-31 of the header
• For Session Request/Created, decrypt the ephemeral key
• Validate all header fields, stop if not valid
• mixHash() the header
• For Session Request/Created/Confirmed, decrypt the payload using Noise
• For Retry and data phase, decrypt the payload using ChaChaPoly
• Process the header and payload

Data phase messages processing:

• Decrypt bytes 8-15 of the header (the packet type, version, and net ID) with the correct key
• Decrypt the payload using ChaChaPoly using the header as AD
• Process the header and payload

Details

In SSU 1, inbound packet classification is difficult, because there is no header to indicate session number. Routers must first match the source IP and port to an existing peer state, and if not found, attempt multiple decryptions with different keys to find the appropriate peer state or start a new one. In the event that the source IP or port for an existing session changes, possibly due to NAT behavior, the router may use expensive heuristics to attempt to match the packet to an existing session and recover the contents.

SSU 2 is designed to minimize the inbound packet classification effort while maintaining DPI resistance and other on-path threats. The Connection ID number is included in the header for all message types, and encrypted (obfuscated) using ChaCha20 with a known key and nonce. Additionally, the message type is also included in the header (encrypted with header protection to a known key and then obfuscated with ChaCha20) and may be used for additional classification. In no case is a trial DH or other asymmetric crypto operation necessary to classify a packet.

For almost all messages from all peers, the ChaCha20 key for the Connection ID encryption is the destination router's introduction key as published in the netdb.

The only exceptions are the first messages sent from Bob to Alice (Session Created or Retry) where Alice's introduction key is not yet known to Bob. In these cases, Bob's introduction key is used as the key.

The protocol is designed to minimize packet classification processing that might require additional crypto operations in multiple fallback steps or complex heuristics. Additionally, the vast majority of received packets will not require a (possibly expensive) fallback lookup by source IP/port and a second header decryption. Only Session Created and Retry (and possibly others TBD) will require the fallback processing. If an endpoint changes IP or port after session creation, the connection ID is still used to lookup the session. It is never necessary to use heuristics to find the session, for example by looking for a different session with the same IP but a different port.

Therefore, the recommended processing steps in the receiver loop logic are:

1. Decrypt the first 8 bytes with ChaCha20 using the local introduction key, to recover the Destination Connection ID. If the Connection ID matches a current or pending inbound session:

   1. Using the appropriate key, decrypt the header bytes 8-15 to recover the version, net ID, and message type.
   2. If the message type is Session Confirmed, it is a long header. Verify the net ID and protocol version are valid. Decrypt the bytes 15-31 of the header with ChaCha20 using the local intro key. Then MixHash() the decrypted 32 byte header and decrypt the message with Noise.
   3. If the message type is valid but not Session Confirmed, it is a short header. Verify the net ID and protocol version are valid. decrypt the rest of the message with ChaCha20/Poly1305 using the session key, using the decrypted 16-byte header as the AD.
   4. (optional) If connection ID is a pending inbound session awaiting a Session Confirmed message, but the net ID, protocol, or message type is not valid, it could be a Data message received out-of-order before the Session Confirmed, so the data phase header protection keys are not yet known, and the header bytes 8-15 were incorrectly decrypted. Queue the message, and attempt to decrypt it once the Session Confirmed message is received.
   5. If b) or c) fails, drop the message.

2. If the connection ID does not match a current session: Check the plaintext header at bytes 8-15 are valid (without doing any header protection operation). Verify the net ID and protocol version are valid, and the message type is Session Request, or other message type allowed out-of-session (TBD).

   1. If all is valid and the message type is Session Request, decrypt bytes 16-31 of the header and the 32-byte X value with ChaCha20 using the local intro key.
   • If the token at header bytes 24-31 is accepted, then MixHash() the decrypted 32 byte header and decrypt the message with Noise. Send a Session Created in response.
   • If the token is not accepted, send a Retry message to the source IP/port with a token. Do not attempt to decrypt the message with Noise to avoid DDoS attacks.
   2. If the message type is some other message that is valid out-of-session, presumably with a short header, decrypt the rest of the message with ChaCha20/Poly1305 using the intro key, and using the decrypted 16-byte header as the AD. Process the message.
   3. If a) or b) fails, go to step 3)

3. Look up a pending outbound session by the source IP/port of the packet.

   1. If found, re-decrypt the first 8 bytes with ChaCha20 using Bob's introduction key to recover the Destination Connection ID.
   2. If the connection ID matches the pending session: Using the correct key, decrypt bytes 8-15 of the header to recover the version, net ID, and message type. Verify the net ID and protocol version are valid, and the message type is Session Created or Retry, or other message type allowed out-of-session (TBD).
   • If all is valid and the message type is Session Created, decrypt the next 16 bytes of the header and the 32-byte Y value with ChaCha20 using Bob's intro key. Then MixHash() the decrypted 32 byte header and decrypt the message with Noise. Send a Session Confirmed in response.
   • If all is valid and the message type is Retry, decrypt bytes 16-31 of the header with ChaCha20 using Bob's intro key. Decrypt and validate the message using ChaCha20/Poly1305 using TBD as the key and TBD as the nonce and the decrypted 32-byte header as the AD. Resend a Session Request with the received token in response.
   • If the message type is some other message that is valid out-of-session, presumably with a short header, decrypt the rest of the message with ChaCha20/Poly1305 using the intro key, and using the decrypted 16-byte header as the AD. Process the message.

   3. If a pending outbound session is not found, or the connection ID does not match the pending session, drop the message, unless the port is shared with SSU 1.

4. If running SSU 1 on the same port, attempt to process the message as an SSU 1 packet.

Error Handling

In general, a session (in the handshake or data phase) should never be destroyed after receiving a packet with an unexpected message type. This prevents packet injection attacks. These packets will also commonly be received after retransmission of a handshake packet, when the header decryption keys are no longer valid.

In most cases, simply drop the packet. An implementation may, but is not required to, retransmit the previously-sent packet (handshake message or ACK 0) in response.

After sending Session Created as Bob, unexpected packets are commonly Data packets that cannot be decrypted because the Session Confirmed packets were lost or out-of-order. Queue the packets and attempt to decrypt them after receiving the Session Confirmed packets.

After receiving Session Confirmed as Bob, unexpected packets are commonly retransmitted Session Confirmed packets, because the ACK 0 of the Sesssion Confirmed was lost. The unexpected packets may be dropped. An implementation may, but is not required to, send a Data packet containing an ACK block in response.