241 lines
14 KiB
HTML
241 lines
14 KiB
HTML
{% extends "_layout.html" %}
|
|
{% block title %}I2CP{% endblock %}
|
|
{% block content %}
|
|
Updated June 2012, current as of router version 0.9
|
|
|
|
<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.i2p-projekt.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 external 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.
|
|
Clients in the same JVM as the router pass messages directly to the router
|
|
through an internal JVM interface.
|
|
</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 colspan="5">Router-side Options</th></tr>
|
|
<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 16<td>2<td>Number of tunnels in.
|
|
Limit was increased from 6 to 16 in release 0.9; however, numbers higher than 6 are not
|
|
currently recommended, as this is untested and is incompatible with older releases.
|
|
<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, None<td>BestEffort<td>Guaranteed is disabled;
|
|
None implemented in 0.8.1; the streaming lib default is None as of 0.8.1
|
|
<tr><td>explicitPeers<td> <td> <td>null<td>Comma-separated list of Base 64 Hashes of peers to build tunnels through; for debugging only
|
|
<tr><td>i2cp.username<td>string<td> <td> <td>For authorization, if required by the router (since 0.8.2).
|
|
If the client is running in the same JVM as a router, this option is not required.
|
|
<tr><td>i2cp.password<td>string<td> <td> <td>For authorization, if required by the router (since 0.8.2).
|
|
If the client is running in the same JVM as a router, this option is not required.
|
|
<tr><td>crypto.tagsToSend<td> <td>1-128<td>40<td>Number of ElGamal/AES Session Tags to send at a time (since 0.9.2).
|
|
For clients with relatively low bandwidth per-client-pair (IRC, some UDP apps), this may be set lower.
|
|
<tr><td>crypto.lowTagThreshold<td> <td>1-128<td>30<td>Minimum number of ElGamal/AES Session Tags before we send more (since 0.9.2).
|
|
Recommended: approximately tagsToSend * 2/3
|
|
<tr><td>shouldBundleReplyInfo<td>true, false<td> <td>true<td>Set to false to disable ever bundling a reply LeaseSet (since 0.9.2).
|
|
For clients that do not publish their LeaseSet, this option must be true
|
|
for any reply to be possible. "true" is also recommended for multihomed servers
|
|
with long connection times.
|
|
|
|
<p> Setting to "false" may save significant outbound bandwidth, especially if
|
|
the client is configured with a large number of inbound tunnels (Leases).
|
|
If replies are still required, this may shift the bandwidth burden to
|
|
the far-end client and the floodfill.
|
|
There are several cases where "false" is may be appropriate:
|
|
<ul><li>
|
|
Unidirectional communication, no reply required
|
|
<li>
|
|
LeaseSet is published and higher reply latency is acceptable
|
|
<li>
|
|
LeaseSet is published, client is a "server", all connections are inbound
|
|
so the connecting far-end destination obviously has the leaseset already.
|
|
Connections are either short, or it is acceptable for latency on a long-lived
|
|
connection to temporarily increase while the other end re-fetches the LeaseSet
|
|
after expiration.
|
|
HTTP servers may fit these requirements.
|
|
</li></ul>
|
|
<tr><td>inbound.*<td> <td> <td> <td>Any other options prefixed with "inbound." are stored
|
|
in the "unknown options" properties of the inbound tunnel pool's settings.
|
|
<tr><td>outbound.*<td> <td> <td> <td>Any other options prefixed with "outbound." are stored
|
|
in the "unknown options" properties of the outbound tunnel pool's settings.
|
|
</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 colspan="6">Client-side Options</th></tr>
|
|
<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>127.0.0.1<td>Router hostname.
|
|
If the client is running in the same JVM as a router, this option is ignored, and the client connects to that router internally.
|
|
<tr><td>i2cp.tcp.port <td> <td> <td>1-65535<td>7654<td>Router I2CP port.
|
|
If the client is running in the same JVM as a router, this option is ignored, and the client connects to that router internally.
|
|
<tr><td>i2cp.SSL<td>0.8.3<td>true, false<td> <td>false<td>Connect to the router using SSL.
|
|
If the client is running in the same JVM as a router, this option is ignored, and the client connects to that router internally.
|
|
<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
|
|
<a href="i2cp_spec.html#msg_SendMessage">SendMessageMessage</a>
|
|
and received by the client in a
|
|
<a href="i2cp_spec.html#msg_MessagePayload">MessagePayloadMessage</a>)
|
|
are 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, 18 = Raw Datagrams) (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>
|
|
Implement I2CP and the streaming library in another programming language.
|
|
</li><li>
|
|
Is the initial Get Date / Set Date handshake required?
|
|
</li><li>
|
|
The current authorization mechanism could be modified to use hashed passwords.
|
|
</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 %}
|