I2P_Developers/i2p.www
3
0
Fork 5
Code Issues 27 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
12d23e36f1fa90354156a6d5158205b79156f888
i2p.www/www.i2p2/pages/tunnel_message_spec.html

312 lines
10 KiB
HTML
Raw Normal View History

- Big rewrite of how_peerselection - Split up tunnel-alt to new discussion and spec pages - Major enhancement to tunnel message spec - Some additions and update to tunnel discussion - Some tunnel-alt work, needs lots more - how_netdb LS store fixup
2010-07-30 19:30:31 +00:00
{% extends "_layout.html" %}
{% block title %}Tunnel Message Specification{% endblock %}
{% block content %}
Updated July 2010 for release 0.8
<h1>Tunnel Message Specification</h1>
This document specifies the format of tunnel messages.
For general information about tunnels see
<a href="tunnel-alt.html">the tunnel documentation</a>.
<h2>Message preprocessing</h3>
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="i2np.html">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="tunnel-alt.html">the tunnel documentation</a>.
<h2 id="msg_Data">Tunnel Message (Encrypted)</h2>
These are the contents of a tunnel data message after encryption.
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| Tunnel ID | IV |
+----+----+----+----+ +
| |
+ +----+----+----+----+
| | |
+----+----+----+----+ +
| |
+ Encrypted Data +
~ ~
| |
+ +-------------------+
| |
+----+----+----+----+
{% endfilter %}
</pre>
<h4>Definition</h4>
<pre>
{% filter escape %}
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
{% endfilter %}
</pre>
<h2 id="msg_Data">Tunnel Message (Decrypted)</h2>
These are the contents of a tunnel data message when decrypted.
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| Tunnel ID | IV |
+----+----+----+----+ +
| |
+ +----+----+----+----+
| | Checksum |
+----+----+----+----+----+----+----+----+
| nonzero padding.. |
~ ~
| |
+ +----+
| |zero|
+----+----+----+----+----+----+----+----+
| |
| Delivery Instructions 1 |
~ ~
| |
+----+----+----+----+----+----+----+----+
| |
+ I2NP Message Fragment 1 +
| |
~ ~
| |
+----+----+----+----+----+----+----+----+
| |
| Delivery Instructions 2... |
~ ~
| |
+----+----+----+----+----+----+----+----+
| |
+ I2NP Message Fragment 2... +
| |
~ ~
| |
+ +-------------------+
| |
+----+----+----+----+
{% endfilter %}
</pre>
<h4>Definition</h4>
<pre>
{% filter escape %}
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 remaining contents of the message concatenated with the 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="#delivery">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
{% endfilter %}
</pre>
<p>Note that the padding, if any, must be before the instruction/message pairs.
there is no provision for padding at the end.</p>
<h2 id="delivery">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>
<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 I2NP message, and the instructions are:</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
|flag| Tunnel ID (opt) | |
+----+----+----+----+----+ +
| |
+ +
| To Hash (optional) |
+ +
| |
+ +--------------+
| |dly | Msg... |
+----+----+----+----+----+----+----+----+
|..ID(opt)| ext opts... (opt) | size |
+----+----+----+----+----+----+----+----+
{% endfilter %}
</pre>
<h4>Definition</h4>
<pre>
{% filter escape %}
flag:
1 byte
Bit order: 76543210
bit 7: 0 to specify an initial fragment
bits 6-5: delivery type
0x0 = LOCAL, 0x01 = DESTINATION, 0x02 = ROUTER, 0x03 = TUNNEL
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
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 gatweay router
Delay:
1 bytes
Optional, present if delay included flag is set
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
An ID that uniquely identifies all fragments as belonging to a single message
(the current implementation uses the <a href="i2np_spec.html#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
Total length: Typical length is 39 bytes for ROUTER / DESTINATION delivery or 43 bytes for TUNNEL delivery (unfragmented);
43 bytes for ROUTER / DESTINATION delivery or 47 bytes for TUNNEL delivery (first fragment)
{% endfilter %}
</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>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+
|frag| Message ID | size |
+----+----+----+----+----+----+----+
{% endfilter %}
</pre>
<h4>Definition</h4>
<pre>
{% filter escape %}
frag:
1 byte
Binary 1nnnnnnd
The first bit is 1 to indicate this is a follow-on fragment
nnnnnn is the 6 bit fragment number from 1 to 63
d is 1 to indicate the last fragment, 0 otherwise
Message ID:
4 bytes
The same ID specified in the first fragment
size:
2 bytes
The length of the fragment that follows
Valid values: 1 to 996
Total length: 7 bytes
{% endfilter %}
</pre>
<h3><a href="http://docs.i2p2.de/router/net/i2p/data/i2np/DeliveryInstructions.html">Delivery Instructions Javadoc</a></h3>
<h2>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 %}
Reference in New Issue Copy Permalink