SSU (also called "UDP" in much of the I2P documentation and user interfaces) is one of two transports currently implemented in I2P. The other is NTCP.
SSU is the newer of the two transports, introduced in I2P release 0.6. In a standard I2P installation, the router uses both NTCP and SSU for outbound connections.
SSU's need for only semireliable delivery, TCP-friendly operation, and the capacity for high throughput allows a great deal of latitude in congestion control. The congestion control algorithm outlined below is meant to be both efficient in bandwidth as well as simple to implement.
Packets are scheduled according to the router's policy, taking care not to exceed the router's outbound capacity or to exceed the measured capacity of the remote peer. The measured capacity operates along the lines of TCP's slow start and congestion avoidance, with additive increases to the sending capacity and multiplicative decreases in face of congestion. Unlike for TCP, routers may give up on some messages after a given period or number of retransmissions while continuing to transmit other messages.
The congestion detection techniques vary from TCP as well, since each message has its own unique and nonsequential identifier, and each message has a limited size - at most, 32KB. To efficiently transmit this feedback to the sender, the receiver periodically includes a list of fully ACKed message identifiers and may also include bitfields for partially received messages, where each bit represents the reception of a fragment. If duplicate fragments arrive, the message should be ACKed again, or if the message has still not been fully received, the bitfield should be retransmitted with any new updates.
The current implementation does not pad the packets to any particular size, but instead just places a single message fragment into a packet and sends it off (careful not to exceed the MTU).
As of router version 0.8.12, two MTU values are used for IPv4: 620 and 1484. The MTU value is adjusted based on the percentage of packets that are retransmitted.
For both MTU values, it is desirable that (MTU % 16) == 12, so that the payload portion after the 28-byte IP/UDP header is a multiple of 16 bytes, for encryption purposes.
For the small MTU value, it is desirable to pack a 2646-byte Variable Tunnel Build Message efficiently into multiple packets; with a 620-byte MTU, it fits into 5 packets with nicely.
Based on measurements, 1492 fits nearly all reasonably small I2NP messages (larger I2NP messages may be up to 1900 to 4500 bytes, which isn't going to fit into a live network MTU anyway).
The MTU values were 608 and 1492 for releases 0.8.9 - 0.8.11. The large MTU was 1350 prior to release 0.8.9.
The maximum receive packet size is 1571 bytes as of release 0.8.12. For releases 0.8.9 - 0.8.11 it was 1535 bytes. Prior to release 0.8.9 it was 2048 bytes.
As of release 0.9.2, if a router's network interface MTU is less than 1484, it will publish that in the network database, and other routers should honor that when a connection is established.
For IPv6, the minimum MTU is 1280. The IPv6 IP/UDP header is 48 bytes, so we use an MTU where (MTN % 16 == 0), which is true for 1280.
While the maximum message size is nominally 32KB, the practical limit differs. The protocol limits the number of fragments to 7 bits, or 128. The current implementation, however, limits each message to a maximum of 64 fragments, which is sufficient for 64 * 534 = 33.3 KB when using the 608 MTU. Due to overhead for bundled LeaseSets and session keys, the practical limit at the application level is about 6KB lower, or about 26KB. Further work is necessary to raise the UDP transport limit above 32KB. For connections using the larger MTU, larger messages are possible.
All encryption used is AES256/CBC with 32 byte keys and 16 byte IVs. The MAC and session keys are negotiated as part of the DH exchange, used for the HMAC and encryption, respectively. Prior to the DH exchange, the publicly knowable introKey is used for the MAC and encryption.
When using the introKey, both the initial message and any subsequent reply use the introKey of the responder (Bob) - the responder does not need to know the introKey of the requester (Alice). The DSA signing key used by Bob should already be known to Alice when she contacts him, though Alice's DSA key may not already be known by Bob.
Upon receiving a message, the receiver checks the "from" IP address and port with all established sessions - if there are matches, that session's MAC keys are tested in the HMAC. If none of those verify or if there are no matching IP addresses, the receiver tries their introKey in the MAC. If that does not verify, the packet is dropped. If it does verify, it is interpreted according to the message type, though if the receiver is overloaded, it may be dropped anyway.
If Alice and Bob have an established session, but Alice loses the keys for some reason and she wants to contact Bob, she may at any time simply establish a new session through the SessionRequest and related messages. If Bob has lost the key but Alice does not know that, she will first attempt to prod him to reply, by sending a DataMessage with the wantReply flag set, and if Bob continually fails to reply, she will assume the key is lost and reestablish a new one.
For the DH key agreement, RFC3526 2048bit MODP group (#14) is used:
p = 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 }
g = 2
These are the same p and g used for I2P's ElGamal encryption.
Replay prevention at the SSU layer occurs by rejecting packets with exceedingly old timestamps or those which reuse an IV. To detect duplicate IVs, a sequence of Bloom filters are employed to "decay" periodically so that only recently added IVs are detected.
The messageIds used in DataMessages are defined at layers above the SSU transport and are passed through transparently. These IDs are not in any particular order - in fact, they are likely to be entirely random. The SSU layer makes no attempt at messageId replay prevention - higher layers should take that into account.
To contact an SSU peer, one of two sets of information is necessary: a direct address, for when the peer is publicly reachable, or an indirect address, for using a third party to introduce the peer. There is no restriction on the number of addresses a peer may have.
Direct: host, port, introKey, options
Indirect: tag, relayhost, port, relayIntroKey, targetIntroKey, options
Each of the addresses may also expose a series of options - special capabilities of that particular peer. For a list of available capabilities, see below.
The addresses, options, and capabilities are published in the network database.
Direct session establishment is used when no third party is required for NAT traversal. The message sequence is as follows:
Alice connects directly to Bob.
Alice Bob
SessionRequest --------------------->
<--------------------- SessionCreated
SessionConfirmed ------------------->
<--------------------- DeliveryStatusMessage
<--------------------- DatabaseStoreMessage
DatabaseStoreMessage --------------->
Data <---------------------------> Data
After the SessionConfirmed message is received, Bob sends a small DeliveryStatus message as a confirmation. In this message, the 4-byte message ID is set to a random number, and the 8-byte "arrival time" is set to the current network-wide ID, which is 2 (i.e. 0x0000000000000002).
After the status message is sent, the peers exchange DatabaseStore messages containing their RouterInfos.
It does not appear that the type of the status message or its contents matters. It was originally added becasue the DatabaseStore message was delayed several seconds; since the store is now sent immediately, perhaps the status message can be eliminated.
Introduction keys are delivered through an external channel (the network database, where they are identical to the router Hash for now) and must be used when establishing a session key. For the indirect address, the peer must first contact the relayhost and ask them for an introduction to the peer known at that relayhost under the given tag. If possible, the relayhost sends a message to the addressed peer telling them to contact the requesting peer, and also gives the requesting peer the IP and port on which the addressed peer is located. In addition, the peer establishing the connection must already know the public keys of the peer they are connecting to (but not necessary to any intermediary relay peer).
Indirect session establishment by means of a third party introduction is necessary for efficient NAT traversal. Charlie, a router behind a NAT or firewall which does not allow unsolicited inbound UDP packets, first contacts a few peers, choosing some to serve as introducers. Each of these peers (Bob, Bill, Betty, etc) provide Charlie with an introduction tag - a 4 byte random number - which he then makes available to the public as methods of contacting him. Alice, a router who has Charlie's published contact methods, first sends a RelayRequest packet to one or more of the introducers, asking each to introduce her to Charlie (offering the introduction tag to identify Charlie). Bob then forwards a RelayIntro packet to Charlie including Alice's public IP and port number, then sends Alice back a RelayResponse packet containing Charlie's public IP and port number. When Charlie receives the RelayIntro packet, he sends off a small random packet to Alice's IP and port (poking a hole in his NAT/firewall), and when Alice receives Bob's RelayResponse packet, she begins a new full direction session establishment with the specified IP and port.
Alice Bob Charlie
RelayRequest ---------------------->
<-------------- RelayResponse RelayIntro ----------->
<-------------------------------------------- HolePunch (data ignored)
SessionRequest -------------------------------------------->
<-------------------------------------------- SessionCreated
SessionConfirmed ------------------------------------------>
<-------------------------------------------- DeliveryStatusMessage
<-------------------------------------------- DatabaseStoreMessage
DatabaseStoreMessage -------------------------------------->
Data <--------------------------------------------------> Data
After the hole punch, the session is established between Alice and Charlie as in a direct establishment.
IPv6 notes: Alice-Bob communication may be via IPv4 or IPv6. Bob-Charlie and Alice-Charlie communication is via IPv4.
The automation of collaborative reachability testing for peers is enabled by a sequence of PeerTest messages. With its proper execution, a peer will be able to determine their own reachability and may update its behavior accordingly. The testing process is quite simple:
Alice Bob Charlie
PeerTest ------------------->
PeerTest-------------------->
<-------------------PeerTest
<-------------------PeerTest
<------------------------------------------PeerTest
PeerTest------------------------------------------>
<------------------------------------------PeerTest
Each of the PeerTest messages carry a nonce identifying the test series itself, as initialized by Alice. If Alice doesn't get a particular message that she expects, she will retransmit accordingly, and based upon the data received or the messages missing, she will know her reachability. The various end states that may be reached are as follows:
Alice should choose Bob arbitrarily from known peers who seem to be capable of participating in peer tests. Bob in turn should choose Charlie arbitrarily from peers that he knows who seem to be capable of participating in peer tests and who are on a different IP from both Bob and Alice. If the first error condition occurs (Alice doesn't get PeerTest messages from Bob), Alice may decide to designate a new peer as Bob and try again with a different nonce.
Alice's introduction key is included in all of the PeerTest messages so that she doesn't need to already have an established session with Bob and so that Charlie can contact her without knowing any additional information. Alice may go on to establish a session with either Bob or Charlie, but it is not required.
IPv6 Notes: Only testing of IPv4 addresses is supported. Therefore, all Alice-Bob and Alice-Charlie communication must be via IPv4. Bob-Charlie communication, however, may be via IPv4 or IPv6. Alice's address, when specified in the PeerTest message, must be 4 bytes.
The DATA message may contain ACKs of full messages and partial ACKs of individual fragments of a message. See the data message section of the protocol specification page for details.
The details of windowing, ACK, and retransmission strategies are not specified here. See the Java code for the current implementation. During the establishment phase, and for peer testing, routers should implement exponential backoff for retransmission. For an established connection, routers should implement an adjustable transmission window, RTT estimate and timeout, similar to TCP or streaming. See the code for initial, min and max parameters.
UDP source addresses may, of course, be spoofed. Additionally, the IPs and ports contained inside specific SSU messages (RelayRequest, RelayResponse, RelayIntro, PeerTest) may not be legitimate. Also, certain actions and responses may need to be rate-limited.
The details of validation are not specified here. Implementers should add defenses where appropriate.