2010-07-17 16:28:13 +00:00
{% extends "_layout.html" %}
{% block title %}I2NP Specification{% endblock %}
{% block content %}
< h1 > I2P Network Protocol (I2NP) Specification< / h1 >
< p >
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.
< / p >
2010-07-17 22:39:20 +00:00
< h2 id = "structures" > Common structures< / h2 >
2010-07-26 18:46:54 +00:00
2010-07-17 22:39:20 +00:00
< h3 id = "struct_header" > I2NP message header< / h3 >
2010-07-26 18:46:54 +00:00
< h4 > Description< / h4 >
< p >
Common header to all I2NP messages, which contains important information like an checksum, expiration date, etc.
< / p >
< h4 > Contents< / h4 >
< p >
1 byte < a href = "common_structures_spec#type_Integer" > Integer< / a > specifying the type of this message, followed by an 4 byte < a href = "common_structures_spec#type_Integer" > Integer< / a > specifying the message-id. After that there is an expiration < a href = "common_structures_spec#type_Date" > Date< / a > , followed by an 2 byte < a href = "common_structures_spec#type_Integer" > Integer< / a > specifying the length of the message payload, followed by an < a href = "common_structures_spec#type_Hash" > Hash< / a > , which is truncated to the first byte. After that the actual message data follows.
< / p >
2010-07-17 22:39:20 +00:00
< pre >
{% filter escape %}
2010-07-26 18:46:54 +00:00
+----+----+----+----+----+
|type| msg-id |
2010-07-17 22:39:20 +00:00
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| expiration |
2010-07-17 22:39:20 +00:00
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| size |chks|
+----+----+----+
2010-07-17 22:39:20 +00:00
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
2010-07-26 18:46:54 +00:00
type :: Integer
length -> 1 byte
purpose -> identifies the message type(see table below)
msg-id :: Integer
length -> 4 bytes
2010-07-17 22:39:20 +00:00
2010-07-26 18:46:54 +00:00
purpose -> uniquely identifies this message(for some time at least)
2010-07-17 22:39:20 +00:00
2010-07-26 18:46:54 +00:00
expiration :: Date
2010-07-17 22:39:20 +00:00
8 bytes
date this message will expire
2010-07-26 18:46:54 +00:00
size :: Integer
length -> 2 bytes
purpose -> length of the payload
chks :: Hash
length -> 1 byte
purpose -> checksum of the payload
SHA256 hash truncated to the first byte
data :: Data
length -> $size bytes
purpose -> actual message contents
2010-07-17 22:39:20 +00:00
{% endfilter %}
< / pre >
2010-07-17 22:54:03 +00:00
< h3 id = "struct_BuildRequestRecord" > BuildRequestRecord< / h3 >
2010-07-26 18:46:54 +00:00
< h4 > Description< / h4 >
< p >
2010-08-02 12:20:33 +00:00
One Record in a set of multiple records to request the creation of one hop in the tunnel. For more details see
< a href = "tunnel-alt.html" > the tunnel overview< / a > and
< a href = "tunnel-alt-creation.html" > the tunnel creation specification< / a > .
2010-07-26 18:46:54 +00:00
< / p >
< h4 > Contents< / h4 >
< p >
< a href = "common_structures_spec#type_TunnelId" > TunnelId< / a > to receive messages on, followed by the < a href = "common_structures_spec#type_Hash" > Hash< / a > of our < a href = "common_structures_spec#struct_RouterIdentity" > RouterIdentity< / a > . After that the < a href = "common_structures_spec#type_TunnelId" > TunnelId< / a > and the < a href = "common_structures_spec#type_Hash" > Hash< / a > of the next router's < a href = "common_structures_spec#struct_RouterIdentity" > RouterIdentity< / a > follow.
< / p >
< h4 > Definition< / h4 >
2010-07-17 22:54:03 +00:00
< pre >
{% filter escape %}
Cleartext:
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| receive_tunnel | our_ident |
+----+----+----+----+ +
2010-07-17 22:54:03 +00:00
| |
+ +
| |
+ +
| |
+ +----+----+----+----+
2010-07-26 18:46:54 +00:00
| | next_tunnel |
2010-07-17 22:54:03 +00:00
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| next_ident |
2010-07-17 22:54:03 +00:00
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| layer_key |
2010-07-17 22:54:03 +00:00
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| iv_key |
2010-07-17 22:54:03 +00:00
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| reply_key |
2010-07-17 22:54:03 +00:00
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
2010-07-26 18:46:54 +00:00
| reply_iv |
2010-07-17 22:54:03 +00:00
+ +
| |
2010-07-26 18:46:54 +00:00
+----+----+----+----+----+----+----+----+----+
|flag| request_time | send_message_id |
+----+----+----+----+----+----+----+----+----+
| padding...
2010-07-17 22:54:03 +00:00
+----+----+----+--//
2010-07-25 18:29:38 +00:00
encrypted:
+----+----+----+----+----+----+----+----+
| toPeer |
+ +
| |
+----+----+----+----+----+----+----+----+
| encrypted data ... |
+----+----+----+----+----+----+----+----+
2010-07-17 22:54:03 +00:00
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
2010-07-25 18:29:38 +00:00
unencrypted:
2010-07-26 18:46:54 +00:00
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
2010-08-04 14:19:34 +00:00
reply_iv :: data
2010-07-26 18:46:54 +00:00
length -> 16 bytes
flag :: Integer
length -> 1 byte
request_time :: Integer
length -> 4 bytes
2010-08-04 14:19:34 +00:00
Hours since the epoch, i.e. current time / 3600
2010-07-26 18:46:54 +00:00
send_message_id :: Integer
length -> 4 bytes
padding :: Data
length -> 29 bytes
source -> random
2010-07-25 18:29:38 +00:00
2010-08-04 14:19:34 +00:00
total length: 223
2010-07-25 18:29:38 +00:00
encrypted:
2010-07-26 18:46:54 +00:00
toPeer :: Hash
length -> 16 bytes
encrypted_data :: ElGamal-2048 encrypted data
2010-08-04 14:19:34 +00:00
length -> 512
total length: 528
2010-07-25 18:29:38 +00:00
2010-07-17 22:54:03 +00:00
{% endfilter %}
< / pre >
2010-08-04 14:19:34 +00:00
< h4 > Notes< / h4 >
< p >
See also the < a href = "tunnel-alt-creation.html" > tunnel creation specification< / a > .
< / p >
2010-07-25 18:29:38 +00:00
< h3 id = "struct_BuildResponseRecord" > BuildResponseRecord< / h3 >
< pre >
{% filter escape %}
unencrypted:
+----+----+----+----+----+----+----+----+
| random data... |
| |
+ +----+
| |ret |
+----+----+----+----+----+----+----+----+
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
unencrypted:
bytes 0-526: random data
byte 527 : reply
encrypted:
bytes 0-527: AES-encrypted record(note: same size as BuildRequestRecord!)
2010-08-04 14:19:34 +00:00
total length: 528
2010-07-25 18:29:38 +00:00
{% endfilter %}
< / pre >
2010-08-04 14:19:34 +00:00
< h4 > Notes< / h4 >
< p >
See also the < a href = "tunnel-alt-creation.html" > tunnel creation specification< / a > .
< / p >
2010-07-25 18:29:38 +00:00
2010-07-17 16:28:13 +00:00
< h2 id = "messages" > Messages< / h2 >
2010-07-17 17:15:06 +00:00
< table border = 1 >
< tr >
< td > Message< / td >
< td > Type< / td >
< / tr >
< tr >
< td > < a href = "#msg_DatabaseStore" > DatabaseStore< / a > < / td >
< td align = "right" > 1< / td >
< / tr >
< tr >
< td > < a href = "#msg_DatabaseLookup" > DatabaseLookup< / a > < / td >
< td align = "right" > 2< / td >
< / tr >
2010-07-17 21:40:59 +00:00
< tr >
< td > < a href = "#msg_DatabaseSearchReply" > DatabaseSearchReply< / a > < / td >
< td align = "right" > 3< / td >
< / tr >
2010-07-17 21:49:22 +00:00
< tr >
< td > < a href = "#msg_DeliveryStatus" > DeliveryStatus< / a > < / td >
< td align = "right" > 10< / td >
< / tr >
2010-07-17 21:57:47 +00:00
< tr >
< td > < a href = "#msg_Garlic" > Garlic< / a > < / td >
< td align = "right" > 11< / td >
< / tr >
2010-07-17 22:05:48 +00:00
< tr >
< td > < a href = "#msg_TunnelData" > TunnelData< / a > < / td >
< td align = "right" > 18< / td >
< / tr >
2010-07-17 22:10:45 +00:00
< tr >
< td > < a href = "#msg_TunnelGateway" > TunnelGateway< / a > < / td >
< td align = "right" > 19< / td >
< / tr >
2010-07-17 22:20:41 +00:00
< tr >
< td > < a href = "#msg_Data" > Data< / a > < / td >
< td align = "right" > 20< / td >
< / tr >
2010-07-17 22:39:20 +00:00
< tr >
< td > < a href = "#msg_TunnelBuild" > TunnelBuild< / a > < / td >
< td align = "right" > 21< / td >
< / tr >
2010-07-25 19:31:28 +00:00
< tr >
< td > < a href = "#msg_TunnelBuildReply" > TunnelBuildReply< / a > < / td >
< td align = "right" > 22< / td >
< / tr >
< tr >
< td > < a href = "#msg_VariableTunnelBuild" > VariableTunnelBuild< / a > < / td >
< td align = "right" > 23< / td >
< / tr >
< tr >
< td > < a href = "#msg_VariableTunnelBuildReply" > VariableTunnelBuildReply< / a > < / td >
< td align = "right" > 24< / td >
< / tr >
2010-07-17 17:15:06 +00:00
< / table >
2010-07-17 16:28:13 +00:00
< h3 id = "msg_DatabaseStore" > DatabaseStore< / h3 >
2010-08-02 12:20:33 +00:00
< h4 > Description< / h4 >
< p >
An unsolicited database store, or the response to a successful Database Lookup Message
< / p >
< h4 > Contents< / h4 >
< p >
A LeaseSet or RouterInfo
< / p >
2010-07-17 16:30:26 +00:00
< pre >
2010-07-17 16:28:13 +00:00
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| reply token | data ...
+----+-------------------+---------\\
2010-07-17 16:30:26 +00:00
< / pre >
2010-07-17 16:28:13 +00:00
< h4 > Definition< / h4 >
2010-07-17 16:30:26 +00:00
< pre >
2010-07-17 16:28:13 +00:00
key:
32 bytes
SHA256 hash
type:
1 byte
type identifier
mapping:
0 RouterInfo
1 LeaseSet
reply token:
4 bytes
2010-08-02 12:20:33 +00:00
If greater than zero, a < a href = "#msg_DeliveryStatus" > Delivery Status Message< / a >
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.
2010-07-17 16:28:13 +00:00
reply tunnelId:
4 bytes
2010-08-02 12:20:33 +00:00
only included if reply token > 0
This is the < a href = "common_structures_spec#type_TunnelID" > tunnel ID< / a > of the inbound gateway of the tunnel the response should be sent to
2010-07-17 16:28:13 +00:00
reply gateway:
32 bytes
Hash of the routerInfo entry to reach the gateway
2010-08-02 12:20:33 +00:00
only included if reply token > 0
This is the router hash of the inbound gateway of the tunnel the response should be sent to
2010-07-17 16:28:13 +00:00
data:
rest of the message(could be anything)
2010-07-17 16:30:26 +00:00
< / pre >
< h3 id = "msg_DatabaseLookup" > DatabaseLookup< / h3 >
< pre >
2010-07-17 16:49:20 +00:00
{% filter escape %}
if flag==TRUE
+----+----+----+----+----+----+----+----+
| SHA256 hash as the key to look up |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| SHA256 hash of the routerInfo |
+ who is asking +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
|flag| reply tunnelId |size | |
+----+----+----+----+----+----+----+ +
| SHA256 of $key1 to exclude |
+ +
| |
+ +
| |
+ +----+
| | |
+----+----+----+----+----+----+----+ +
| SHA256 of $key2 to exclude |
....
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
key:
32 bytes
SHA256 hash of the object to lookup
from:
32 bytes
SHA256 hash of the routerInfo entry this request came from(and to which the reply should be sent)
flag:
1 byte
mapping:
0 FALSE => send reply directly
1 TRUE => send reply to some tunnel
reply tunnelId:
2 bytes
only included if flag==TRUE
tunnelId of the tunnel to send the reply to
size:
2 bytes
2010-08-02 12:20:33 +00:00
number of peers to exclude from the Database Search Reply Message
2010-07-17 16:49:20 +00:00
excludedPeers:
2010-08-02 12:20:33 +00:00
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.
2010-07-17 16:49:20 +00:00
{% endfilter %}
2010-07-17 16:30:26 +00:00
< / pre >
2010-07-17 16:28:13 +00:00
2010-07-17 21:40:59 +00:00
< h3 id = "msg_DatabaseSearchReply" > DatabaseSearchReply< / h3 >
2010-08-02 12:20:33 +00:00
< h4 > Description< / h4 >
< p >
The response to a failed Database Lookup Message
< / p >
< h4 > Contents< / h4 >
< p >
A list of router hashes closest to the requested key
< / p >
2010-07-17 21:40:59 +00:00
< pre >
{% filter escape %}
+----+----+----+----+----+----+----+----+
| SHA256 hash as query key |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
|num | peer hash $1 |
+----+ +
| |
+ +
| |
+ +
| |
+ +----+----+----+----+----+----+----+
| | |
+----+.... $num peer hashes
+ +----+----+----+----+----+----+----+
| | from |
+----+ +
| |
+ +
| |
+ +
| |
+ +----+----+----+----+----+----+----+
| |
+----+
{% endfilter %}
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
key:
32 bytes
SHA256 of the object being searched
num:
1 byte
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
2010-07-17 22:20:41 +00:00
{% endfilter %}
2010-07-17 21:40:59 +00:00
< / pre >
2010-07-17 21:49:22 +00:00
2010-08-02 12:20:33 +00:00
< h4 > Notes< / h4 >
< p >
The 'from' hash is unauthenticated and cannot be trusted.
< / p >
2010-07-17 21:49:22 +00:00
< h3 id = "msg_DeliveryStatus" > DeliveryStatus< / h3 >
< pre >
{% filter escape %}
+----+----+----+----+----+----+----+----+----+----+----+----+
|msg-id | arrival-time |
+----+----+----+----+----+----+----+----+----+----+----+----+
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
msg-id:
4 bytes
unique ID of the message we deliver the DeliveryStatus for(see common I2NP header for details)
arrival-time:
8 bytes
time the message was successfully delivered
{% endfilter %}
< / pre >
2010-07-17 21:57:47 +00:00
< h3 id = "msg_Garlic" > Garlic< / h3 >
< pre >
{% filter escape %}
2010-07-25 21:01:44 +00:00
encrypted:
2010-07-17 21:57:47 +00:00
+----+----+----+----+----+----+----+----+
2010-07-25 21:01:44 +00:00
|length | tag |
+----+----+----+----+ +
| |
+ +
| |
+ +
| |
+ +----+----+----+----+
|
2010-07-17 21:57:47 +00:00
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
length:
4 bytes
number of bytes that follow
data:
$length bytes
2010-07-25 21:01:44 +00:00
elgamal en
2010-07-17 21:57:47 +00:00
{% endfilter %}
< / pre >
2010-07-17 22:05:48 +00:00
< h3 id = "msg_TunnelData" > TunnelData< / h3 >
< pre >
{% filter escape %}
+----+----+----+----+----+----+----+----+
| tunnelId | data |
+----+----+----+----+ |
| |
| |
+----+----+----+----+----+----+----+----+
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
tunnelId:
4 bytes
identifies the tunnel this message is directed at
data:
1024 bytes
payload data.. fixed to 1024 bytes
{% endfilter %}
< / pre >
2010-07-17 22:10:45 +00:00
< h3 id = "msg_TunnelGateway" > TunnelGateway< / h3 >
< pre >
{% filter escape %}
+----+----+----+----+----+----+--\\----+
| tunnelId | length | data...|
+----+----+----+----+----+----+--\\----+
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
2010-07-17 22:20:41 +00:00
{% filter escape %}
2010-07-17 22:10:45 +00:00
tunnelId:
4 bytes
identifies the tunnel this message is directed at
length:
2 bytes
length of the payload
data:
$length bytes
actual payload of this message
{% endfilter %}
< / pre >
2010-07-17 22:20:41 +00:00
{% endblock %}
< h3 id = "msg_Data" > Data< / h3 >
< pre >
{% filter escape %}
+----+----+----+----+----+---//--+
| length | data... |
+----+----+----+----+----+---//--+
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
length:
4 bytes
length of the payload
data:
$length bytes
actual payload of this message
{% endfilter %}
< / pre >
2010-07-17 22:39:20 +00:00
< h3 id = "msg_TunnelBuild" > TunnelBuild< / h3 >
< pre >
{% filter escape %}
2010-07-25 18:34:24 +00:00
+----+----+----+----+----+----+----+----+
| Record 0 ... |
| |
+----+----+----+----+----+----+----+----+
| Record 1 ... |
.....
+----+----+----+----+----+----+----+----+
| Record 7 ... |
| |
+----+----+----+----+----+----+----+----+
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
{% filter escape %}
Just 8 records attached together
Record size: 528 bytes
Total size: 8*528 = 4224 bytes
2010-07-17 22:39:20 +00:00
{% endfilter %}
2010-07-25 18:34:24 +00:00
< / pre >
2010-07-17 22:39:20 +00:00
2010-08-04 14:19:34 +00:00
< h4 > Notes< / h4 >
< p >
See also the < a href = "tunnel-alt-creation.html" > tunnel creation specification< / a > .
< / p >
2010-07-25 19:31:28 +00:00
< h3 id = "msg_TunnelBuildReply" > TunnelBuildReply< / h3 >
< pre >
{% filter escape %}
same format as TunnelBuild message
{% endfilter %}
< / pre >
2010-08-04 14:19:34 +00:00
< h4 > Notes< / h4 >
< p >
See also the < a href = "tunnel-alt-creation.html" > tunnel creation specification< / a > .
< / p >
2010-07-25 19:31:28 +00:00
< h3 id = "msg_VariableTunnelBuild" > VariableTunnelBuild< / h3 >
< pre >
{% filter escape %}
+----+----+----+----+----+----+----+----+
|num | ....
{% endfilter %}
< / pre >
< h4 > Definition< / h4 >
< pre >
2010-07-25 21:01:44 +00:00
{% filter escape %}
2010-07-25 19:31:28 +00:00
same format as TunnelBuildMessage, except for the addition of an "num" field in front and $num number of records instead of 8
2010-08-02 12:20:33 +00:00
num:
1 byte
Valid values: 1-8
Record size: 528 bytes
Total size: 1 + $num*528
2010-07-25 19:31:28 +00:00
{% endfilter %}
< / pre >
2010-08-04 14:19:34 +00:00
< h4 > Notes< / h4 >
< p >
See also the < a href = "tunnel-alt-creation.html" > tunnel creation specification< / a > .
< / p >
2010-07-25 19:31:28 +00:00
< h3 id = "msg_VariableTunnelBuildReply" > VariableTunnelBuildReply< / h3 >
< pre >
{% filter escape %}
same format as VariableTunnelBuild message
{% endfilter %}
< / pre >
2010-08-04 14:19:34 +00:00
< h4 > Notes< / h4 >
< p >
See also the < a href = "tunnel-alt-creation.html" > tunnel creation specification< / a > .
< / p >
