Important note

Code before release 0.9.8 was broken and did not correctly handle DH key byte arrays between 32 and 63 bytes (steps 3 and 4 above) and the connection will fail. As these cases didn't ever work, they were redefined as described above for release 0.9.8, and the 0-32 byte case was redefined as well. Since the nominal exchanged DH key is 256 bytes, the chances of the mininimal representation being less than 64 bytes is vanishingly small.

Extended options

Note: Implemented in 0.9.24.

• Minimum length: 3 (option length byte + 2 bytes)
• Option length: 2 minimum
• 2 bytes flags:

  Bit order: 15...76543210 (bit 15 is MSB)

      bit 0: 1 for Alice to request a relay tag from Bob in the
             SessionCreated response, 0 if Alice does not need a relay tag.
             Note that "1" is the default if no extended options are present
  bits 15-1: unused, set to 0 for compatibility with future uses

Notes

• IPv4 and IPv6 addresses are supported.
• The uninterpreted data could possibly be used in the future for challenges.

Notes

• IPv4 and IPv6 addresses are supported.
• If the relay tag is nonzero, Bob is offering to act as an introducer for Alice. Alice may subsequently publish Bob's address and the relay tag in the network database.
• For the signature, Bob must use his external port, as that what Alice will use to verify. If Bob's NAT/firewall has mapped his internal port to a different external port, and Bob is unaware of it, the verification by Alice will fail.
• See the Keys section above for details on signatures. Alice already has Bob's public signing key, from the network database.
• Through release 0.9.15, the signature was always a 40 byte DSA signature and the padding was always 8 bytes. As of release 0.9.16, the signature type and length are implied by the type of the [SigningPublicKey] in Bob's [RouterIdentity]. The padding is as necessary to a multiple of 16 bytes.
• This is the only message that uses the sender's intro key. All others use the receiver's intro key or the established session key.
• Signed-on time appears to be unused or unverified in the current implementation.
• The uninterpreted data could possibly be used in the future for challenges.
• Extended options in the header: Not expected, undefined.

Notes

• In the current implementation, the maximum fragment size is 512 bytes. This should be extended so that longer signatures will work without fragmentation. The current implementation does not correctly process signatures split across two fragments.
• The typical [RouterIdentity] is 387 bytes, so no fragmentation is ever necessary. If new crypto extends the size of the RouterIdentity, the fragmentation scheme must be tested carefully.
• There is no mechanism for requesting or redelivering missing fragments.
• The total fragments field F must be set identically in all fragments.
• See the Keys section above for details on DSA signatures.
• Signed-on time appears to be unused or unverified in the current implementation.
• Since the signature is at the end, the padding in the last or only packet must pad the total packet to a multiple of 16 bytes, or the signature will not get decrypted correctly. This is different from all the other message types, where the padding is at the end.
• Through release 0.9.15, the signature was always a 40 byte DSA signature. As of release 0.9.16, the signature type and length are implied by the type of the [SigningPublicKey] in Alice's [RouterIdentity]. The padding is as necessary to a multiple of 16 bytes.
• Extended options in the header: Not expected, undefined.

Notes

• Destroy messages received with the sender's or receiver's intro key will be ignored.
• Extended options in the header: Not expected, undefined.

Notes

• The IP address is only included if it is be different than the packet's source address and port.
• This message may be sent via IPv4 or IPv6. If the message is over IPv6 for an IPv4 introduction, or (as of release 0.9.50) over IPv4 for an IPv6 introduction, Alice must include her introduction address and port. This is supported as of release 0.9.50.
• If Alice includes her address/port, Bob may perform additional validation before continuing.
  • Prior to release 0.9.24, Java I2P rejected any address or port that was different from the connection.
• Challenge is unimplemented, challenge size is always zero
• Relaying for IPv6 is supported as of release 0.9.50.
• Prior to release 0.9.12, Bob's intro key was always used. As of release 0.9.12, the session key is used if there is an established session between Alice and Bob. In practice, there must be an established session, as Alice will only get the nonce (introduction tag) from the session created message, and Bob will mark the introduction tag invalid once the session is destroyed.
• Extended options in the header: Not expected, undefined.

Notes

• This message may be sent via IPv4 or IPv6.
• Alice's IP address/port are the apparent IP/port that Bob received the RelayRequest on (not necessarily the IP Alice included in the RelayRequest), and may be IPv4 or IPv6. Alice currently ignores these on receive.
• Charlie's IP address may be IPv4, or, as of release 0.9.50, IPv6. as that is the address that Alice will send the SessionRequest to after the Hole Punch.
• Relaying for IPv6 is supported as of release 0.9.50.
• Prior to release 0.9.12, Alice's intro key was always used. As of release 0.9.12, the session key is used if there is an established session between Alice and Bob.
• Extended options in the header: Not expected, undefined.

Notes

• For IPv4, Alice's IP address is always 4 bytes, because Alice is trying to connect to Charlie via IPv4. As of release 0.9.xx, IPv6 is supported, and Alice's IP address may be 16 bytes.
• 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.
• 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. As of release 0.9.50, IPv6 is supported, and this message may be sent via an established IPv6 connection.
• As of release 0.9.50, any SSU address published with introducers must contain "4" or "6" in the "caps" option.
• Challenge is unimplemented, challenge size is always zero
• Extended options in the header: Not expected, undefined.

Notes

• The current implementation adds a limited number of duplicate acks for messages previously acked, if space is available.
• If the number of fragments is zero, this is an ack-only or keepalive message.
• The ECN feature is unimplemented, and the bit is never set.
• In the current implementation, the want reply bit is set when the number of fragments is greater then zero, and not set when there are no fragments.
• Extended data is unimplemented and never present.
• Reception of multiple fragments is supported in all releases. Transmission of multiple fragments is implemented in release 0.9.16.
• As currently implemented, maximum fragments is 64 (maximum fragment number = 63).
• As currently implemented, maximum fragment size is of course less than the MTU.
• Take care not to exceed the maximum MTU even if there is a large number of ACKs to send.
• The protocol allows zero-length fragments but there's no reason to send them.
• In SSU, the data uses a short 5-byte I2NP header followed by the payload of the I2NP message instead of the standard 16-byte I2NP header. The short I2NP header consists only of the one-byte I2NP type and 4-byte expiration in seconds. The I2NP message ID is used as the message ID for the fragment. The I2NP size is assembled from the fragment sizes. The I2NP checksum is not required as UDP message integrity is ensured by decryption.
• Message IDs are not sequence numbers and are not consecutive. SSU does not guarantee in-order delivery. While we use the I2NP message ID as the SSU message ID, from the SSU protocol view, they are random numbers. In fact, since the router uses a single Bloom filter for all peers, the message ID must be an actual random number.
• Because there are no sequence numbers, there is no way to be sure an ACK was received. The current implementation routinely sends a large amount of duplicate ACKs. Duplicate ACKs should not be taken as an indication of congestion.
• ACK Bitfield notes: The receiver of a data packet does not know how many fragments are in the message unless it has received the last fragment. Therefore, the number of bitfield bytes sent in response may be less or more than the number of fragments divided by 7. For example, if the highest fragment the receiver has seen is number 4, only one byte is required to be sent, even if there may be 13 fragments total. Up to 10 bytes (i.e. (64 / 7) + 1) may be included for each message ID acked.
• Extended options in the header: Not expected, undefined.

Notes

• When sent by Alice, IP address size is 0, IP address is not present, and port is 0, as Bob and Charlie do not use the data; the point is to determine Alice's true IP address/port and tell Alice; Bob and Charlie don't care what Alice thinks her address is.

• When sent by Bob or Charlie, IP and port are present, and IP address is 4 or 16 bytes. IPv6 testing is supported as of release 0.9.27.

• When sent by Charlie to Alice, the IP and port are as follows: First time (message 5): Alice's requested IP and port as received in message 2. Second time (message 7): Alice's actual IP and port that message 6 was received from.

• IPv6 Notes: Through release 0.9.26, 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. As of release 0.9.27, 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).

• A peer must maintain a table of active test states (nonces). On reception of a PeerTest message, look up the nonce in the table. If found, it's an existing test and you know your role (Alice, Bob, or Charlie). Otherwise, if the IP is not present and the port is 0, this is a new test and you are Bob. Otherwise, this is a new test and you are Charlie.

• As of release 0.9.15, Alice must have an established session with Bob and use the session key.

• Prior to API version 0.9.52, in some implementations, Bob replied to Alice using Alice's intro key rather than the Alice/Bob session key, even though Alice and Bob have an established session (since 0.9.15). As of API version 0.9.52, Bob will correctly use the session key in all implementations, and Alice should reject a message received from Bob with Alice's intro key if Bob is API version 0.9.52 or higher.

• Extended options in the header: Not expected, undefined.