I2P Network Protocol (I2NP) Specification
The I2P Network Protocol (I2NP), which is sandwiched between I2CP and the various I2P transport protocols, manages the routing and mixing of messages between routers, as well as the selection of what transports to use when communicating with a peer for which there are multiple common transports supported.
Common structures
The following structures are elements of multiple I2NP messages. They are not complete messages.I2NP message header
Description
Common header to all I2NP messages, which contains important information like a checksum, expiration date, etc.
Contents
1 byte Integer specifying the type of this message, followed by a 4 byte Integer specifying the message-id. After that there is an expiration Date, followed by a 2 byte Integer specifying the length of the message payload, followed by a Hash, which is truncated to the first byte. After that the actual message data follows.
Standard (16 bytes):
+----+----+----+----+----+----+----+----+
|type| msg-id | expiration
+----+----+----+----+----+----+----+----+
| size |chks|
+----+----+----+----+----+----+----+----+
Short (SSU, 5 bytes):
+----+----+----+----+----+
|type| short expiration |
+----+----+----+----+----+
Definition
type :: Integer
length -> 1 byte
purpose -> identifies the message type (see table below)
msg-id :: Integer
length -> 4 bytes
purpose -> uniquely identifies this message (for some time at least)
expiration :: Date
8 bytes
date this message will expire
short expiration :: Integer
4 bytes
date this message will expire (seconds since the epoch)
size :: Integer
length -> 2 bytes
purpose -> length of the payload
chks :: Integer
length -> 1 byte
purpose -> checksum of the payload
SHA256 hash truncated to the first byte
data :: Data
length -> $size bytes
purpose -> actual message contents
Notes
- When transmitted over SSU, the 16-byte standard header is not used. Only a 1-byte type and a 4-byte expiration in seconds is included. The message id and size are incorporated into various parts of the SSU data packet format. The checksum is not required since errors are caught in decryption.
- THe standard header is also required for I2NP messages contained in other messages and structures (Data, TunnelData, TunnelGateway, and GarlicClove). As of release 0.8.12, to reduce overhead, checksum verification is disabled at some places in the protocol stack. However, for compatibility with older versions, checksum generation is still required. It is a topic for future research to determine points in the protocol stack where the far-end router's version is known and checksum generation can be disabled.
BuildRequestRecord
Description
One Record in a set of multiple records to request the creation of one hop in the tunnel. For more details see the tunnel overview and the tunnel creation specification.
Contents
TunnelId to receive messages on, followed by the Hash of our RouterIdentity. After that the TunnelId and the Hash of the next router's RouterIdentity follow.
Definition
Cleartext:
+----+----+----+----+----+----+----+----+
| receive_tunnel | our_ident |
+----+----+----+----+ +
| |
+ +
| |
+ +
| |
+ +----+----+----+----+
| | next_tunnel |
+----+----+----+----+----+----+----+----+
| next_ident |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| layer_key |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| iv_key |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| reply_key |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| reply_iv |
+ +
| |
+----+----+----+----+----+----+----+----+
|flag| request_time | send_msg_id
+----+----+----+----+----+----+----+----+
| |
+----+ +
| 29 bytes padding |
+ +
| |
+ +----+----+
| |
+----+----+----+----+----+----+
ElGamal encrypted:
+----+----+----+----+----+----+----+----+
| toPeer |
+ +
| |
+----+----+----+----+----+----+----+----+
| encrypted data ... |
~ ~
| |
+----+----+----+----+----+----+----+----+
ElGamal and AES encrypted:
+----+----+----+----+----+----+----+----+
| encrypted data ... |
~ ~
| |
+----+----+----+----+----+----+----+----+
Definition
unencrypted:
receive_tunnel :: TunnelId
length -> 4 bytes
our_ident :: Hash
length -> 32 bytes
next_tunnel :: TunnelId
length -> 4 bytes
next_ident :: Hash
length -> 32 bytes
layer_key :: SessionKey
length -> 32 bytes
iv_key :: SessionKey
length -> 32 bytes
reply_key :: SessionKey
length -> 32 bytes
reply_iv :: data
length -> 16 bytes
flag :: Integer
length -> 1 byte
request_time :: Integer
length -> 4 bytes
Hours since the epoch, i.e. current time / 3600
send_message_id :: Integer
length -> 4 bytes
padding :: Data
length -> 29 bytes
source -> random
total length: 222
ElGamal encrypted:
toPeer :: First 16 bytes of the SHA-256 Hash of the peer's router identity
length -> 16 bytes
encrypted_data :: ElGamal-2048 encrypted data (see notes)
length -> 512
total length: 528
ElGamal and AES encrypted:
encrypted_data :: ElGamal and AES encrypted data
length -> 528
total length: 528
Notes
- In the 512-byte encrypted record, the ElGamal data contains bytes 1-256 and 258-513 of the 514-byte ElGamal encrypted block. The two padding bytes from the block (the zero bytes at locations 0 and 257) are removed.
- See the tunnel creation specification for details on field contents.
BuildResponseRecord
unencrypted: +----+----+----+----+----+----+----+----+ | random data... | ~ ~ | | + +----+ | |ret | +----+----+----+----+----+----+----+----+
Definition
unencrypted: bytes 0-526: random data byte 527 : reply encrypted: bytes 0-527: AES-encrypted record(note: same size as BuildRequestRecord) total length: 528
Notes
- The first 527 bytes could, in the future, be used to return congestion or peer connectivity information back to the requestor.
- See the tunnel creation specification for details on the reply field.
GarlicClove
unencrypted:
+----+----+----+----+----+----+----+----+
| Delivery Instructions |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| I2NP Message |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| Clove ID | Expiration
+----+----+----+----+----+----+----+----+
| Certificate |
+----+----+----+----+----+----+----+
Definition
unencrypted: Delivery Instructions :: as defined here Length varies but is typically 39, 43, or 47 bytes I2NP Message :: Any I2NP Message Clove ID :: 4 byte Integer Expiration :: Date (8 bytes) Certificate :: Always NULL in the current implementation (3 bytes total, all zeroes)
Notes
- Cloves are never fragmented. When used in a Garlic Clove, the first bit of the Delivery Instructions flag byte (the fragment bit) is redefined. If this bit is 0, the clove is not encrypted. If 1, the clove is encrypted, and a 32 byte Session Key immediately follows the flag byte. Clove encryption is not fully implemented.
- See also the garlic routing specification.
- See also Delivery Instructions definition
- In the future, the certificate could possibly be used for a HashCash to "pay" for the routing.
- The message is always a DataMessage?
Delivery Instructions
Defined in the Tunnel Message Specification.Messages
| Message | Type |
|---|---|
| DatabaseStore | 1 |
| DatabaseLookup | 2 |
| DatabaseSearchReply | 3 |
| DeliveryStatus | 10 |
| Garlic | 11 |
| TunnelData | 18 |
| TunnelGateway | 19 |
| Data | 20 |
| TunnelBuild | 21 |
| TunnelBuildReply | 22 |
| VariableTunnelBuild | 23 |
| VariableTunnelBuildReply | 24 |
DatabaseStore
Description
An unsolicited database store, or the response to a successful Database Lookup Message
Contents
An uncompressed LeaseSet or a compressed RouterInfo
with reply token: +----+----+----+----+----+----+----+----+ | SHA256 Hash as key | + + | | + + | | + + | | +----+----+----+----+----+----+----+----+ |type| reply token | reply tunnel- +----+----+----+----+----+----+----+----+ Id | SHA256 of the gateway RouterInfo | +----+ + | | + + | | + + | | + +----+----+----+----+----+----+----+ | | data ... +----+--------\\ with reply token == 0: +----+----+----+----+----+----+----+----+ | SHA256 Hash as key | + + | | + + | | + + | | +----+----+----+----+----+----+----+----+ |type| 0 | data ... +----+-------------------+---------\\
Definition
key:
32 bytes
SHA256 hash
type:
1 byte
type identifier
mapping:
0 RouterInfo
1 LeaseSet
reply token:
4 bytes
If greater than zero, a Delivery Status Message
is requested with the Message ID set to the value of the Reply Token.
A floodfill router is also expected to flood the data to the closest floodfill peers
if the token is greater than zero.
reply tunnelId:
4 byte Tunnel ID
only included if reply token > 0
This is the tunnel ID of the inbound gateway of the tunnel the response should be sent to
reply gateway:
32 bytes
Hash of the routerInfo entry to reach the gateway
only included if reply token > 0
This is the router hash of the inbound gateway of the tunnel the response should be sent to
data:
If type == 0, data is a 2-byte integer specifying the number of bytes that follow, followed by a gzip-compressed RouterInfo.
If type == 1, data is an uncompressed LeaseSet.
DatabaseLookup
+----+----+----+----+----+----+----+----+ | SHA256 hash as the key to look up | + + | | + + | | + + | | +----+----+----+----+----+----+----+----+ | SHA256 hash of the routerInfo | + who is asking, or the gateway to + | send the reply to | + + | | + + | | +----+----+----+----+----+----+----+----+ |flag| reply tunnelId |size | | +----+----+----+----+----+----+----+ + | SHA256 of $key1 to exclude | + + | | + + | | + +----+ | | | +----+----+----+----+----+----+----+ + | SHA256 of $key2 to exclude | ....
Definition
key:
32 bytes
SHA256 hash of the object to lookup
from:
32 bytes
If flag == 0, the SHA256 hash of the routerInfo entry this request came from (and to which the reply should be sent)
If flag == 1, the SHA256 hash of the reply tunnel gateway (to which the reply should be sent)
flag:
1 byte
valid values:
0 FALSE => send reply directly
1 TRUE => send reply to some tunnel
reply tunnelId:
4 byte Tunnel ID
only included if flag==TRUE
tunnelId of the tunnel to send the reply to
size:
2 byte Integer
valid range: 0-512
number of peers to exclude from the Database Search Reply Message
excludedPeers:
Rest of the message are $size SHA256 hashes of 32 bytes each (total $size*32 bytes)
If the lookup fails, these peers are requested to be excluded from the list in
the Database Search Reply Message.
If excludedPeers includes a hash of all zeroes, the request is exploratory, and
the Database Search Reply Message is requested to list non-floodfill routers only.
Notes
To do: Use a bit of the flag field to request an AES-encrypted response. Use parts of this message as the key and IV? Add a message ID also? Backward compatibility?
DatabaseSearchReply
Description
The response to a failed Database Lookup Message
Contents
A list of router hashes closest to the requested key
+----+----+----+----+----+----+----+----+ | SHA256 hash as query key | + + | | + + | | + + | | +----+----+----+----+----+----+----+----+ |num | peer hash $1 | +----+ + | | + + | | + + | | + +----+----+----+----+----+----+----+ | | | +----+.... $num peer hashes + +----+----+----+----+----+----+----+ | | from | +----+ + | | + + | | + + | | + +----+----+----+----+----+----+----+ | | +----+
Definition
key:
32 bytes
SHA256 of the object being searched
num:
1 byte Integer
number of peer hashes that follow
peer hash:
32 bytes
SHA256 of the RouterInfo that the other router thinks are close to the key
$num entries
from:
32 bytes
SHA256 of the RouterInfo of the router this reply was sent from
Notes
The 'from' hash is unauthenticated and cannot be trusted.
DeliveryStatus
Description
A simple message acknowledgment. Generally created by the message originator, and wrapped in a Garlic Message with the message itself, to be returned by the destination.
Contents
The ID of the delivered message, and the creation or arrival time.
+----+----+----+----+----+----+----+----+----+----+----+----+ |msg-id | time stamp | +----+----+----+----+----+----+----+----+----+----+----+----+
Definition
msg-id:
4 bytes
unique ID of the message we deliver the DeliveryStatus for (see common I2NP header for details)
time stamp: Date
8 bytes
time the message was successfully created or delivered
Notes
It appears that the time stamp is always set by the creator to the current time. However there are several uses of this in the code, and more may be added in the future.
Garlic
Description
Used to wrap multiple encrypted I2NP Messages
Contents
When decrypted, a series of Garlic Cloves.
encrypted:
+----+----+----+----+----+----+----+----+
| length | data |
+----+----+----+----+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
unencrypted data:
+----+----+----+----+----+----+----+----+
|num | clove 1 |
+----+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| clove 2 ... |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| Certificate | Message ID |
+----+----+----+----+----+----+----+----+
Expiration |
+----+----+----+----+----+----+----+
Definition
Encrypted:
length:
4 byte Integer
number of bytes that follow 0 - 64 KB
data:
$length bytes
ElGamal encrypted data
Unencrypted data:
num:
1 byte Integer number of Garlic Cloves to follow
clove: A Garlic Clove
Certificate :: Always NULL in the current implementation (3 bytes total, all zeroes)
Message ID :: 4 byte Integer
Expiration :: Date (8 bytes)
Notes
- When unencrypted, data contains one or more Garlic Cloves.
- Actual max length is less than 64 KB; see the I2NP Overview.
- See also the ElGamal/AES specification.
- See also the garlic routing specification.
- In the future, the certificate could possibly be used for a HashCash to "pay" for the routing.
TunnelData
+----+----+----+----+----+----+----+----+ | tunnnelID | data | +----+----+----+----+ | | | ~ ~ ~ ~ | | + +----+----+----+----+ | | +----+----+----+----+
Definition
tunnelId:
4 byte Tunnel ID
identifies the tunnel this message is directed at
data:
1024 bytes
payload data.. fixed to 1024 bytes
Notes
- See also the Tunnel Message Specification
TunnelGateway
+----+----+----+----+----+----+--\\----+ | tunnelId | length | data...| +----+----+----+----+----+----+--\\----+
Definition
tunnelId:
4 byte Tunnel ID
identifies the tunnel this message is directed at
length:
2 byte Integer
length of the payload
data:
$length bytes
actual payload of this message
Notes
- The payload is an I2NP message with a standard 16-byte header.
Data
Description
Used as a wrapper for encrypted Garlic Messages and Garlic Cloves. Also used previously for network load testing.
Contents
A length Integer, followed by opaque data.
+----+----+----+----+----+---//--+ | length | data... | +----+----+----+----+----+---//--+
Definition
length:
4 bytes
length of the payload
data:
$length bytes
actual payload of this message
TunnelBuild
+----+----+----+----+----+----+----+----+ | Record 0 ... | | | +----+----+----+----+----+----+----+----+ | Record 1 ... | ..... +----+----+----+----+----+----+----+----+ | Record 7 ... | | | +----+----+----+----+----+----+----+----+
Definition
Just 8 Build Request Records attached together Record size: 528 bytes Total size: 8*528 = 4224 bytes
Notes
See also the tunnel creation specification.
TunnelBuildReply
same format as TunnelBuild message, with Build Response Records
Notes
See also the tunnel creation specification.
VariableTunnelBuild
+----+----+----+----+----+----+----+----+ |num | BuildRequestRecords... +----+----+----+----+----+----+----+----+
Definition
Same format as TunnelBuildMessage, except for the addition of an "num" field in front and $num number of Build Request Records instead of 8
num:
1 byte Integer
Valid values: 1-8
Record size: 528 bytes
Total size: 1 + $num*528
Notes
- This message was introduced in router version 0.7.12, and may not be sent to tunnel participants earlier than that version.
- See also the tunnel creation specification.
VariableTunnelBuildReply
+----+----+----+----+----+----+----+----+ |num | BuildResponseRecords... +----+----+----+----+----+----+----+----+
Definition
Same format as VariableTunnelBuild message, with Build Response Records.Notes
- This message was introduced in router version 0.7.12, and may not be sent to tunnel participants earlier than that version.
- See also the tunnel creation specification.