Updated December 2011 for release 0.8.11

See the SSU page for an overview of the SSU transport.

Specification

DH Key Exchange

The initial 2048-bit DH key exchange is described on the SSU page. This exchange uses the same shared prime as that used for I2P's ElGamal encryption.

All UDP datagrams begin with a 16 byte MAC (Message Authentication Code) and a 16 byte IV (Initialization Vector) followed by a variable-size payload encrypted with the appropriate key. The MAC used is HMAC-MD5, truncated to 16 bytes, while the key is a full 32 byte AES256 key. The specific construct of the MAC is the first 16 bytes from:

  HMAC-MD5(payload || IV || (payloadLength ^ protocolVersion), macKey)

where '||' means append. The payload is the message starting with the flag byte. The macKey is either the introduction key or the session key, as specified for each message below.

The payload itself (that is, the message starting with the flag byte) is AES256/CBC encrypted with the IV and the sessionKey, with replay prevention addressed within its body, explained below. The payloadLength in the MAC is a 2 byte unsigned integer.

The protocolVersion is a 2 byte unsigned integer and is currently set to 0. Peers using a different protocol version will not be able to communicate with this peer, though earlier versions not using this flag are.

Within the AES encrypted payload, there is a minimal common structure to the various messages - a one byte flag and a four byte sending timestamp (seconds since the unix epoch). The flag byte contains the following bitfields:

  Bit order: 76543210 (bit 7 is MSB)

  bits 7-4: payload type
     bit 3: rekey?
     bit 2: extended options included
  bits 1-0: reserved

 Header: 37+ bytes
 Encryption starts with the flag byte.
 +----+----+----+----+----+----+----+----+
 |                  MAC                  |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |                   IV                  |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |flag|        time       | (optionally  |
 +----+----+----+----+----+              |
 | this may have 64 byte keying material |
 | and/or a one+N byte extended options) |
 +---------------------------------------|

Rekeying

If the rekey flag is set, 64 bytes of keying material follow the timestamp.

When rekeying, the first 32 bytes of the keying material is fed into a SHA256 to produce the new MAC key, and the next 32 bytes are fed into a SHA256 to produce the new session key, though the keys are not immediately used. The other side should also reply with the rekey flag set and that same keying material. Once both sides have sent and received those values, the new keys should be used and the previous keys discarded. It may be useful to keep the old keys around briefly, to address packet loss and reordering.

NOTE: Rekeying is currently unimplemented.

Extended Options

If the extended options flag is set, a one byte option size value is appended, followed by that many extended option bytes.

NOTE: Extended options is currently unimplemented.

Padding

All messages contain 0 or more bytes of padding. Each message must be padded to a 16 byte boundary, as required by the AES256 encryption layer. Currently, messages are not padded beyond the next 16 byte boundary. The fixed-size tunnel messages of 1024 bytes (at a higher layer) provide a significant amount of protection. In the future, additional padding in the transport layer up to a set of fixed packet sizes may be appropriate to further hide the data fragmentation to external adversaries.

Keys

Both introduction keys and session keys are 32 bytes, and are defined by the Common structures specification. The key used for the MAC and encryption is specified for each message below.

Introduction keys are delivered through an external channel (the network database, where they are identical to the router Hash for now).

Notes

IPv6 Notes

While the protocol specification supports 16-byte IPv6 addresses, IPv6 addressing is not currently supported within I2P. All IP addresses are currently 4 bytes.

Timestamps

While most of I2P uses 8-byte Date timestamps with millisecond resolution, SSU uses a 4-byte timestamp with one-second resolution.

Messages

There are 10 messages (payload types) defined:

Type	Message	Notes
0	SessionRequest
1	SessionCreated
2	SessionConfirmed
3	RelayRequest
4	RelayResponse
5	RelayIntro
6	Data
7	PeerTest
8	SessionDestroyed	Implemented as of 0.8.9
n/a	HolePunch

SessionRequest (type 0)

This is the first message sent to establish a session.

Peer:	Alice to Bob
Data:	256 byte X, to begin the DH agreement 1 byte IP address size that many byte representation of Bob's IP address N bytes, currently uninterpreted
Key used:	introKey

 +----+----+----+----+----+----+----+----+
 |         X, as calculated from DH      |
 |                                       |
                 .   .   .               
 |                                       |
 +----+----+----+----+----+----+----+----+
 |size| that many byte IP address (4-16) |
 +----+----+----+----+----+----+----+----+
 |           arbitrary amount            |
 |        of uninterpreted data          |
                 .   .   .               
 |                                       |
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 304 bytes

Notes

IP address is always 4 bytes in the current implementation.
The uninterpreted data could possibly be used in the future for challenges.

IP address is always 4 bytes in the current implementation.

SessionCreated (type 1)

This is the response to a Session Request.

Peer:	Bob to Alice
Data:	256 byte Y, to complete the DH agreement 1 byte IP address size that many byte representation of Alice's IP address 2 byte Alice's port number 4 byte relay (introduction) tag which Alice can publish (else 0x00000000) 4 byte timestamp (seconds from the epoch) for use in the DSA signature 40 byte DSA signature of the critical exchanged data (X + Y + Alice's IP + Alice's port + Bob's IP + Bob's port + Alice's new relay tag + Bob's signed on time), encrypted with another layer of encryption using the negotiated sessionKey. The IV is reused here. 8 bytes padding, encrypted with an additional layer of encryption using the negotiated session key as part of the DSA block N bytes, currently uninterpreted
Key used:	introKey, with an additional layer of encryption over the 40 byte signature and the following 8 bytes padding.

 +----+----+----+----+----+----+----+----+
 |         Y, as calculated from DH      |
 |                                       |
                 .   .   .               
 |                                       |
 +----+----+----+----+----+----+----+----+
 |size| that many byte IP address (4-16) |
 +----+----+----+----+----+----+----+----+
 | Port (A)| public relay tag  |  signed
 +----+----+----+----+----+----+----+----+
   on time |                             |
 +----+----+                             |
 |              DSA signature            |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +         +----+----+----+----+----+----+
 |         |     (8 bytes of padding) 
 +----+----+----+----+----+----+----+----+
           |                             |
 +----+----+                             |
 |           arbitrary amount            |
 |        of uninterpreted data          |
                 .   .   .               
 |                                       |
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 368 bytes

Notes

IP address is always 4 bytes in the current implementation.
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.
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.

SessionConfirmed (type 2)

This is the response to a Session Created message and the last step in establishing a session. There may be multiple Session Confirmed messages required if the Router Identity must be fragmented.

Peer:	Alice to Bob
Data:	1 byte identity fragment info: Bit order: 76543210 (bit 7 is MSB) bits 7-4: current identity fragment # 0-14 bits 3-0: total identity fragments (F) 1-15 2 byte size of the current identity fragment that many byte fragment of Alice's Router Identity After the last identity fragment only: 4 byte signed-on time N bytes padding, currently uninterpreted After the last identity fragment only: The last 40 bytes contain the DSA signature of the critical exchanged data (X + Y + Alice's IP + Alice's port + Bob's IP + Bob's port + Alice's new relay key + Alice's signed on time)
Key used:	sessionKey

 Fragment 0 through F-2
 +----+----+----+----+----+----+----+----+
 |info| cursize |                        |
 +----+----+----+                        |
 |      fragment of Alice's full         |
 |            Router Identity            |
                 .   .   .               
 |                                       |
 +----+----+----+----+----+----+----+----+
 |  arbitrary amount of uninterpreted    |
 |              data                     |
 +----+----+----+----+----+----+----+----+
 
 Fragment F-1:
 +----+----+----+----+----+----+----+----+
 |info| cursize |                        |
 +----+----+----+                        |
 |     last fragment of Alice's full     |
 |            Router Identity            |
                 .   .   .               
 |                                       |
 +----+----+----+----+----+----+----+----+
 |  signed on time   |                   |
 +----+----+----+----+                   |
 |  arbitrary amount of uninterpreted    |
 |      data, to 40 bytes prior to       |
 |       end of the current packet       |
 +----+----+----+----+----+----+----+----+
 | DSA signature                         |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 480 bytes

Notes

In the current implementation, the maximum fragment size is 512 bytes.
The typical Router Identity is 387 bytes, so no fragmentation is usually necessary.
There is no mechanism for requesting or redelivering missing fragments.
The total fragments field F must be set identically in all fragments.
Signed-on time appears to be unused or unverified in the current implementation.

SessionDestroyed (type 8)

The Session Destroyed message was implemented (reception only) in release 0.8.1, and is never sent. Transmission implemented as of release 0.8.9.

Peer:	Alice to Bob or Bob to Alice
Data:	none
Key used:	sessionKey or introKey

 +----+----+----+----+----+----+----+----+
 |              no data                  |
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 48 bytes

RelayRequest (type 3)

This is the first message sent from Alice to Bob to request an introduction to Charlie.

Peer:	Alice to Bob
Data:	4 byte relay (introduction) tag, nonzero 1 byte IP address size that many byte representation of Alice's IP address 2 byte port number (of Alice) 1 byte challenge size that many bytes to be relayed to Charlie in the intro Alice's 32-byte introduction key (so Bob can reply with Charlie's info) 4 byte nonce of Alice's relay request N bytes, currently uninterpreted
Key used:	introKey (or sessionKey, if Alice/Bob is established)

 +----+----+----+----+----+----+----+----+
 |      relay tag    |size| Alice IP addr 
 +----+----+----+----+----+--- +----+----|
      | Port (A)|size| challenge bytes   |
 +----+----+----+----+                   +
 |      to be delivered to Charlie       |
 +----+----+----+----+----+----+----+----+
 | Alice's intro key                     |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |       nonce       |                   |
 +----+----+----+----+                   |
 | arbitrary amount of uninterpreted data|
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 96 bytes

Notes

IP address is always 4 bytes in the current implementation.
Challenge is unimplemented, challenge size is always zero

RelayResponse (type 4)

This is the response to a Relay Request and is sent from Bob to Alice.

Peer:	Bob to Alice
Data:	1 byte IP address size that many byte representation of Charlie's IP address 2 byte Charlie's port number 1 byte IP address size that many byte representation of Alice's IP address 2 byte Alice's port number 4 byte nonce sent by Alice N bytes, currently uninterpreted
Key used:	introKey (or sessionKey, if Alice/Bob is established)

 +----+----+----+----+----+----+----+----+
 |size|    Charlie IP     | Port (C)|size|
 +----+----+----+----+----+----+----+----+
 |    Alice IP       | Port (A)|  nonce   
 +----+----+----+----+----+----+----+----+
           |   arbitrary amount of       |
 +----+----+                             |
 |          uninterpreted data           |
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 64 bytes

Notes

IP address is always 4 bytes in the current implementation.

RelayIntro (type 5)

This is the introduction for Alice, which is sent from Bob to Charlie.

Peer:	Bob to Charlie
Data:	1 byte IP address size that many byte representation of Alice's IP address 2 byte port number (of Alice) 1 byte challenge size that many bytes relayed from Alice N bytes, currently uninterpreted
Key used:	sessionKey

 +----+----+----+----+----+----+----+----+
 |size|     Alice IP      | Port (A)|size|
 +----+----+----+----+----+----+----+----+
 |      that many bytes of challenge     |
 +                                       |
 |        data relayed from Alice        |
 +----+----+----+----+----+----+----+----+
 | arbitrary amount of uninterpreted data|
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 48 bytes

Notes

IP address is always 4 bytes in the current implementation.
Challenge is unimplemented, challenge size is always zero

Data (type 6)

This message is used for data transport and acknowledgment.

Peer:

Any

Data:

1 byte flags:

   Bit order: 76543210 (bit 7 is MSB)
   bit 7: explicit ACKs included
   bit 6: ACK bitfields included
   bit 5: reserved
   bit 4: explicit congestion notification (ECN)
   bit 3: request previous ACKs
   bit 2: want reply
   bit 1: extended data included (unused, never set)
   bit 0: reserved

if explicit ACKs are included:
- a 1 byte number of ACKs
- that many 4 byte MessageIds being fully ACKed

if ACK bitfields are included:

a 1 byte number of ACK bitfields

that many 4 byte MessageIds + a 1 or more byte ACK bitfield. The bitfield uses the 7 low bits of each byte, with the high bit specifying whether an additional bitfield byte follows it (1 = true, 0 = the current bitfield byte is the last). These sequence of 7 bit arrays represent whether a fragment has been received - if a bit is 1, the fragment has been received. To clarify, assuming fragments 0, 2, 5, and 9 have been received, the bitfield bytes would be as follows:

byte 0
   Bit order: 76543210 (bit 7 is MSB)
   bit 7: 1 (further bitfield bytes follow)
   bit 6: 1 (fragment 0 received)
   bit 5: 0 (fragment 1 not received)
   bit 4: 1 (fragment 2 received)
   bit 3: 0 (fragment 3 not received)
   bit 2: 0 (fragment 4 not received)
   bit 1: 1 (fragment 5 received)
   bit 0: 0 (fragment 6 not received)
byte 1
   Bit order: 76543210 (bit 7 is MSB)
   bit 7: 0 (no further bitfield bytes)
   bit 6: 0 (fragment 7 not received)
   bit 5: 0 (fragment 8 not received)
   bit 4: 1 (fragment 9 received)
   bit 3: 0 (fragment 10 not received)
   bit 2: 0 (fragment 11 not received)
   bit 1: 0 (fragment 12 not received)
   bit 0: 0 (fragment 13 not received)

If extended data included:
- 1 byte data size
- that many bytes of extended data (currently uninterpreted)
1 byte number of fragments (can be zero)

If nonzero, that many message fragments. Each fragment contains:

4 byte messageId

3 byte fragment info:

   Bit order: 76543210 (bit 7 is MSB)
   bits 23-17: fragment # 0 - 127
   bit 16: isLast (1 = true)
   bits 15-14: unused
   bits 13-0: fragment size 0 - 16383

that many bytes

N bytes padding, uninterpreted

Key used:

sessionKey

 +----+----+----+----+----+----+----+----+
 |flag| (additional headers, determined  |
 +----+                                  |
 | by the flags, such as ACKs or         |
 | bitfields                             |
 +----+----+----+----+----+----+----+----+
 |#frg|     messageId     |   frag info  |
 +----+----+----+----+----+----+----+----+
 | that many bytes of fragment data      |
                  .  .  .                                       
 |                                       |
 +----+----+----+----+----+----+----+----+
 |     messageId     |   frag info  |    |
 +----+----+----+----+----+----+----+    |
 | that many bytes of fragment data      |
                  .  .  .                                       
 |                                       |
 +----+----+----+----+----+----+----+----+
 |     messageId     |   frag info  |    |
 +----+----+----+----+----+----+----+    |
 | that many bytes of fragment data      |
                  .  .  .                                       
 |                                       |
 +----+----+----+----+----+----+----+----+
 | arbitrary amount of uninterpreted data|
 +----+----+----+----+----+----+----+----+

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.
The want reply bit is always set in the current implementation.
Extended data is unimplemented and never present.
The current implementation does not pack multiple fragments into a single packet; the number of fragments is always 0 or 1.
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.

PeerTest (type 7)

See the UDP overview page for details.

Peer:	Any
Data:	4 byte nonce 1 byte IP address size that many byte representation of Alice's IP address 2 byte Alice's port number Alice's 32-byte introduction key N bytes, currently uninterpreted
Key used:	introKey (or sessionKey if the connection has already been established)

 +----+----+----+----+----+----+----+----+
 |    test nonce     |size| Alice IP addr 
 +----+----+----+----+----+----+----+----+
      | Port (A)|                        |
 +----+----+----+                        +
 | Alice or Charlie's                    |
 + introduction key (Alice's is sent to  +
 | Bob and Charlie, while Charlie's is   |
 + sent to Alice)                        +
 |                                       |
 |              +----+----+----+----+----+
 |              | arbitrary amount of    |
 |----+----+----+                        |
 | uninterpreted data                    |
 +----+----+----+----+----+----+----+----+

Typical size including header, in current implementation: 80 bytes

Notes

IP address is always 4 bytes in the current implementation.

HolePunch

A HolePunch is simply a UDP packet with no data. It is unauthenticated and unencrypted. It does not contain a SSU header, so it does not have a message type number. It is sent from Charlie to Alice as a part of the Introduction sequence.

Sample datagrams

Minimal data message (no fragments, no ACKs, no NACKs, etc)
(Size: 39 bytes)

 +----+----+----+----+----+----+----+----+
 |                  MAC                  |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |                   IV                  |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |flag|        time       |flag|#frg|    |
 +----+----+----+----+----+----+----+    |
 |  padding to fit a full AES256 block   |
 +----+----+----+----+----+----+----+----+

Minimal data message with payload
(Size: 46+fragmentSize bytes)

 +----+----+----+----+----+----+----+----+
 |                  MAC                  |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |                   IV                  |
 +                                       +
 |                                       |
 +----+----+----+----+----+----+----+----+
 |flag|        time       |flag|#frg| 
 +----+----+----+----+----+----+----+----+
   messageId    |   frag info  |         |
 +----+----+----+----+----+----+         |
 | that many bytes of fragment data      |
                  .  .  .                                       
 |                                       |
 +----+----+----+----+----+----+----+----+

SSU Protocol Specification

Specification

DH Key Exchange

Message Header

Rekeying

Extended Options

Padding

Keys

Notes

IPv6 Notes

Timestamps

Messages

SessionRequest (type 0)

Notes

SessionCreated (type 1)

Notes

SessionConfirmed (type 2)

Notes

SessionDestroyed (type 8)

RelayRequest (type 3)

Notes

RelayResponse (type 4)

Notes

RelayIntro (type 5)

Notes

Data (type 6)

Notes

PeerTest (type 7)

Notes

HolePunch

Sample datagrams