320 lines
11 KiB
HTML
320 lines
11 KiB
HTML
{% extends "global/layout.html" %}
|
|
{% block title %}Tunnel Message Specification{% endblock %}
|
|
{% block lastupdated %}February 2014{% endblock %}
|
|
{% block accuratefor %}0.9.11{% endblock %}
|
|
{% block content %}
|
|
<p>
|
|
This document specifies the format of tunnel messages.
|
|
For general information about tunnels see
|
|
<a href="{{ site_url('docs/tunnels/implementation') }}">the tunnel documentation</a>.
|
|
</p>
|
|
|
|
<h2>Message preprocessing</h2>
|
|
|
|
|
|
A <i>tunnel gateway</i> is the entrance, or first hop, of a tunnel.
|
|
For an outbound tunnel, the gateway is the creator of the tunnel.
|
|
For an inbound tunnel, the gateway is at the opposite end from the creator of the tunnel.
|
|
|
|
<p>
|
|
A gateway <i>preprocesses</i> <a href="{{ site_url('docs/protocol/i2np') }}">I2NP messages</a>
|
|
by fragmenting and combining them into tunnel messages.
|
|
|
|
<p>
|
|
While I2NP messages are variable size from 0 to almost 64 KB,
|
|
tunnel messages are fixed-size, approximately 1 KB.
|
|
Fixed message size
|
|
restricts several types of attacks that are possible from
|
|
observing message size.
|
|
|
|
<p>
|
|
After the tunnel messages are created, they are encrypted as described in
|
|
<a href="{{ site_url('docs/tunnels/implementation') }}">the tunnel documentation</a>.
|
|
|
|
<h2 id="msg_Data">Tunnel Message (Encrypted)</h2>
|
|
These are the contents of a tunnel data message after encryption.
|
|
{% highlight lang='dataspec' %}
|
|
+----+----+----+----+----+----+----+----+
|
|
| Tunnel ID | IV |
|
|
+----+----+----+----+ +
|
|
| |
|
|
+ +----+----+----+----+
|
|
| | |
|
|
+----+----+----+----+ +
|
|
| |
|
|
+ Encrypted Data +
|
|
~ ~
|
|
| |
|
|
+ +-------------------+
|
|
| |
|
|
+----+----+----+----+
|
|
{% endhighlight %}
|
|
|
|
<h4>Definition</h4>
|
|
{% highlight lang='dataspec' %}
|
|
Tunnel ID ::
|
|
4 bytes
|
|
the ID of the next hop
|
|
|
|
IV ::
|
|
16 bytes
|
|
the initialization vector
|
|
|
|
Encrypted Data ::
|
|
1008 bytes
|
|
the encrypted tunnel message
|
|
|
|
total size: 1028 Bytes
|
|
|
|
{% endhighlight %}
|
|
|
|
|
|
<h2 id="msg_Data">Tunnel Message (Decrypted)</h2>
|
|
These are the contents of a tunnel data message when decrypted.
|
|
{% highlight lang='dataspec' %}
|
|
+----+----+----+----+----+----+----+----+
|
|
| Tunnel ID | IV |
|
|
+----+----+----+----+ +
|
|
| |
|
|
+ +----+----+----+----+
|
|
| | Checksum |
|
|
+----+----+----+----+----+----+----+----+
|
|
| nonzero padding... |
|
|
~ ~
|
|
| |
|
|
+ +----+
|
|
| |zero|
|
|
+----+----+----+----+----+----+----+----+
|
|
| |
|
|
| Delivery Instructions 1 |
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| |
|
|
+ I2NP Message Fragment 1 +
|
|
| |
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| |
|
|
| Delivery Instructions 2... |
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| |
|
|
+ I2NP Message Fragment 2... +
|
|
| |
|
|
~ ~
|
|
| |
|
|
+ +-------------------+
|
|
| |
|
|
+----+----+----+----+
|
|
{% endhighlight %}
|
|
|
|
<h4>Definition</h4>
|
|
<pre>
|
|
Tunnel ID ::
|
|
4 bytes
|
|
the ID of the next hop
|
|
|
|
IV ::
|
|
16 bytes
|
|
the initialization vector
|
|
|
|
Checksum ::
|
|
4 bytes
|
|
the first 4 bytes of the SHA256 hash of (the contents of the message (after the zero byte) + IV)
|
|
|
|
Nonzero padding ::
|
|
0 or more bytes
|
|
random nonzero data for padding
|
|
|
|
Zero ::
|
|
1 byte
|
|
the value 0x00
|
|
|
|
Delivery Instructions ::
|
|
length varies but is typically 7, 39, 43, or 47 bytes
|
|
Indicates the fragment and the routing for the fragment
|
|
See <a href="#struct_TunnelMessageDeliveryInstructions">below</a> for specification
|
|
|
|
Message Fragment ::
|
|
1 to 996 bytes, actual maximum depends on delivery instruction size
|
|
A partial or full I2NP Message
|
|
|
|
total size: 1028 Bytes
|
|
|
|
</pre>
|
|
|
|
<h4>Notes</h4>
|
|
<ul><li>
|
|
The padding, if any, must be before the instruction/message pairs.
|
|
There is no provision for padding at the end.
|
|
</li><li>
|
|
The checksum does NOT cover the padding or the zero byte.
|
|
Take the message starting at the first delivery instructions, concatenate the IV,
|
|
and take the Hash of that.
|
|
</li></ul>
|
|
|
|
|
|
<h2 id="struct_TunnelMessageDeliveryInstructions">Tunnel Message Delivery Instructions</h2>
|
|
|
|
<p>The instructions are encoded with a single control byte, followed by any
|
|
necessary additional information. The first bit (MSB) in that control byte determines
|
|
how the remainder of the header is interpreted - if it is not set, the message
|
|
is either not fragmented or this is the first fragment in the message. If it is
|
|
set, this is a follow on fragment.</p>
|
|
|
|
<p>
|
|
This specification is for Delivery Instructions inside Tunnel Messages only.
|
|
Note that "Delivery Instructions" are also used inside
|
|
<a href="{{ site_url('docs/spec/i2np') }}#struct_GarlicClove">Garlic Cloves</a>,
|
|
where the format is significantly different.
|
|
See the
|
|
<a href="{{ site_url('docs/spec/i2np') }}#struct_GarlicCloveDeliveryInstructions">I2NP documentation</a>
|
|
for details.
|
|
Do NOT use the following specification for Garlic Clove Delivery Instructions!
|
|
|
|
|
|
<h3>First Fragment Delivery Instructions</h3>
|
|
<p>If the MSB of the first byte is 0, this is an initial I2NP message fragment,
|
|
or a complete (unfragmented) I2NP message, and the instructions are:</p>
|
|
{% highlight lang='dataspec' %}
|
|
+----+----+----+----+----+----+----+----+
|
|
|flag| Tunnel ID (opt) | |
|
|
+----+----+----+----+----+ +
|
|
| |
|
|
+ +
|
|
| To Hash (optional) |
|
|
+ +
|
|
| |
|
|
+ +--------------+
|
|
| |dly | Message
|
|
+----+----+----+----+----+----+----+----+
|
|
ID (opt) |extended opts (opt)| size |
|
|
+----+----+----+----+----+----+----+----+
|
|
{% endhighlight %}
|
|
|
|
<h4>Definition</h4>
|
|
<pre>
|
|
flag:
|
|
1 byte
|
|
Bit order: 76543210
|
|
bit 7: 0 to specify an initial fragment or an unfragmented message
|
|
bits 6-5: delivery type
|
|
0x0 = LOCAL, 0x01 = TUNNEL, 0x02 = ROUTER, 0x03 = unused, invalid
|
|
Note: LOCAL is used for inbound tunnels only, unimplemented for outbound tunnels
|
|
bit 4: delay included? Unimplemented, always 0
|
|
If 1, a delay byte is included
|
|
bit 3: fragmented? If 0, the message is not fragmented, what follows is the entire message
|
|
If 1, the message is fragmented, and the instructions contain a Message ID
|
|
bit 2: extended options? Unimplemented, always 0
|
|
If 1, extended options are included
|
|
bits 1-0: reserved, set to 0 for compatibility with future uses
|
|
|
|
Tunnel ID:
|
|
4 bytes
|
|
Optional, present if delivery type is TUNNEL
|
|
The destination tunnel ID
|
|
|
|
To Hash:
|
|
32 bytes
|
|
Optional, present if delivery type is DESTINATION, ROUTER, or TUNNEL
|
|
If DESTINATION, the SHA256 Hash of the destination
|
|
If ROUTER, the SHA256 Hash of the router
|
|
If TUNNEL, the SHA256 Hash of the gateway router
|
|
|
|
Delay:
|
|
1 byte
|
|
Optional, present if delay included flag is set
|
|
In tunnel messages: Unimplemented, never present; original specification:
|
|
bit 7: type (0 = strict, 1 = randomized)
|
|
bits 6-0: delay exponent (2^value minutes)
|
|
|
|
Message ID:
|
|
4 bytes
|
|
Optional, present if this message is the first of 2 or more fragments
|
|
(i.e. if the fragmented bit is 1)
|
|
An ID that uniquely identifies all fragments as belonging to a single message
|
|
(the current implementation uses the <a href="{{ site_url('docs/spec/i2np') }}#struct_header">I2NP Message ID</a>)
|
|
|
|
Extended Options:
|
|
2 or more bytes
|
|
Optional, present if extend options flag is set
|
|
Unimplemented, never present; original specification:
|
|
One byte length and then that many bytes
|
|
|
|
size:
|
|
2 bytes
|
|
The length of the fragment that follows
|
|
Valid values: 1 to approx. 960 in a tunnel message
|
|
|
|
Total length: Typical length is:
|
|
3 bytes for LOCAL delivery (tunnel message);
|
|
35 bytes for ROUTER / DESTINATION delivery or 39 bytes for TUNNEL delivery (unfragmented tunnel message);
|
|
39 bytes for ROUTER delivery or 43 bytes for TUNNEL delivery (first fragment)
|
|
|
|
</pre>
|
|
|
|
<h3>Follow-on Fragment Delivery Instructions</h3>
|
|
<p>If the MSB of the first byte is 1, this is a follow-on fragment, and the instructions are:</p>
|
|
{% highlight lang='dataspec' %}
|
|
+----+----+----+----+----+----+----+
|
|
|frag| Message ID | size |
|
|
+----+----+----+----+----+----+----+
|
|
{% endhighlight %}
|
|
|
|
<h4>Definition</h4>
|
|
<pre>
|
|
frag ::
|
|
1 byte
|
|
Bit order: 76543210
|
|
binary 1nnnnnnd
|
|
bit 7: 1 to indicate this is a follow-on fragment
|
|
bits 6-1: nnnnnn is the 6 bit fragment number from 1 to 63
|
|
bit 0: d is 1 to indicate the last fragment, 0 otherwise
|
|
|
|
Message ID ::
|
|
4 bytes
|
|
Identifies the fragment sequence that this fragment belongs to.
|
|
This will match the message ID of an initial fragment (a fragment
|
|
with flag bit 7 set to 0 and flag bit 3 set to 1).
|
|
|
|
size ::
|
|
2 bytes
|
|
the length of the fragment that follows
|
|
valid values: 1 to 996
|
|
|
|
total length: 7 bytes
|
|
</pre>
|
|
|
|
<h3><a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/i2np/DeliveryInstructions.html">Delivery Instructions Javadoc</a></h3>
|
|
|
|
<h2 id="notes">Notes</h2>
|
|
<h3>I2NP Message Maximum Size</h3>
|
|
<p>
|
|
While the maximum I2NP message size is nominally 64 KB, the size is further constrained by the
|
|
method of fragmenting I2NP messages into multiple 1 KB tunnel messages.
|
|
The maximum number of fragments is 64, and the initial fragment may not
|
|
be perfectly aligned at the start of a tunnel message.
|
|
So the message must nominally fit in 63 fragments.
|
|
<p>
|
|
The maximum size of an initial fragment is 956 bytes (assuming TUNNEL delivery mode);
|
|
the maximum size of a follow-on fragment is 996 bytes.
|
|
Therefore the maximum size is approximately 956 + (62 * 996) = 62708 bytes, or 61.2 KB.
|
|
</p>
|
|
|
|
<h3>Ordering, Batching, Packing</h3>
|
|
Tunnel messages may be dropped or reordered.
|
|
The tunnel gateway, who creates tunnel messages, is free to implement any
|
|
batching, mixing, or reordering strategy to fragment I2NP messages and
|
|
efficiently pack fragments into tunnel messages.
|
|
In general, an optimal packing is not possible (the "packing problem").
|
|
The gateways may implement various delay and reordering strategies.
|
|
|
|
<h3>Cover Traffic</h3>
|
|
Tunnel messages may contain only padding (i.e. no delivery instructions or message fragments at all)
|
|
for cover traffic. This is unimplemented.
|
|
|
|
{% endblock %}
|