This page was last updated in September 2016 and is accurate for router version 0.9.26.

Overview

This document specifies the format of tunnel messages. For general information
about tunnels see the tunnel documentation [TUNNEL-IMPL].

Message preprocessing

A tunnel gateway 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.

A gateway preprocesses[I2NP] messages by fragmenting and combining them
into tunnel messages.

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.

After the tunnel messages are created, they are encrypted as described in the
tunnel documentation [TUNNEL-IMPL].

Notes

The padding, if any, must be before the instruction/message pairs.
There is no provision for padding at the end.

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.

Tunnel Message Delivery Instructions

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.

This specification is for Delivery Instructions inside Tunnel Messages only.
Note that "Delivery Instructions" are also used inside Garlic Cloves
[I2NP-GC], where the format is significantly different. See the I2NP
documentation [I2NP-GCDI] for details. Do NOT use the following specification
for Garlic Clove Delivery Instructions!

First Fragment Delivery Instructions

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:

Notes

I2NP Message Maximum Size

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.

Ordering, Batching, Packing

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.

Cover Traffic

Tunnel messages may contain only padding (i.e. no delivery instructions or
message fragments at all) for cover traffic. This is unimplemented.