215 lines
12 KiB
HTML
215 lines
12 KiB
HTML
{% extends "_layout.html" %}
|
|
{% block title %}I2CP{% endblock %}
|
|
{% block content %}
|
|
Updated September 2010, current as of router version 0.8
|
|
|
|
<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, and to request authorization
|
|
for some tunnels to be used.
|
|
</p>
|
|
|
|
<p>
|
|
The protocol itself has only been implemented in Java, to provide the
|
|
<a href="http://docs.i2p2.de/javadoc/net/i2p/client/package-summary.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>
|
|
While implementing the client side of I2CP in a non-Java language is certainly feasible,
|
|
a non-Java client would also have to implement the
|
|
<a href="streaming.html">streaming library</a> for TCP-style connections.
|
|
Together, implementing I2CP and the streaming library would be a sizable task.
|
|
</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 <a href="bob.html">BOB</a> 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>Client-side end-to-end encryption (encrypting the data over the I2CP connection)
|
|
was disabled in I2P release 0.6,
|
|
leaving in place the <a href="how_elgamalaes.html">ElGamal/AES end-to-end encryption</a>
|
|
which is implemented in the router.
|
|
The only cryptography that client libraries must still implement is
|
|
<a href="how_cryptography.html#DSA">DSA public/private key signing</a>
|
|
for <a href="i2cp_spec.html#msg_CreateLeaseSet">LeaseSets</a> and <a href="i2cp_spec.html#type_SessionConfig">Session Configurations</a>, and management of those keys.
|
|
</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 Protocol Specification</h2>
|
|
<p>
|
|
Now on the
|
|
<a href="i2cp_spec.html">I2CP Specification page</a>.
|
|
</p>
|
|
|
|
|
|
<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 <a href="i2cp_spec.html#msg_GetDate">GetDate Message</a> and waits for the <a href="i2cp_spec.html#msg_GetDate">SetDate Message</a> response.
|
|
Next, it sends a <a href="i2cp_spec.html#msg_GetDate">CreateSession Message</a> containing the session configuration.
|
|
It next awaits a <a href="i2cp_spec.html#msg_GetDate">RequestLeaseSet Message</a> 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 <a href="i2cp_spec.html#type_SessionConfig">SessionConfig</a> contained in a <a href="i2cp_spec.html#msg_CreateSession">CreateSession Message</a> or a <a href="i2cp_spec.html#msg_ReconfigureSession">ReconfigureSession Message</a>.
|
|
<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> <td> <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> <td> <td>Name of tunnel - generally ignored unless inbound.nickname is unset.
|
|
<tr><td>inbound.allowZeroHop <td>true, false<td> <td>true<td>If incoming zero hop tunnel is allowed
|
|
<tr><td>outbound.allowZeroHop <td>true, false<td> <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> <td>false<td>Should generally be set to true for clients
|
|
and false for servers
|
|
<tr><td>i2cp.messageReliability <td> <td>BestEffort, Guaranteed<td>BestEffort<td>Guaranteed is disabled
|
|
<tr><td>explicitPeers<td> <td> <td>null<td>Comma-separated list of Base 64 Hashes of peers to build tunnels through; for debugging only
|
|
</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> <td> <td> <td>localhost<td>Router hostname
|
|
<tr><td>i2cp.tcp.port <td> <td> <td>1-65535<td>7654<td>Router I2CP port
|
|
<tr><td>i2cp.gzip<td>0.6.5<td>true, false <td> <td>true<td>Gzip outbound data
|
|
<tr><td>i2cp.reduceOnIdle<td>0.7.1<td>true, false <td> <td>false<td>Reduce tunnel quantity when idle
|
|
<tr><td>i2cp.closeOnIdle<td>0.7.1<td>true, false <td> <td>false<td>Close I2P session when idle
|
|
<tr><td>i2cp.reduceIdleTime<td>0.7.1<td>1200000<td>300000 minimum<td> <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> <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> <td>false<td>Encrypt the lease
|
|
<tr><td>i2cp.leaseSetKey<td>0.7.1<td> <td> <td> <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 Payload 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>
|
|
|
|
<p>
|
|
Data integrity is verified with the standard gzip CRC-32 as
|
|
specified by <a href="http://www.ietf.org/rfc/rfc1952.txt">RFC 1952</a>.
|
|
</p>
|
|
|
|
|
|
<h2 id="future">Future Work</h2>
|
|
<ul><li>
|
|
There is an in-JVM version of I2CP that uses a Java pipe instead of real sockets.
|
|
However, it still does message serialization and deserialization.
|
|
It should be refactored to pass the Message objects directly.
|
|
</li><li>
|
|
The protocol is highly inefficient, with three I2CP messages for every outgoing message,
|
|
and four I2CP messages for every incoming message.
|
|
Perhaps the acknowledgments and queueing could be eliminated, especially for the in-JVM version.
|
|
This would eliminate a lot of data structures and memory for holding
|
|
unacknowledged messages.
|
|
</li><li>
|
|
Implement i2cp.messageReliablity=none to disable the two Message Status Message responses
|
|
to a Send Message Message.
|
|
Make it the default? At least via the streaming lib.
|
|
</li><li>
|
|
The API does not support Dest Lookups or Get Bandwidth Limits Messages in a standard session,
|
|
only in a simple session.
|
|
This should be fixed.
|
|
</li><li>
|
|
The API does not support parallel Dest Lookups or Get Bandwidth Limits Messages in a session.
|
|
This should be fixed.
|
|
</li><li>
|
|
Implement I2CP and the streaming library in another programming language.
|
|
</li><li>
|
|
Is the initial Get Date / Set Date handshake required?
|
|
</li><li>
|
|
There is currently no authorization mechanism.
|
|
This would be required on the socket version only, not in the in-JVM version.
|
|
</li><li>
|
|
Private Keys are included in the Create Lease Set message,
|
|
are they really required? Revocation is unimplemented.
|
|
</li><li>
|
|
Some improvements may be able to use messages previously defined but not implemented.
|
|
For reference, 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>.
|
|
</li></ul>
|
|
|
|
|
|
|
|
{% endblock %}
|