i2p.www/www.i2p2/pages/i2cp.html

{% extends "_layout.html" %}
{% block title %}I2CP{% endblock %}
{% block content %}
<p>The I2P Client Protocol (I2CP) exposes a strong separation of concerns between
the router and any client that wishes to communicate over the network.  It enables
secure and asynchronous messaging by sending and receiving messages over a 
single TCP socket, yet never exposing any private keys and authenticating itself
to the router only through signatures.  With I2CP, a client application tells the
router who they are (their "destination"), what anonymity, reliability, and 
latency tradeoffs to make, and where to send messages.  In turn the router uses
I2CP to tell the client when any messages have arrived, to request authorization
for some tunnels to be used, and, if necessary, to notify the client that the 
router is under attack and unable to operate safely.</p>

<p>As the I2CP requires all client libraries to provide an implementation of the
end to end encryption (including <a href="how_elgamalaes">ElGamal/AES+SessionTag</a>),
the protocol itself isn't likely to be adopted for normal client applications
(except for those implemented in Java that can use the existing I2P 
<a href="package-client.html">Client SDK</a>).  
This SDK is exposed in the i2p.jar package, which implements the client-side of I2CP.
Clients should never need to access the router.jar package, which contains the
router itself and the router-side of I2CP.
</p>

<p>
Applications can take advantage of the base I2CP plus the 
<a href="ministreaming">streaming</a> and <a href="datagrams">datagram</a> libraries
by using the <a href="sam">Simple Anonymous Messaging</a> or BOB protocols,
which do not require clients to deal with any sort of cryptography.
Also, clients may access the network by one of several proxies -
HTTP, CONNECT, and SOCKS 4/4a/5.
Alternatively, Java clients may access those libraries in ministreaming.jar and streaming.jar.
So there are several options for both Java and non-Java applications.
</p>

<p>I2CP end-to-end encryption was disabled in I2P release 0.6,
leaving in place the end-to-end garlic encryption.
However, client libraries must still implement public/private key signing
for LeaseSets, and key management.
</p>

<p>While the I2CP has been quite stable since its inception in
August of 2003, there have been several messages added.
Here is the
<a href="/_static/pdf/I2CP_spec.pdf">I2CP Protocol Specification Version 0.9</a>
(PDF) dated August 28, 2003.
That document also references the
<a href="/_static/pdf/datastructures.pdf">Common Data Structures Specification Version 0.9</a>.
There have been several changes to the protocol since that time,
and many of the messages in those documents were never implemented.
</p>

<p>In a standard I2P installation, port 7654 is used by java clients to communicate
with the local router via I2CP.
By default, the router binds to address 127.0.0.1. To bind to 0.0.0.0, set the
router advanced configuration option <tt>i2cp.tcp.bindAllInterfaces=true</tt> and restart.
</p>

<h2>I2CP Definition</h2>
<p>
<i>Note</i> - The following information is extracted from the current code base,
however it may be incomplete and/or inaccurate. Check the code to be sure.
Rather than completely document the messages here, we refer you to the
old protocol and data specifications linked above, together with the actual code.
<p>
R-&gt;C is Router to Client;
C-&gt;R is Client to Router
<p>
<table border=1>
<tr><th>Message<th>Direction<th>Type
<tr><td>
BandwidthLimitsMessage <i>(new in release 0.7.2)</i>
<td align="center">R-&gt;C
<td align=right>23
<tr><td>
CreateLeaseSetMessage
<td align="center">C-&gt;R
<td align=right>4
<tr><td>
CreateSessionMessage
<td align="center">C-&gt;R
<td align=right>1
<tr><td>
DestLookupMessage <i>(new in release 0.7)</i>
<td align="center">C-&gt;R
<td align=right>34
<tr><td>
DestReplyMessage <i>(new in release 0.7)</i>
<td align="center">R-&gt;C
<td align=right>35
<tr><td>
DestroySessionMessage
<td align="center">C-&gt;R
<td align=right>3
<tr><td>
DisconnectMessage
<td align="center">R-&gt;C
<td align=right>30
<tr><td>
GetBandwidthLimitsMessage <i>(new in release 0.7.2)</i>
<td align="center">C-&gt;R
<td align=right>8
<tr><td>
GetDateMessage
<td align="center">C-&gt;R
<td align=right>32
<tr><td>
MessagePayloadMessage
<td align="center">R-&gt;C
<td align=right>31
<tr><td>
MessageStatusMessage
<td align="center">R-&gt;C
<td align=right>22
<tr><td>
ReceiveMessageBeginMessage
<td align="center">R-&gt;C
<td align=right>6
<tr><td>
ReceiveMessageEndMessage
<td align="center">C-&gt;R
<td align=right>7
<tr><td>
ReconfigureSessionMessage <i>(new in release 0.7.1)</i>
<td align="center">C-&gt;R
<td align=right>2
<tr><td>
ReportAbuseMessage
<td align="center">R-&gt;C
<td align=right>29
<tr><td>
RequestLeaseSetMessage
<td align="center">R-&gt;C
<td align=right>21
<tr><td>
SendMessageExpiresMessage <i>(new in release 0.7.1)</i>
<td align="center">C-&gt;R
<td align=right>36
<tr><td>
SendMessageMessage
<td align="center">C-&gt;R
<td align=right>5
<tr><td>
SessionStatusMessage
<td align="center">R-&gt;C
<td align=right>20
<tr><td>
SetDateMessage
<td align="center">R-&gt;C
<td align=right>33
</table>

<h2>I2CP Initialization</h2>
<p>
When a client connects to the router, it first sends a single protocol version byte (0x2A).
Then it sends a GetDateMessage and waits for the SetDateMessage response.
Next, it sends a CreateSessionMessage containing the session configuration.
It next awaits a RequestLeaseSetMessage from the router, indicating that inbound tunnels
have been built, and responds with a CreateLeaseSetMessage containing the signed LeaseSet.
The client may now initiate or receive connections from other I2P destinations.

<h2 id="options">I2CP Options</h2>
<p>
The following options are traditionally passed to the router via
a SessionConfig contained in a CreateSessionMessage or a ReconfigureSessionMessage.
<p>
<table border=1>
<tr><th>Option <th>Recommended Arguments <th>Allowable Range<th>Default<th>Description
<tr><td>inbound.quantity <td>number from 1 to 3 <td>1 to 6<td>2<td>Number of tunnels in
<tr><td>outbound.quantity <td>number from 1 to 3 <td>No limit<td>2<td>Number of tunnels out
<tr><td>inbound.length <td>number from 0 to 3 <td>0 to 7<td>2<td>Length of  tunnels in
<tr><td>outbound.length <td>number from 0 to 3 <td>0 to 7<td>2<td>Length of tunnels out
<tr><td>inbound.lengthVariance <td>number from -1 to 2 <td>-7 to 7<td>0<td>Random amount to add or subtract to the length of tunnels in.
     A positive number x means add a random amount from 0 to x inclusive.
     A negative number -x means add a random amount from -x to x inclusive.
     The router will limit the total length of the tunnel to 0 to 7 inclusive.
     The default variance was 1 prior to release 0.7.6.
<tr><td>outbound.lengthVariance <td>number from -1 to 2 <td>-7 to 7<td>0<td>Random amount to add or subtract to the length of tunnels out.
     A positive number x means add a random amount from 0 to x inclusive.
     A negative number -x means add a random amount from -x to x inclusive.
     The router will limit the total length of the tunnel to 0 to 7 inclusive.
     The default variance was 1 prior to release 0.7.6.
<tr><td>inbound.backupQuantity <td>number from 0 to 3 <td>No limit<td>0<td>Number of redundant fail-over for tunnels in
<tr><td>outbound.backupQuantity <td>number from 0 to 3 <td>No limit<td>0<td>Number of redundant fail-over for tunnels out
<tr><td>inbound.nickname <td>string<td>&nbsp;<td>&nbsp;<td>Name of tunnel - generally used in routerconsole, which will
     use the first few characters of the Base64 hash of the destination by default.
<tr><td>outbound.nickname <td>string<td>&nbsp;<td>&nbsp;<td>Name of tunnel - generally ignored unless inbound.nickname is unset.
<tr><td>inbound.allowZeroHop <td>true, false<td>&nbsp;<td>true<td>If incoming zero hop tunnel is allowed
<tr><td>outbound.allowZeroHop <td>true, false<td>&nbsp;<td>true<td>If outgoing zero hop tunnel is allowed
<tr><td>inbound.IPRestriction <td>number from 0 to 4 <td>0 to 4<td>2<td>Number of IP bytes to match to determine if
     two routers should not be in the same tunnel. 0 to disable.
<tr><td>outbound.IPRestriction <td>number from 0 to 4 <td>0 to 4<td>2<td>Number of IP bytes to match to determine if
     two routers should not be in the same tunnel. 0 to disable.
<tr><td>i2cp.dontPublishLeaseSet <td>true, false<td>&nbsp;<td>false<td>Should generally be set to true for clients
     and false for servers
<tr><td>i2cp.messageReliability <td>&nbsp;<td>BestEffort, Guaranteed<td>BestEffort<td>Guaranteed is disabled
</table>
<p>
Note: Large quantity, length, or variance settings may cause significant performance or reliability problems.
<p>
Note: As of release 0.7.7, option names and values must use UTF-8 encoding.
This is primarily useful for nicknames.
Prior to that release, options with multi-byte characters were corrupted.

<p>
The following options are interpreted on the client side,
and will be interpreted if passed to the I2PSession via the I2PClient.createSession() call.
The streaming lib should also pass these options through to I2CP.
<p>
<table border=1>
<tr><th>Option <th>As Of Release<th>Recommended Arguments <th>Allowable Range<th>Default<th>Description
<tr><td>i2cp.tcp.host <td>&nbsp;<td>&nbsp;<td>&nbsp;<td>localhost<td>Router hostname
<tr><td>i2cp.tcp.port <td>&nbsp;<td>&nbsp;<td>1-65535<td>7654<td>Router I2CP port
<tr><td>i2cp.gzip<td>0.6.5<td>true, false <td>&nbsp;<td>true<td>Gzip outbound data
<tr><td>i2cp.reduceOnIdle<td>0.7.1<td>true, false <td>&nbsp;<td>false<td>Reduce tunnel quantity when idle
<tr><td>i2cp.closeOnIdle<td>0.7.1<td>true, false <td>&nbsp;<td>false<td>Close I2P session when idle
<tr><td>i2cp.reduceIdleTime<td>0.7.1<td>1200000<td>300000 minimum<td>&nbsp;<td>(ms) Idle time required (default 20 minutes, minimum 5 minutes)
<tr><td>i2cp.closeIdleTime<td>0.7.1<td>1800000<td>300000 minimum<td>&nbsp;<td>(ms) Idle time required (default 30 minutes)
<tr><td>i2cp.reduceQuantity<td>0.7.1<td>1<td>1 to 5<td>1<td>Tunnel quantity when reduced (applies to both inbound and outbound)
<tr><td>i2cp.encryptLeaseSet<td>0.7.1<td>true, false <td>&nbsp;<td>false<td>Encrypt the lease
<tr><td>i2cp.leaseSetKey<td>0.7.1<td>&nbsp;<td>&nbsp;<td>&nbsp;<td>Base64 SessionKey (44 characters)
</table>
<p>
Note: All arguments, including numbers, are strings. True/false values are case-insensitive strings.
Anything other than case-insensitive "true" is interpreted as false.
All option names are case-sensitive.

<h2 id="format">I2CP Data Format and Multiplexing</h2>
<p>
The end-to-end messages handled by I2CP (i.e. the data sent by the client in a SendMessageMessage and
received by the client in a MessagePayloadMessage) is gzipped with a standard 10-byte gzip
header beginning with 0x1F 0x8B 0x08 as
specified by <a href="http://www.ietf.org/rfc/rfc1952.txt">RFC 1952</a>.
As of release 0.7.1, I2P uses ignored portions of the gzip header to include
protocol, from-port, and to-port information, thus supporting streaming and
datagrams on the same destination, and allowing query/response using datagrams
to work reliably in the presence of multiple channels.
<p>
The gzip function cannot be completely turned off, however setting i2cp.gzip=false
turns the gzip effort setting to 0, which may save a little CPU.
<p>
<table border=1>
<tr><th>Bytes<th>Content
<tr><td>0-2<td>Gzip header 0x1F 0x8B 0x08
<tr><td>3<td>Gzip flags
<tr><td>4-5<td>I2P Source port (Gzip mtime)
<tr><td>6-7<td>I2P Destination port (Gzip mtime)
<tr><td>8<td>Gzip xflags
<tr><td>9<td>I2P Protocol (6 = Streaming, 17 = Datagram) (Gzip OS)
</table>


{% endblock %}