i2p.www/i2p2www/pages/site/docs/protocol/i2cp.html

{% extends "global/layout.html" %}
{% block title %}I2CP{% endblock %}
{% block lastupdated %}2023-10{% endblock %}
{% block accuratefor %}0.9.59{% endblock %}
{% block content %}
<p>{% trans -%}
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.
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.
{%- endtrans %}</p>

<p>{% trans url='http://'+i2pconv('idk.i2p/javadoc-i2p')+'/net/i2p/client/package-summary.html',
libi2cp='http://git.repo.i2p/w/libi2cp.git',
streaming=site_url('docs/api/streaming') -%}
The protocol itself is implemented in Java, to provide the
<a href="{{ url }}">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.
There is also a <a href="{{ libi2cp }}">C library implementation</a>.
A non-Java client would also have to implement the
<a href="{{ streaming }}">streaming library</a> for TCP-style connections.
{%- endtrans %}</p>

<p>{% trans streaming=site_url('docs/api/streaming'), datagrams=site_url('docs/spec/datagrams'),
sam=site_url('docs/api/sam'), bob=site_url('docs/api/bob') -%}
Applications can take advantage of the base I2CP plus the 
<a href="{{ streaming }}">streaming</a> and <a href="{{ datagrams }}">datagram</a> libraries
by using the <a href="{{ sam }}">Simple Anonymous Messaging</a> or <a href="{{ bob }}">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.
{%- endtrans %}</p>

<p>{% trans elgamalaes=site_url('docs/how/elgamal-aes'),
cryptography=site_url('docs/how/cryptography'),
i2cp=site_url('docs/spec/i2cp') -%}
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="{{ elgamalaes }}">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="{{ cryptography }}#DSA">DSA public/private key signing</a>
for <a href="{{ i2cp }}#msg_CreateLeaseSet">LeaseSets</a> and
<a href="{{ i2cp }}#struct_SessionConfig">Session Configurations</a>, and management of those keys.
{%- endtrans %}</p>

<p>{% trans -%}
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.
{%- endtrans %}</p>

<p>{% trans commonstructures=site_url('docs/spec/common-structures') -%}
The router also supports external connections over SSL.
While SSL is not the default, it is strongly recommended for any traffic that may
be exposed to the open Internet. The authorization user/password (if any), the
<a href="{{ commonstructures }}#type_PrivateKey">Private Key</a> and
<a href="{{ commonstructures }}#type_SigningPrivateKey">Signing Private Key</a> for the
<a href="{{ commonstructures }}#struct_Destination">Destination</a>
are all transmitted in-the-clear unless SSL is enabled.
{%- endtrans %}</p>

<h2>{% trans %}I2CP Protocol Specification{% endtrans %}</h2>
<p>{% trans i2cp=site_url('docs/spec/i2cp') -%}
Now on the <a href="{{ i2cp }}">I2CP Specification page</a>.
{%- endtrans %}</p>


<h2>{% trans %}I2CP Initialization{% endtrans %}</h2>
<p>{% trans i2cp=site_url('docs/spec/i2cp') -%}
When a client connects to the router, it first sends a single protocol version byte (0x2A).
Then it sends a <a href="{{ i2cp }}#msg_GetDate">GetDate Message</a> and waits for the <a href="{{ i2cp }}#msg_SetDate">SetDate Message</a> response.
Next, it sends a <a href="{{ i2cp }}#msg_CreateSession">CreateSession Message</a> containing the session configuration.
It next awaits a <a href="{{ i2cp }}#msg_RequestLeaseSet">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.
{%- endtrans %}</p>

<h2 id="options">{% trans %}I2CP Options{% endtrans %}</h2>
<h3>{% trans %}Router-side Options{% endtrans %}</h3>
<p>{% trans i2cp=site_url('docs/spec/i2cp') -%}
The following options are traditionally passed to the router via
a <a href="{{ i2cp }}#struct_SessionConfig">SessionConfig</a> contained in a <a href="{{ i2cp }}#msg_CreateSession">CreateSession Message</a> or a <a href="{{ i2cp }}#msg_ReconfigureSession">ReconfigureSession Message</a>.
{%- endtrans %}</p>
<table border=1>
<tr>
<th colspan="6">{% trans %}Router-side Options{% endtrans %}</th>
</tr>

<tr>
<th>{% trans %}Option{% endtrans %}</th>
<th>{% trans %}As Of Release{% endtrans %}</th>
<th>{% trans %}Recommended Arguments{% endtrans %}</th>
<th>{% trans %}Allowable Range{% endtrans %}</th>
<th>{% trans %}Default{% endtrans %}</th>
<th>{% trans %}Description{% endtrans %}</th>
</tr>

<tr>
<td>clientMessageTimeout
<td>&nbsp;
<td>&nbsp;
<td>8*1000 - 120*1000
<td>60*1000
<td>{% trans -%}
The timeout (ms) for all sent messages. Unused.
See the protocol specification for per-message settings.
{%- endtrans %}</td>
</tr>

<tr>
<td>crypto.lowTagThreshold
<td>0.9.2</td>
<td>&nbsp;
<td>1-128
<td>30
<td>{% trans -%}
Minimum number of ElGamal/AES Session Tags before we send more.
Recommended: approximately tagsToSend * 2/3
{%- endtrans %}</td>
</tr>

<tr>
<td>crypto.ratchet.inboundTags
<td>0.9.47</td>
<td>&nbsp;
<td>1-?
<td>160
<td>
Inbound tag window for ECIES-X25519-AEAD-Ratchet.
Local inbound tagset size.
See proposal 144.
</td>
</tr>

<tr>
<td>crypto.ratchet.outboundTags
<td>0.9.47</td>
<td>&nbsp;
<td>1-?
<td>160
<td>
Outbound tag window for ECIES-X25519-AEAD-Ratchet.
Advisory to send to the far-end in the options block.
See proposal 144.
</td>
</tr>

<tr>
<td>crypto.tagsToSend
<td>0.9.2</td>
<td>&nbsp;
<td>1-128
<td>40
<td>{% trans -%}
Number of ElGamal/AES Session Tags to send at a time.
For clients with relatively low bandwidth per-client-pair (IRC, some UDP apps), this may be set lower.
{%- endtrans %}</td>
</tr>

<tr>
<td>explicitPeers
<td>&nbsp;</td>
<td>&nbsp;
<td>&nbsp;
<td>null
<td>{% trans %}Comma-separated list of Base 64 Hashes of peers to build tunnels through; for debugging only{% endtrans %}</td>
</tr>

<tr>
<td>i2cp.dontPublishLeaseSet
<td>&nbsp;</td>
<td>true, false
<td>&nbsp;
<td>false
<td>{% trans %}Should generally be set to true for clients and false for servers{% endtrans %}</td>
</tr>

<tr>
<td>i2cp.fastReceive
<td>0.9.4</td>
<td>&nbsp;
<td>true, false
<td>false
<td>{% trans -%}
If true, the router just sends the MessagePayload instead
of sending a MessageStatus and awaiting a ReceiveMessageBegin.
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.leaseSetAuthType
<td>0.9.41</td>
<td>0
<td>0-2
<td>0
<td>
The type of authentication for encrypted LS2.
0 for no per-client authentication (the default);
1 for DH per-client authentication;
2 for PSK per-client authentication.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetEncType
<td>0.9.38</td>
<td>4,0
<td>0-65535,...
<td>0
<td>
The encryption type to be used, as of 0.9.38.
Interpreted client-side, but also passed to the router in the
SessionConfig, to declare intent and check support.
As of 0.9.39, may be comma-separated values for multiple types.
See PublicKey in common strutures spec for values.
See proposals 123, 144, and 145.
</td>
</tr>

<tr>
<td>i2cp.leaseSetOfflineExpiration
<td>0.9.38</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>
The expiration of the offline signature, 4 bytes,
seconds since the epoch.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetOfflineSignature
<td>0.9.38</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>
The base 64 of the offline signature.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetPrivKey
<td>0.9.41</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>
A base 64 X25519 private key for the router to use to decrypt the encrypted LS2 locally,
only if per-client authentication is enabled.
Optionally preceded by the key type and ':'.
Only "ECIES_X25519:" is supported, which is the default.
See proposal 123.
Do not confuse with i2cp.leaseSetPrivateKey which is for the leaseset encryption keys.
</td>
</tr>

<tr>
<td>i2cp.leaseSetSecret
<td>0.9.39</td>
<td>&nbsp;
<td>&nbsp;
<td>""
<td>
Base 64 encoded UTF-8
secret used to blind the leaseset address.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetTransientPublicKey
<td>0.9.38</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>
[type:]b64  The base 64 of the transient private key,
prefixed by an optional sig type number or name,
default DSA_SHA1.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetType
<td>0.9.38</td>
<td>1,3,5,7
<td>1-255
<td>1
<td>
The type of leaseset to be sent in the CreateLeaseSet2 Message.
Interpreted client-side, but also passed to the router in the
SessionConfig, to declare intent and check support.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.messageReliability
<td>&nbsp;</td>
<td>&nbsp;
<td>BestEffort, None
<td>BestEffort
<td>{% trans -%}
Guaranteed is disabled;
None implemented in 0.8.1; the streaming lib default is None as of 0.8.1, the client side default is None as of 0.9.4
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.password
<td>0.8.2</td>
<td>string
<td>&nbsp;
<td>&nbsp;
<td rowspan="2">{% trans -%}
For authorization, if required by the router.
If the client is running in the same JVM as a router, this option is not required.
Warning - username and password are sent in the clear to the router, unless using SSL (i2cp.SSL=true).
Authorization is only recommended when using SSL.
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.username
<td>0.8.2</td>
<td>string
<td>&nbsp;
<td>&nbsp;
</tr>

<tr>
<td>inbound.allowZeroHop
<td>&nbsp;</td>
<td>true, false
<td>&nbsp;
<td>true
<td>{% trans %}If incoming zero hop tunnel is allowed{% endtrans %}</td>
</tr>

<tr>
<td>outbound.allowZeroHop
<td>&nbsp;</td>
<td>true, false
<td>&nbsp;
<td>true
<td>{% trans %}If outgoing zero hop tunnel is allowed{% endtrans %}</td>
</tr>

<tr>
<td>inbound.backupQuantity
<td>&nbsp;</td>
<td>{% trans from=0, to=3 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans %}No limit{% endtrans %}</td>
<td>0
<td>{% trans %}Number of redundant fail-over for tunnels in{% endtrans %}</td>
</tr>

<tr>
<td>outbound.backupQuantity
<td>&nbsp;</td>
<td>{% trans from=0, to=3 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans %}No limit{% endtrans %}</td>
<td>0
<td>{% trans %}Number of redundant fail-over for tunnels out{% endtrans %}</td>
</tr>

<tr>
<td>inbound.IPRestriction
<td>&nbsp;</td>
<td>{% trans from=0, to=4 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=0, to=4 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>2
<td>{% trans -%}
Number of IP bytes to match to determine if
two routers should not be in the same tunnel. 0 to disable.
{%- endtrans %}</td>
</tr>

<tr>
<td>outbound.IPRestriction
<td>&nbsp;</td>
<td>{% trans from=0, to=4 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=0, to=4 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>2
<td>{% trans -%}
Number of IP bytes to match to determine if
two routers should not be in the same tunnel. 0 to disable.
{%- endtrans %}</td>
</tr>

<tr>
<td>inbound.length
<td>&nbsp;</td>
<td>{% trans from=0, to=3 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=0, to=7 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>3
<td>{% trans %}Length of tunnels in{% endtrans %}</td>
</tr>

<tr>
<td>outbound.length
<td>&nbsp;</td>
<td>{% trans from=0, to=3 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=0, to=7 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>3
<td>{% trans %}Length of tunnels out{% endtrans %}</td>
</tr>

<tr>
<td>inbound.lengthVariance
<td>&nbsp;</td>
<td>{% trans from=-1, to=2 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=-7, to=7 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>0
<td>{% trans -%}
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.
{%- endtrans %}</td>
</tr>

<tr>
<td>outbound.lengthVariance
<td>&nbsp;</td>
<td>{% trans from=-1, to=2 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=-7, to=7 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>0
<td>{% trans -%}
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.
{%- endtrans %}</td>
</tr>

<tr>
<td>inbound.nickname
<td>&nbsp;</td>
<td>string
<td>&nbsp;
<td>&nbsp;
<td>{% trans -%}
Name of tunnel - generally used in routerconsole, which will
use the first few characters of the Base64 hash of the destination by default.
{%- endtrans %}</td>
</tr>

<tr>
<td>outbound.nickname
<td>&nbsp;</td>
<td>string
<td>&nbsp;
<td>&nbsp;
<td>{% trans %}Name of tunnel - generally ignored unless inbound.nickname is unset.{% endtrans %}</td>
</tr>

<tr>
<td>outbound.priority
<td>0.9.4</td>
<td>{% trans from=-25, to=25 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=-25, to=25 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>0
<td>{% trans -%}
Priority adjustment for outbound messages.
Higher is higher priority.
{%- endtrans %}</td>
</tr>

<tr>
<td>inbound.quantity</td>
<td>&nbsp;</td>
<td>{% trans from=1, to=3 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans from=1, to=16 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>2</td>
<td>{% trans -%}
Number of tunnels in.
Limit was increased from 6 to 16 in release 0.9; however, numbers higher than 6 are
incompatible with older releases.
{%- endtrans %}</td>
</tr>

<tr>
<td>outbound.quantity
<td>&nbsp;</td>
<td>{% trans from=1, to=3 %}number from {{ from }} to {{ to }}{% endtrans %}</td>
<td>{% trans %}No limit{% endtrans %}</td>
<td>2
<td>{% trans %}Number of tunnels out{% endtrans %}</td>
</tr>

<tr>
<td>inbound.randomKey
<td>0.9.17</td>
<td>Base 64 encoding of 32 random bytes</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td rowspan="2">{% trans -%}
Used for consistent peer ordering across restarts.
{%- endtrans %}</td>
</tr>

<tr>
<td>outbound.randomKey
<td>0.9.17</td>
<td>Base 64 encoding of 32 random bytes</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>

<tr>
<td>inbound.*
<td>&nbsp;</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>{% trans -%}
Any other options prefixed with "inbound." are stored
in the "unknown options" properties of the inbound tunnel pool's settings.
{%- endtrans %}</td>
</tr>

<tr>
<td>outbound.*
<td>&nbsp;</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>{% trans -%}
Any other options prefixed with "outbound." are stored
in the "unknown options" properties of the outbound tunnel pool's settings.
{%- endtrans %}</td>
</tr>

<tr>
<td>shouldBundleReplyInfo
<td>0.9.2</td>
<td>true, false
<td>&nbsp;
<td>true
<td>{% trans -%}
Set to false to disable ever bundling a reply LeaseSet.
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.
{%- endtrans %}
     
<p>{% trans -%}
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" may be appropriate:
{%- endtrans %}</p>
<ul>
<li>{% trans %}Unidirectional communication, no reply required{% endtrans %}</li>
<li>{% trans %}LeaseSet is published and higher reply latency is acceptable{% endtrans %}</li>
<li>{% trans -%}
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.
{%- endtrans %}</li>
</ul>
</td>
</tr>
</table>

<p>{% trans -%}
Note: Large quantity, length, or variance settings may cause significant performance or reliability problems.
{%- endtrans %}</p>

<p>{% trans commonstructures=site_url('docs/spec/common-structures') -%}
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.
Since options are encoded in a <a href="{{ commonstructures }}#type_Mapping">Mapping</a>,
all option names and values are limited to 255 bytes (not characters) maximum.
{%- endtrans %}</p>







<h3>{% trans %}Client-side Options{% endtrans %}</h3>
<p>{% trans -%}
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.
Other implementations may have different defaults.
{%- endtrans %}</p>
<table border=1>
<tr>
<th colspan="6">{% trans %}Client-side Options{% endtrans %}</th></tr>
</tr>

<tr>
<th>{% trans %}Option{% endtrans %}</th>
<th>{% trans %}As Of Release{% endtrans %}</th>
<th>{% trans %}Recommended Arguments{% endtrans %}</th>
<th>{% trans %}Allowable Range{% endtrans %}</th>
<th>{% trans %}Default{% endtrans %}</th>
<th>{% trans %}Description{% endtrans %}</th>
</tr>

<tr>
<td>i2cp.closeIdleTime
<td>0.7.1
<td>1800000
<td>{% trans num=300000 %}{{ num }} minimum{% endtrans %}
<td>&nbsp;
<td>{% trans %}(ms) Idle time required (default 30 minutes){% endtrans %}</td>
</tr>

<tr>
<td>i2cp.closeOnIdle
<td>0.7.1
<td>true, false
<td>&nbsp;
<td>false
<td>{% trans %}Close I2P session when idle{% endtrans %}</td>
</tr>

<tr>
<td>i2cp.encryptLeaseSet
<td>0.7.1
<td>true, false
<td>&nbsp;
<td>false
<td>{% trans %}Encrypt the lease{% endtrans %}</td>
</tr>

<tr>
<td>i2cp.fastReceive
<td>0.9.4
<td>&nbsp;
<td>true, false
<td>true
<td>{% trans -%}
If true, the router just sends the MessagePayload instead
of sending a MessageStatus and awaiting a ReceiveMessageBegin.
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.gzip
<td>0.6.5
<td>true, false
<td>&nbsp;
<td>true
<td>{% trans %}Gzip outbound data{% endtrans %}</td>
</tr>

<tr>
<td>i2cp.leaseSetAuthType
<td>0.9.41</td>
<td>0
<td>0-2
<td>0
<td>
The type of authentication for encrypted LS2.
0 for no per-client authentication (the default);
1 for DH per-client authentication;
2 for PSK per-client authentication.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetBlindedType
<td>0.9.39</td>
<td>&nbsp;
<td>0-65535
<td>See prop. 123
<td>
The sig type of the blinded key for encrypted LS2.
Default depends on the destination sig type.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetClient.dh.nnn
<td>0.9.41</td>
<td>b64name:b64pubkey
<td>&nbsp;
<td>&nbsp;
<td>
The base 64 of the client name (ignored, UI use only),
followed by a ':', followed by the base 64 of the public
key to use for DH per-client auth. nnn starts with 0
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetClient.psk.nnn
<td>0.9.41</td>
<td>b64name:b64privkey
<td>&nbsp;
<td>&nbsp;
<td>
The base 64 of the client name (ignored, UI use only),
followed by a ':', followed by the base 64 of the private
key to use for PSK per-client auth. nnn starts with 0
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetEncType
<td>0.9.38</td>
<td>0
<td>0-65535,...
<td>0
<td>
The encryption type to be used, as of 0.9.38.
Interpreted client-side, but also passed to the router in the
SessionConfig, to declare intent and check support.
As of 0.9.39, may be comma-separated values for multiple types.
See also i2cp.leaseSetPrivateKey.
See PublicKey in common strutures spec for values.
See proposals 123, 144, and 145.
</td>
</tr>

<tr>
<td>i2cp.leaseSetKey
<td>0.7.1
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>{% trans %}For encrypted leasesets. Base 64 SessionKey (44 characters){% endtrans %}</td>
</tr>

<tr>
<td>i2cp.leaseSetPrivateKey
<td>0.9.18</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>{% trans -%}
Base 64 private keys for encryption.
Optionally preceded by the encryption type name or number and ':'.
For LS1, only one key is supported, and
only "0:" or "ELGAMAL_2048:" is supported, which is the default.
As of 0.9.39, for LS2, multiple keys may be comma-separated,
and each key must be a different encryption type.
I2CP will generate the public key from the private key.
Use for persistent leaseset keys across restarts.
See proposals 123, 144, and 145.
See also i2cp.leaseSetEncType.
{%- endtrans %}
Do not confuse with i2cp.leaseSetPrivKey which is for encrypted LS2.
</td>
</tr>

<tr>
<td>i2cp.leaseSetSecret
<td>0.9.39</td>
<td>&nbsp;
<td>&nbsp;
<td>""
<td>
Base 64 encoded UTF-8
secret used to blind the leaseset address.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.leaseSetSigningPrivateKey
<td>0.9.18</td>
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>{% trans -%}
Base 64 private key for signatures.
Optionally preceded by the key type and ':'.
DSA_SHA1 is the default.
Key type must match the signature type in the destination.
I2CP will generate the public key from the private key.
Use for persistent leaseset keys across restarts.
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.leaseSetType
<td>0.9.38</td>
<td>1,3,5,7
<td>1-255
<td>1
<td>
The type of leaseset to be sent in the CreateLeaseSet2 Message.
Interpreted client-side, but also passed to the router in the
SessionConfig, to declare intent and check support.
See proposal 123.
</td>
</tr>

<tr>
<td>i2cp.messageReliability
<td>&nbsp;
<td>&nbsp;
<td>BestEffort, None
<td>None
<td>{% trans -%}
Guaranteed is disabled;
None implemented in 0.8.1; None is the default as of 0.9.4
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.reduceIdleTime
<td>0.7.1
<td>1200000
<td>{% trans num=300000 %}{{ num }} minimum{% endtrans %}
<td>&nbsp;
<td>{% trans %}(ms) Idle time required (default 20 minutes, minimum 5 minutes){% endtrans %}</td>
</tr>

<tr>
<td>i2cp.reduceOnIdle
<td>0.7.1
<td>true, false
<td>&nbsp;
<td>false
<td>{% trans %}Reduce tunnel quantity when idle{% endtrans %}</td>
</tr>

<tr>
<td>i2cp.reduceQuantity
<td>0.7.1
<td>1
<td>{% trans from=1, to=5 %}{{ from }} to {{ to }}{% endtrans %}</td>
<td>1
<td>{% trans %}Tunnel quantity when reduced (applies to both inbound and outbound){% endtrans %}</td>
</tr>

<tr>
<td>i2cp.SSL
<td>0.8.3
<td>true, false
<td>&nbsp;
<td>false
<td>{% trans -%}
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.
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.tcp.host
<td>&nbsp;
<td>&nbsp;
<td>&nbsp;
<td>127.0.0.1
<td>{% trans -%}
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.
{%- endtrans %}</td>
</tr>

<tr>
<td>i2cp.tcp.port
<td>&nbsp;
<td>&nbsp;
<td>1-65535
<td>7654
<td>{% trans -%}
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.
{%- endtrans %}</td>
</tr>
</table>

<p>{% trans -%}
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.
{%- endtrans %}</p>

<h2 id="format">{% trans %}I2CP Payload Data Format and Multiplexing{% endtrans %}</h2>
<p>{% trans i2cp=site_url('docs/spec/i2cp') -%}
The end-to-end messages handled by I2CP (i.e. the data sent by the client in a
<a href="{{ i2cp }}#msg_SendMessage">SendMessageMessage</a>
and received by the client in a
<a href="{{ i2cp }}#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.
{%- endtrans %}</p>

<p>{% trans -%}
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.
{%- endtrans %}
Implementations may select different gzip efforts on a per-socket or
per-message basis, depending on an assessment of the compressibility
of the contents. Due to the compressibility of destination padding implemented in
API 0.9.57 (proposal 161), compression of the streaming SYN packets
in each direction, and of repliable datagrams, is recommended even if
the payload is not compressible.
Implementations may wish to write a trivial gzip/gunzip function for
a gzip effort of 0, which will provide large efficiency gains
over a gzip library for this case.
</p>
<table border=1>
<tr>
<th>{% trans %}Bytes{% endtrans %}</th>
<th>{% trans %}Content{% endtrans %}</th>
</tr>

<tr>
<td>0-2
<td>{% trans %}Gzip header{% endtrans %} 0x1F 0x8B 0x08</th>
</tr>

<tr>
<td>3
<td>{% trans %}Gzip flags{% endtrans %}</td>
</tr>

<tr>
<td>4-5
<td>{% trans %}I2P Source port (Gzip mtime){% endtrans %}</td>
</tr>

<tr>
<td>6-7
<td>{% trans %}I2P Destination port (Gzip mtime){% endtrans %}</td>
</tr>

<tr>
<td>8
<td>{% trans %}Gzip xflags{% endtrans %} (set to 2 to be indistinguishable from the Java implementation)</td>
</tr>

<tr>
<td>9
<td>{% trans %}I2P Protocol (6 = Streaming, 17 = Datagram, 18 = Raw Datagrams) (Gzip OS){% endtrans %}</td>
</tr>
</table>

<p>
Note: I2P protocol numbers 224-254 are reserved for experimental protocols.
I2P protocol number 255 is reserved for future expansion.
</p>

<p>{% trans -%}
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>.
{%- endtrans %}</p>



<h2>Important Differences from Standard IP</h2>
<p>
I2CP ports are for I2P sockets and datagrams. They are unrelated to your local sockets or ports.
Because I2P did not support ports and protocol numbers prior to release 0.7.1,
ports and protocol numbers are somewhat different from that in standard IP,
for backward compatibility:
</p>

<ul><li>
Port 0 is valid and has special meaning.
</li><li>
Ports 1-1023 are not special or privileged.
</li><li>
Servers listen on port 0 by default, which means "all ports".
</li><li>
Clients send to port 0 by default, which means "any port".
</li><li>
Clients send from port 0 by default, which means "unspecified".
</li><li>
Servers may have a service listening on port 0 and other services listening on higher ports.
If so, the port 0 service is the default, and will be connected to if the incoming
socket or datagram port does not match another service.
</li><li>
Most I2P destinations only have one service running on them, so you may use the defaults, and ignore I2CP port configuration.
</li><li>
Protocol 0 is valid and means "any protocol". However, this is not recommended, and probably will not work.
Streaming requires that the protocol number is set to 6.
</li><li>
Streaming sockets are tracked by an internal connection ID.
Therefore, there is no requirement that the 5-tuple of dest:port:dest:port:protocol be unique.
For example, there may be multiple sockets with the same ports between two destinations.
Clients do not need to pick a "free port" for an outbound connection.
</li></ul>




<h2 id="future">{% trans %}Future Work{% endtrans %}</h2>
<ul>
<li>{% trans -%}
The current authorization mechanism could be modified to use hashed passwords.
{%- endtrans %}</li>

<li>{% trans -%}
The Signing Private Keys is included in the Create Lease Set message,
it is not required. Revocation is unimplemented.
It should be replaced with random data or removed.
{%- endtrans %}</li>

<li>{% trans pdf1=url_for('static', filename='pdf/I2CP_spec.pdf'), pdf2=url_for('static', filename='pdf/datastructures.pdf') -%}
Some improvements may be able to use messages previously defined but not implemented.
For reference, here is the
<a href="{{ pdf1 }}">I2CP Protocol Specification Version 0.9</a>
(PDF) dated August 28, 2003.
That document also references the
<a href="{{ pdf2 }}">Common Data Structures Specification Version 0.9</a>.
{%- endtrans %}</li>
</ul>


<h2 id="links">See Also</h2>
<a href="http://git.repo.i2p/w/libi2cp.git">C library implementation</a>

{% endblock %}