i2p.www/www.i2p2/pages/i2np_spec.html

{% 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>

<h2 id="structures">Common structures</h2>

<h3 id="struct_header">I2NP message header</h3>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
|type| msg-id            | expiration
+----+----+----+----+----+----+----+----+
 date                    | size    |chks|
+----+----+----+----+----+----+----+----+
| data .....
+----+---//
{% endfilter %}
</pre>

<h4>Definition</h4>
<pre>
{% filter escape %}
type:
     1 byte
     identifies the message type(see table below)

msg-id:
       4 bytes
       uniquely identifies this message(for some time at least)

expiration:
           8 bytes
           date this message will expire

size:
     2 bytes
     length of the payload

chks:
     1 byte
     checksum of the payload
     TODO: algorithm

data:
     $size bytes
     actual message contents
{% endfilter %}
</pre>

<h2 id="messages">Messages</h2>
<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>
  <tr>
    <td><a href="#msg_DatabaseSearchReply">DatabaseSearchReply</a></td>
    <td align="right">3</td>
  </tr>
  <tr>
    <td><a href="#msg_DeliveryStatus">DeliveryStatus</a></td>
    <td align="right">10</td>
  </tr>
  <tr>
    <td><a href="#msg_Garlic">Garlic</a></td>
    <td align="right">11</td>
  </tr>
  <tr>
    <td><a href="#msg_TunnelData">TunnelData</a></td>
    <td align="right">18</td>
  </tr>
  <tr>
    <td><a href="#msg_TunnelGateway">TunnelGateway</a></td>
    <td align="right">19</td>
  </tr>
  <tr>
    <td><a href="#msg_Data">Data</a></td>
    <td align="right">20</td>
  </tr>
  <tr>
    <td><a href="#msg_TunnelBuild">TunnelBuild</a></td>
    <td align="right">21</td>
  </tr>
</table>

<h3 id="msg_DatabaseStore">DatabaseStore</h3>
<pre>
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 ...
+----+-------------------+---------\\
</pre>
<h4>Definition</h4>
<pre>
key:
    32 bytes
    SHA256 hash

type:
     1 byte
     type identifier
     mapping:
             0    RouterInfo
             1    LeaseSet

reply token:
            4 bytes
            TODO: find out what this does

reply tunnelId:
               4 bytes
               only included if reply token > 0
               TODO: what this tunnel information is needed for

reply gateway:
              32 bytes
              Hash of the routerInfo entry to reach the gateway
              only included if reply token > 0
              TODO: what this tunnel information is needed for

data:
     rest of the message(could be anything)
</pre>

<h3 id="msg_DatabaseLookup">DatabaseLookup</h3>
<pre>
{% 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
     number of peers to exclude from the lookup(TODO: whatever this means)

excludedPeers:
              rest of the message are $size SHA256 hashes of 32 bytes each(total $size*32 bytes)
{% endfilter %}
</pre>

<h3 id="msg_DatabaseSearchReply">DatabaseSearchReply</h3>
<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
{% endfilter %}
</pre>

<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>

<h3 id="msg_Garlic">Garlic</h3>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
|length             | .... data
+----+----+----+----+--\\
{% endfilter %}
</pre>

<h4>Definition</h4>
<pre>
{% filter escape %}
length:
       4 bytes
       number of bytes that follow

data:
     $length bytes
     $some data
{% endfilter %}
</pre>

<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>

<h3 id="msg_TunnelGateway">TunnelGateway</h3>
<pre>
{% filter escape %}
+----+----+----+----+----+----+--\\----+
| tunnelId          | length  | data...|
+----+----+----+----+----+----+--\\----+
{% endfilter %}
</pre>

<h4>Definition</h4>
<pre>
{% filter escape %}
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>


{% 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>

<h3 id="msg_TunnelBuild">TunnelBuild</h3>
<pre>
{% filter escape %}
...
{% endfilter %}