I2P_Developers/i2p.www
3
0
Fork 5
Code Issues 27 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
d93c494de63f84af612104a8b466a23675e7984d
i2p.www/i2p2www/pages/site/docs/spec/i2cp.html
str4d 9805973315 Anchor fix
2014-07-18 02:13:45 +00:00

1281 lines
41 KiB
HTML
Raw Blame History

{% extends "global/layout.html" %}
{% block title %}I2CP Specification{% endblock %}
{% block lastupdated %}June 2014{% endblock %}
{% block accuratefor %}0.9.13{% endblock %}
{% block content %}
<h2>Overview</h2>
<p>
This page specified the I2P Control Protocol (I2CP),
which is the interface between clients and the router.
Java clients will use the I2CP client API, which implements this protocol.
Non-Java clients will most likely use a higher-layer protocol
such as SAM or BOB.
</p><p>
The protocol is only serialized if the client and router are not in the same JVM;
otherwise, I2CP message objects are passed via an internal JVM interface.
</p><p>
More information is on the <a href="{{ site_url('docs/protocol/i2cp') }}">I2CP Overview page</a>.
</p>
<h2>Sessions</h2>
<p>
The protocol was designed to handle multiple "sessions", each with a 2-byte session ID,
over a single TCP connection.
This is not fully implemented.
Do not attempt to use multiple sessions on a single I2CP connection.
</p>
<p>
It also appears that there are some provisions for a single client to talk to multiple
routers over separate connections. This is also untested,
and probably not useful.
</p>
<p>
It does not appear that there is currently a way for a session to be
maintained after a disconnect, or to be
recovered on a different
I2CP connection.
</p>
<h2>Example Message Sequences</h2>
<p>
Note: The examples below do not show the Protocol Byte (0x2a) that must be
sent from the client to the router when first connecting.
More information about connection initialization is
on the <a href="{{ site_url('docs/protocol/i2cp') }}">I2CP Overview page</a>.
</p>
<h3>Standard Session Establish</h3>
{% highlight %}
Client Router
---------------------> Get Date Message
Set Date Message <---------------------
---------------------> Create Session Message
Session Status Message <---------------------
Request LeaseSet Message <---------------------
---------------------> Create LeaseSet Message
{% endhighlight %}
<h3>Get Bandwidth Limits (Simple Session)</h3>
{% highlight %}
Client Router
---------------------> Get Bandwidth Limits Message
Bandwidth Limits Message <---------------------
{% endhighlight %}
<h3>Destination Lookup (Simple Session)</h3>
{% highlight %}
Client Router
---------------------> Dest Lookup Message
Dest Reply Message <---------------------
{% endhighlight %}
<h3>Outgoing Message</h3>
<p>Existing session, with i2cp.messageReliability=none</p>
{% highlight %}
Client Router
---------------------> Send Message Message
{% endhighlight %}
<p>Existing session, with i2cp.messageReliability=BestEffort</p>
{% highlight %}
Client Router
---------------------> Send Message Message
Message Status Message <---------------------
(accepted)
Message Status Message <---------------------
(succeeded)
{% endhighlight %}
<h3>Incoming Message</h3>
<p>Existing session, with i2cp.fastReceive=true (as of 0.9.4)</p>
{% highlight %}
Client Router
Message Payload Message <---------------------
{% endhighlight %}
<p>Existing session, with i2cp.fastReceive=false</p>
{% highlight %}
Client Router
Message Status Message <---------------------
(available)
---------------------> Receive Message Begin Message
Message Payload Message <---------------------
---------------------> Receive Message End Message
{% endhighlight %}
<h2 id="notes">Version Notes</h2>
<p>
The initial protocol version byte (0x2a) sent by the client is not expected to change.
Prior to release 0.8.7, the router's version information was not available to the client,
thus preventing new clients from working with old routers.
As of release 0.8.7, the two parties' protocol version strings are exchanged in the Get/Set Date Messages.
Going forward, clients may use this information to communicate correctly with old routers.
Clients and routers should not send messages that are unsupported by the other side,
as they generally disconnect the session upon reception of an unsupported message.
</p>
<h2 id="structures">Common structures</h2>
<h3 id="struct_header">I2CP message header</h3>
<h4>Description</h4>
<p>
Common header to all I2CP messages, containing the message length and message type.
</p>
<h4>Contents</h4>
<ol><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> specifying the length of the message body
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> specifying the message type.
</li><li>
The I2CP message body, 0 or more bytes
</li></ol>
<h4>Notes</h4>
<p>
Actual message length limit is about 64 KB.
</p>
<h3 id="struct_MessageId">Message ID</h3>
<h4>Description</h4>
<p>
Uniquely identifies a message waiting on a particular router at a
point in time.
This is always generated by the router and is NOT the same as the nonce generated by the client.
</p>
<h4>Contents</h4>
<ol><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
</li></ol>
<h4>Notes</h4>
<p>
Message IDs are unique within a session only; they are not globally unique.
</p>
<h3 id="struct_Payload">Payload</h3>
<h4>Description</h4>
<p>
This structure is the content of a message being delivered from one
Destination to another.
</p>
<h4>Contents</h4>
<ol><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> length
</li><li>
That many bytes
</li></ol>
<h4>Notes</h4>
<p>
The payload is in a gzip format as specified on the
<a href="{{ site_url('docs/protocol/i2cp') }}#format">I2CP Overview page</a>.
</p>
<h3 id="struct_SessionConfig">Session Config</h3>
<h4>Description</h4>
<p>
Defines the configuration options for a particular client session.
</p>
<h4>Contents</h4>
<ol><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a> of options
</li><li>
Creation <a href="{{ site_url('docs/spec/common-structures') }}#type_Date">Date</a>
</li><li>
DSA <a href="{{ site_url('docs/spec/common-structures') }}#type_Signature">Signature</a> of the previous 3 fields, signed by the
<a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>
</li></ol>
<h4>Notes</h4>
<ul><li>
The options are specified on the
<a href="{{ site_url('docs/protocol/i2cp') }}#options">I2CP Overview page</a>.
</li><li>
The <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a>
must be sorted by key so that the signature will be validated correctly in the router.
</li><li>
The creation date must be within +/- 30 seconds of the current time when processed by
the router, or the config will be rejected.
</li></ul>
<h3 id="struct_SessionId">Session ID</h3>
<h4>Description</h4>
<p>
Uniquely identifies a session on a particular router at a point in
time.
</p>
<h4>Contents</h4>
<ol><li>
2 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
</li></ol>
<h4>Notes</h4>
<p>
</p>
<h2 id="messages">Messages</h2>
See also the
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/i2cp/package-summary.html">I2CP Javadocs</a>.
<h3 id="types">Message Types</h3>
<table border=1>
<tr><th>Message<th>Direction<th>Type<th>Since
<tr><td>
<a href="#msg_BandwidthLimits">
BandwidthLimitsMessage
</a>
</a>
<td align="center">R-&gt;C
<td align=right>23
<td align="center">0.7.2
<tr><td>
<a href="#msg_CreateLeaseSet">
CreateLeaseSetMessage
</a>
<td align="center">C-&gt;R
<td align=right>4
<td>&nbsp;
<tr><td>
<a href="#msg_CreateSession">
CreateSessionMessage
</a>
<td align="center">C-&gt;R
<td align=right>1
<td>&nbsp;
<tr><td>
<a href="#msg_DestLookup">
DestLookupMessage
</a>
<td align="center">C-&gt;R
<td align=right>34
<td align="center">0.7
<tr><td>
<a href="#msg_DestReply">
DestReplyMessage
</a>
<td align="center">R-&gt;C
<td align=right>35
<td align="center">0.7
<tr><td>
<a href="#msg_DestroySession">
DestroySessionMessage
</a>
<td align="center">C-&gt;R
<td align=right>3
<td>&nbsp;
<tr><td>
<a href="#msg_Disconnect">
DisconnectMessage
</a>
<td align="center">bidir.
<td align=right>30
<td>&nbsp;
<tr><td>
<a href="#msg_GetBandwidthLimits">
GetBandwidthLimitsMessage
</a>
<td align="center">C-&gt;R
<td align=right>8
<td align="center">0.7.2
<tr><td>
<a href="#msg_GetDate">
GetDateMessage
</a>
<td align="center">C-&gt;R
<td align=right>32
<td>&nbsp;
<tr><td>
<a href="#msg_HostLookup">
HostLookupMessage
</a>
<td align="center">C-&gt;R
<td align=right>38
<td align="center">0.9.11
<tr><td>
<a href="#msg_HostReply">
HostReplyMessage
</a>
<td align="center">R-&gt;C
<td align=right>39
<td align="center">0.9.11
<tr><td>
<a href="#msg_MessagePayload">
MessagePayloadMessage
</a>
<td align="center">R-&gt;C
<td align=right>31
<td>&nbsp;
<tr><td>
<a href="#msg_MessageStatus">
MessageStatusMessage
</a>
<td align="center">R-&gt;C
<td align=right>22
<td>&nbsp;
<tr><td>
<a href="#msg_ReceiveMessageBegin">
ReceiveMessageBeginMessage
</a>
<td align="center">C-&gt;R
<td align=right>6
<td>&nbsp;
<tr><td>
<a href="#msg_ReceiveMessageEnd">
ReceiveMessageEndMessage
</a>
<td align="center">C-&gt;R
<td align=right>7
<td>&nbsp;
<tr><td>
<a href="#msg_ReconfigureSession">
ReconfigureSessionMessage
</a>
<td align="center">C-&gt;R
<td align=right>2
<td align="center">0.7.1
<tr><td>
<a href="#msg_ReportAbuse">
ReportAbuseMessage
</a>
<td align="center">bidir.
<td align=right>29
<td>&nbsp;
<tr><td>
<a href="#msg_RequestLeaseSet">
RequestLeaseSetMessage
</a>
<td align="center">R-&gt;C
<td align=right>21
<td>&nbsp;
<tr><td>
<a href="#msg_RequestVariableLeaseSet">
RequestVariableLeaseSetMessage
</a>
<td align="center">R-&gt;C
<td align=right>37
<td align="center">0.9.7
<tr><td>
<a href="#msg_SendMessage">
SendMessageMessage
</a>
<td align="center">C-&gt;R
<td align=right>5
<td>&nbsp;
<tr><td>
<a href="#msg_SendMessageExpires">
SendMessageExpiresMessage
</a>
<td align="center">C-&gt;R
<td align=right>36
<td align="center">0.7.1
<tr><td>
<a href="#msg_SessionStatus">
SessionStatusMessage
</a>
<td align="center">R-&gt;C
<td align=right>20
<td>&nbsp;
<tr><td>
<a href="#msg_SetDate">
SetDateMessage
</a>
<td align="center">R-&gt;C
<td align=right>33
<td>&nbsp;
</table>
<h3 id="msg_BandwidthLimits">Bandwidth Limits</h3>
<h4>Description</h4>
<p>
Tell the client what the bandwidth limits are.
Sent from Router to Client in response to a Get Bandwidth Limits Message.
</p>
<h4>Contents</h4>
<ol><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Client inbound limit (KBps)
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Client outbound limit (KBps)
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Router inbound limit (KBps)
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Router inbound burst limit (KBps)
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Router outbound limit (KBps)
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Router outbound burst limit (KBps)
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
Router burst time (seconds)
</li><li>
Nine 4-byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integers</a>
undefined
</li></ol>
<h4>Notes</h4>
<p>
Currently, the client limits are the only values set,
and are actually the router limits. All the values labeled as router limits are always 0.
As of release 0.7.2.
</p>
<h3 id="msg_CreateLeaseSet">Create Lease Set</h3>
<h4>Description</h4>
<p>
This message is sent in response to a
<a href="#msg_CreateLeaseSet">Create Lease Set Message</a>
or
<a href="#msg_CreateLeaseSet">Create Variable Lease Set Message</a>
and contains all
of the Lease structures that should be published to the I2NP Network Database.
Sent from Client to Router.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_LeaseSet">LeaseSet</a>
</li></ol>
<h4>Notes</h4>
<p>
The SigningPrivateKey matches the SigningPublicKey from within the
LeaseSet, as does the PrivateKey with the PublicKey. The Signing key is
necessary to allow the router to revoke the LeaseSet if the client goes offline,
and the encryption key is necessary for decrypting garlic routed messages. The
LeaseSet granted may include Lease structures for tunnels pointing at another
router if the client is actively connected to multiple routers with Leases granted
to each.
Really?
Revocation is unimplemented.
Connection to multiple routers is untested.
</p>
<h3 id="msg_CreateSession">Create Session</h3>
<h4>Description</h4>
<p>
This message is sent from a client to initiate a session, where a session is defined
as a single Destination's connection to the network, to which all messages for
that Destination will be delivered and from which all messages that
Destination sends to any other Destination will be sent through.
Sent from Client to Router.
The router responds with a <a href="#msg_SessionStatus">Session Status Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionConfig">Session Config</a>
</li></ol>
<h4>Notes</h4>
<ul><li>
This is the second message sent by the client. Previously the client sent a Get Date Message and received a Set Date Message response.
</li><li>
If the Date in the Session Config is too far (more than +/- 30 seconds) from the router's current time, the session will be rejected.
</li><li>
If there is already a session on the router for this Destination, the session will be rejected.
</li><li>
The <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a> in the Session Config
must be sorted by key so that the signature will be validated correctly in the router.
</li></ul>
<h3 id="msg_DestLookup">Dest Lookup</h3>
<h4>Description</h4>
<p>
Sent from Client to Router.
The router responds with a <a href="#msg_DestReply">Dest Reply Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Hash">SHA-256 Hash</a>
</li></ol>
<h4>Notes</h4>
<p>
As of release 0.7.
As of release 0.8.3, multiple outstanding lookups are supported,
and lookups are supported in both I2PSimpleSession and in standard sessions.
<a href="#msg_HostLookup">Host Lookup Message</a> is preferred as of release 0.9.11.
</p>
<h3 id="msg_DestReply">Dest Reply</h3>
<h4>Description</h4>
<p>
Sent from Router to Client in response to a Dest Lookup Message.
</p>
<h4>Contents</h4>
<ol><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>
on success, or
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Hash">Hash</a>
on failure
</li></ol>
<h4>Notes</h4>
<p>
As of release 0.7.
As of release 0.8.3,
the requested Hash is returned if the lookup failed,
so that the client may have multiple lookups outstanding and correlate the replies to the lookups.
To correlate a Destination response with a request, take the Hash of the Destination.
Prior to release 0.8.3, the response was empty on failure.
</p>
<h3 id="msg_Destroy Session">Destroy Session</h3>
<h4>Description</h4>
<p>
This message is sent from a client to destroy a session.
Sent from Client to Router.
The router responds with a <a href="#msg_SessionStatus">Session Status Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li></ol>
<h4>Notes</h4>
<p>
The router at this point should release all resources related to the session.
</p>
<h3 id="msg_Disconnect">Disconnect</h3>
<h4>Description</h4>
<p>
Tell the other party that there are problems and the current connection is about to
be destroyed. This does not necessarily end a session.
Sent either from router to client or from client to router.
</p>
<h4>Contents</h4>
<ol><li>
Reason <a href="{{ site_url('docs/spec/common-structures') }}#struct_String">String</a>
</li></ol>
<h4>Notes</h4>
<p>
Only implemented in the router-to-client direction.
Disconnecting probably does end a session, in practice.
</p>
<h3 id="msg_GetBandwidthLimits">Get Bandwidth Limits</h3>
<h4>Description</h4>
<p>
Request that the router state what its current bandwidth limits are.
Sent from Client to Router.
The router responds with a <a href="#msg_BandwidthLimits">Bandwidth Limits Message</a>.
</p>
<h4>Contents</h4>
<i>None</i>
<h4>Notes</h4>
<p>
As of release 0.7.2.
As of release 0.8.3,
supported in both I2PSimpleSession and in standard sessions.
</p>
<h3 id="msg_GetDate">Get Date</h3>
<h4>Description</h4>
<p>
Sent from Client to Router.
The router responds with a <a href="#msg_SetDate">Set Date Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
I2CP Version <a href="{{ site_url('docs/spec/common-structures') }}#struct_String">String</a>
</li><li>
Authentication <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a>
(optional, as of release 0.9.11)
</li></ol>
<h4>Notes</h4>
<ul><li>
Generally the first message sent by the client after sending the protocol version byte.
</li><li>
The version string is included as of release 0.8.7.
This is only useful if the client and router are not in the same JVM.
If it is not present, the client is version 0.8.6 or earlier.
</li><li>
As of release 0.9.11, the authentication
<a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a>
may be included, with the keys i2cp.username and i2cp.password.
The Mapping need not be sorted as this message is not signed.
Prior to and including 0.9.10, authentication is included in the
<a href="#struct_SessionConfig">Session Config</a> Mapping, and
no authentication is enforced for GetDate, GetBandwidthLimits, or DestLookup.
The Get Date authentication will be enforced in a future release.
This is only useful outside router context.
This will be an incompatible change, but will only affect sessions outside
router context with authentication, which should be rare.
</li></ul>
</p>
<h3 id="msg_HostLookup">Host Lookup</h3>
<h4>Description</h4>
<p>
Sent from Client to Router.
The router responds with a <a href="#msg_HostReply">Host Reply Message</a>.
This replaces the <a href="#msg_DestLookup">Dest Lookup Message</a>
and adds a request ID, a timeout, and host name lookup support.
As it also supports Hash lookups, it may be used for all lookups if the router supports it.
For host name lookups, the router will query its context's naming service.
This is only useful if the client is outside the router's context.
Inside router context, the client should query the naming service itself,
which is much more efficient.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> request ID
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> timeout (ms)
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> request type
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Hash">SHA-256 Hash</a>
or
host name <a href="{{ site_url('docs/spec/common-structures') }}#struct_String">String</a>
</li></ol>
<h4>Notes</h4>
<ul><li>
As of release 0.9.11.
Use <a href="#msg_DestLookup">Dest Lookup Message</a> for older routers.
</li><li>
The session ID and request ID will be returned in the <a href="#msg_HostReply">Host Reply Message</a>.
Use 0xFFFF for the session ID if there is no session.
</li><li>
Timeout is useful for Hash lookups. Recommended minimum 10,000 (10 sec.).
In the future it may also be useful for remote naming service lookups.
The value may be not be honored for local host name lookups, which should be fast.
</li><li>
The request type is 0 for Hash and 1 for host name.
</li><li>
Base 32 host name lookup is supported but it is preferred to convert
it to a Hash first.
</ul>
<h3 id="msg_HostReply">Host Reply</h3>
<h4>Description</h4>
<p>
Sent from Router to Client in response to a
<a href="#msg_HostLookup">Host Lookup Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> request ID
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> result code
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>,
only present if result code is zero.
</li></ol>
<h4>Notes</h4>
<ul><li>
As of release 0.9.11.
See Host Lookup notes.
</li><li>
The session ID and request ID are those from the Host Lookup.
</li><li>
The result code is 0 for success, 1-255 for failure.
Only 1 is used for failure now, more specific failure codes may be defined in the future.
</ul>
<h3 id="msg_MessagePayload">Message Payload</h3>
<h4>Description</h4>
<p>
Deliver the payload of a message to the client.
Sent from Router to Client.
The client responds with a <a href="#msg_ReceiveMessageEnd">Receive Message End Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="#struct_MessageId">Message ID</a>
</li><li>
<a href="#struct_Payload">Payload</a>
</li></ol>
<h4>Notes</h4>
<p>
</p>
<h3 id="msg_MessageStatus">Message Status</h3>
<h4>Description</h4>
<p>
Notify the client of the delivery status of an incoming or outgoing message.
Sent from Router to Client.
If this message indicates that an incoming message is available,
the client responds with a <a href="#msg_ReceiveMessageBegin">Receive Message Begin Message</a>.
For an outgoing message, this is a response to a
<a href="#msg_SendMessage">Send Message Message</a> or
<a href="#msg_SendMessageExpires">Send Message Expires Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="#struct_MessageId">Message ID</a> generated by the router
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> status
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> size
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> nonce previously generated by the client
</li></ol>
<h4>Notes</h4>
<p>
Through version 0.9.4,
the known status values are 0 for message is available, 1 for accepted, 2 for best
effort succeeded, 3 for best effort failed, 4 for guaranteed succeeded, 5 for
guaranteed failed. The size Integer specifies the size of the available
message and is only relevant for status = 0.
Even though guaranteed is unimplemented, (best effort is the only service), the current
router implementation uses the guaranteed status codes, not the best effort codes.
As of router version 0.9.5, additional status codes are defined,
however they are not necessarily implemented.
See the
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/i2cp/MessageStatusMessage.html">MessageStatusMessage Javadocs</a>
for details.
All status codes:
<table border=1>
<tr><th>Status Code<th>As Of Release<th>Name<th>Description
<tr><td align="center">0<td align="center">&nbsp;<td>Available<td>For incoming messages only.
The included size is the size in bytes of the available message.
This is unused in "fast receive" mode, which is the default as of release 0.9.4.
All other status codes below are for outgoing messages.
<tr><td align="center">1<td align="center">&nbsp;<td>Accepted<td>Outgoing message accepted by the local router for delivery.
The included nonce matches the nonce in the
Send Message Message, and the included Message ID
will be used for subsequent success or failure notification.
<tr><td align="center">2<td align="center">&nbsp;<td>Best Effort Success<td>Probable success (unused)
<tr><td align="center">3<td align="center">&nbsp;<td>Best Effort Failure<td>Probable failure
<tr><td align="center">4<td align="center">&nbsp;<td>Guaranteed Success<td>Probable success
<tr><td align="center">5<td align="center">&nbsp;<td>Guaranteed Failure<td>Generic failure, specific cause unknown.
May not really be a guaranteed failure.
<tr><td align="center">6<td align="center">0.9.5<td>Local Success<td>Local delivery successful.
The destination was another client on the same router.
<tr><td align="center">7<td align="center">0.9.5<td>Local Failure<td>Local delivery failure.
The destination was another client on the same router.
<tr><td align="center">8<td align="center">0.9.5<td>Router Failure<td>The local router is not ready, has shut down,
or has major problems.
This is a guaranteed failure.
<tr><td align="center">9<td align="center">0.9.5<td>Network Failure<td>The local computer apparently has no network connectivity at all.
This is a guaranteed failure.
<tr><td align="center">10<td align="center">0.9.5<td>Bad Session<td>The I2CP session is invalid or closed.
This is a guaranteed failure.
<tr><td align="center">11<td align="center">0.9.5<td>Bad Message<td>The message payload is invalid or zero-length or too big.
This is a guaranteed failure.
<tr><td align="center">12<td align="center">0.9.5<td>Bad Options<td>Something is invalid in the message options,
or the expiration is in the past or too far in the future.
This is a guaranteed failure.
<tr><td align="center">13<td align="center">0.9.5<td>Overflow Failure<td>Some queue or buffer in the router is full and the message was dropped.
This is a guaranteed failure.
<tr><td align="center">14<td align="center">0.9.5<td>Message Expired<td>The message expired before it could be sent.
This is a guaranteed failure.
<tr><td align="center">15<td align="center">0.9.5<td>Bad Local Leaseset<td>The client has not yet signed a leaseset, or the local keys
are invalid, or it has expired, or it does not have any tunnels in it.
This is a guaranteed failure.
<tr><td align="center">16<td align="center">0.9.5<td>No Local Tunnels<td>Local problems. No outbound tunnel to send through,
or no inbound tunnel if a reply is required.
This is a guaranteed failure.
<tr><td align="center">17<td align="center">0.9.5<td>Unsupported Encryption<td>The certs or options in the destination or its leaseset
indicate that it uses an encryption format that we don't support, so we can't talk to it.
This is a guaranteed failure.
<tr><td align="center">18<td align="center">0.9.5<td>Bad Destination<td>Something is wrong with the far-end destination.
Bad format, unsupported options, certificates, etc.
This is a guaranteed failure.
<tr><td align="center">19<td align="center">0.9.5<td>Bad Leaseset<td>We got the far-end leaseset but something strange is wrong with it.
Unsupported options or certificates, no tunnels, etc.
This is a guaranteed failure.
<tr><td align="center">20<td align="center">0.9.5<td>Expired Leaseset<td>We got the far-end leaseset but it's expired and we can't get a new one.
This is a guaranteed failure.
<tr><td align="center">21<td align="center">0.9.5<td>No Leaseset<td>Could not find the far-end leaseset.
This is a common failure, equivalent to a DNS lookup failure.
This is a guaranteed failure.
</table>
</p>
<p>
When status = 1 (accepted), the nonce matches the nonce in the
Send Message Message, and the included Message ID
will be used for subsequent success or failure notification.
Otherwise, the nonce may be ignored.
</p>
<h3 id="msg_ReceiveMessageBegin">Receive Message Begin</h3>
<h4>Description</h4>
<p>
Request the router to deliver a message that it was previously notified of.
Sent from Client to Router.
The router responds with a <a href="#msg_MessagePayload">Message Payload Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="#struct_MessageId">Message ID</a>
</li></ol>
<h4>Notes</h4>
<p>
The ReceiveMessageBeginMessage is sent as a response to a
MessageStatusMessage stating that a new message is available for pickup. If the
message id specified in the ReceiveMessageBeginMessage is invalid or
incorrect, the router may simply not reply, or it may send back a
DisconnectMessage.
</p>
<p>
This is unused in "fast receive" mode, which is the default as of release 0.9.4.
</p>
<h3 id="msg_ReceiveMessageEnd">Receive Message End</h3>
<h4>Description</h4>
<p>
Tell the router that delivery of a message was completed successfully and that
the router can discard the message.
Sent from Client to Router.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="#struct_MessageId">Message ID</a>
</li></ol>
<h4>Notes</h4>
<p>
The ReceiveMessageBeginMessage is sent after a MessagePayloadMessage fully
delivers a message's payload.
</p>
<p>
This is unused in "fast receive" mode, which is the default as of release 0.9.4.
</p>
<h3 id="msg_ReconfigureSession">Reconfigure Session</h3>
<h4>Description</h4>
<p>
Sent from Client to Router to update the session configuration.
The router responds with a <a href="#msg_SessionStatus">Session Status Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="#struct_SessionConfig">Session Config</a>
</li></ol>
<h4>Notes</h4>
<ul><li>
As of release 0.7.1.
</li><li>
If the Date in the Session Config is too far (more than +/- 30 seconds) from the router's current time, the session will be rejected.
</li><li>
The <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a> in the Session Config
must be sorted by key so that the signature will be validated correctly in the router.
</li></ul>
<h3 id="msg_ReportAbuse">Report Abuse</h3>
<h4>Description</h4>
<p>
Tell the other party (client or router) that they are under attack, potentially with reference to a
particular messageId. If the router is under attack, the client may decide to
migrate to another router, and if a client is under attack, the router may rebuild
its routers or banlist some of the peers that sent it messages delivering the attack.
Sent either from router to client or from client to router.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> abuse severity
(0 is minimally abusive, 255 being extremely abusive)
</li><li>
Reason <a href="{{ site_url('docs/spec/common-structures') }}#struct_String">String</a>
</li><li>
<a href="#struct_MessageId">Message ID</a>
</li></ol>
<h4>Notes</h4>
<p>
Unused.
Not fully implemented. Both router and client can generate Report Abuse Messages,
but neither has a handler for the message when received.
</p>
<h3 id="msg_RequestLeaseSet">Request LeaseSet</h3>
<h4>Description</h4>
<p>
Request that a client authorize the inclusion of a particular set of inbound tunnels.
Sent from Router to Client.
The client responds with a <a href="#msg_CreateLeaseSet">Create LeaseSet Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> number of tunnels
</li><li>
That many pairs of:
<ol><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_RouterIdentity">Router Identity</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#type_TunnelId">Tunnel ID</a>
</li></ol>
</li><li>
End <a href="{{ site_url('docs/spec/common-structures') }}#type_Date">Date</a>
</li></ol>
<h4>Notes</h4>
<p>
This requests a LeaseSet with all Leases set to expire at the same time.
For client versions 0.9.7 or higher, RequestVariableLeaseSet is preferred.
</p>
<h3 id="msg_RequestVariableLeaseSet">Request Variable LeaseSet</h3>
<h4>Description</h4>
<p>
Request that a client authorize the inclusion of a particular set of inbound tunnels.
Sent from Router to Client.
The client responds with a <a href="#msg_CreateLeaseSet">Create LeaseSet Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> number of tunnels
</li><li>
That many
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Lease">Leases</a>
</li></ol>
<h4>Notes</h4>
<p>
This requests a LeaseSet with an individual expiration time for each Lease.
As of release 0.9.7.
For clients before that release, use RequestLeaseSet.
</p>
<h3 id="msg_SendMessage">Send Message</h3>
<h4>Description</h4>
<p>
This is how a client sends a message (the payload) to the Destination.
The router will use a default expiration.
Sent from Client to Router.
The router responds with a <a href="#msg_MessageStatus">Message Status Message</a>.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>
</li><li>
<a href="#struct_Payload">Payload</a>
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> nonce
</li></ol>
<h4>Notes</h4>
<p>
As soon as the SendMessageMessage arrives fully intact, the router should return
a MessageStatusMessage stating that it has been accepted for delivery.
That message will contain the same nonce sent here.
Later on,
based on the delivery guarantees of the session configuration, the router may
additionally send back another MessageStatusMessage updating the status.
</p><p>
As of release 0.8.1, the router does not send either Message Status Message if
i2cp.messageReliability=none.
</p><p>
Prior to release 0.9.4, a nonce value of 0 was not allowed.
As of release 0.9.4, a nonce value of 0 is allowed, and tells to the router
that it should not send either Message Status Message, i.e. it acts as if
i2cp.messageReliability=none for this message only.
</p>
<h3 id="msg_SendMessageExpires">Send Message Expires</h3>
<h4>Description</h4>
<p>
Sent from Client to Router. Same as Send Message Message, except includes an expiration and options.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
<a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>
</li><li>
<a href="#struct_Payload">Payload</a>
</li><li>
4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> nonce
</li><li>
2 bytes of flags (options)
</li><li>
Expiration <a href="{{ site_url('docs/spec/common-structures') }}#type_Date">Date</a>
truncated from 8 bytes to 6 bytes
</li></ol>
<h4>Notes</h4>
<p>
As of release 0.7.1.
</p><p>
As soon as the SendMessageExpiresMessage arrives fully intact, the router should return
a MessageStatusMessage stating that it has been accepted for delivery.
That message will contain the same nonce sent here.
Later on,
based on the delivery guarantees of the session configuration, the router may
additionally send back another MessageStatusMessage updating the status.
</p><p>
As of release 0.8.1, the router does not send either Message Status Message if
i2cp.messageReliability=none.
</p><p>
Prior to release 0.9.4, a nonce value of 0 was not allowed.
As of release 0.9.4, a nonce value of 0 is allowed, and tells the router
that it should not send either Message Status Message, i.e. it acts as if
i2cp.messageReliability=none for this message only.
</p><p>
As of release 0.8.4, the upper two bytes of the Date are redefined to contain
flags. The flags must default to all zeros for backward compatibility.
The Date will not encroach on the flags field until the year 10889.
The flags may be used by the application to provide hints to the router
as to whether a LeaseSet and/or ElGamal/AES Session Tags should be delivered
with the message. The settings will significantly affect the amount of
protocol overhead and the reliability of message delivery.
The individual flag bits are defined as follows, as of release 0.9.2.
Definitions are subject to change. Use the SendMessageOptions class to construct the flags.
</p><p>
Bit order: 15...0
</p><p>
Bits 15-11: Unused, must be zero
</p><p>
Bits 10-9: Message Reliability Override (Preliminary, unimplemented, subject to change)
<table border=1>
<tr><th>Field value<th>Description
<tr><td align="center">00<td>Use session setting i2cp.messageReliabiltiy (default)
<tr><td align="center">01<td>Use "best effort" message reliabiltiy for this message,
overriding the session setting. The router will send one or more MessageStatusMessages in response.
<tr><td align="center">10<td>Use "guaranteed" message reliabiltiy for this message,
overriding the session setting. The router will send one or more MessageStatusMessages in response.
<tr><td align="center">11<td>Unused. Use a nonce value of 0 to force "none" and override a session setting
of "best effort" or "guaranteed".
</table>
</p><p>
Bit 8: If 1, don't send lease set
</p><p>
Bits 7-4: Low tag threshold. If there are less than this many tags available, send more.
<table border=1>
<tr><th>Field value<th>Tag threshold
<tr><td align="center">0000<td align="center">Use session key manager settings
<tr><td align="center">0001<td align="center">2
<tr><td align="center">0010<td align="center">3
<tr><td align="center">0011<td align="center">6
<tr><td align="center">0100<td align="center">9
<tr><td align="center">0101<td align="center">14
<tr><td align="center">0110<td align="center">20
<tr><td align="center">0111<td align="center">27
<tr><td align="center">1000<td align="center">35
<tr><td align="center">1001<td align="center">45
<tr><td align="center">1010<td align="center">57
<tr><td align="center">1011<td align="center">72
<tr><td align="center">1100<td align="center">92
<tr><td align="center">1101<td align="center">117
<tr><td align="center">1110<td align="center">147
<tr><td align="center">1111<td align="center">192
</table>
</p><p>
Bits 3-0: Number of tags to send if required.
<table border=1>
<tr><th>Field value<th>Tags to send
<tr><td align="center">0000<td align="center">Use session key manager settings
<tr><td align="center">0001<td align="center">2
<tr><td align="center">0010<td align="center">4
<tr><td align="center">0011<td align="center">6
<tr><td align="center">0100<td align="center">8
<tr><td align="center">0101<td align="center">12
<tr><td align="center">0110<td align="center">16
<tr><td align="center">0111<td align="center">24
<tr><td align="center">1000<td align="center">32
<tr><td align="center">1001<td align="center">40
<tr><td align="center">1010<td align="center">51
<tr><td align="center">1011<td align="center">64
<tr><td align="center">1100<td align="center">80
<tr><td align="center">1101<td align="center">100
<tr><td align="center">1110<td align="center">125
<tr><td align="center">1111<td align="center">160
</table>
</p>
<h3 id="msg_SessionStatus">Session Status</h3>
<h4>Description</h4>
<p>
Instruct the client as to the status of its session.
Sent from Router to Client, possibly in response to a Create Session or Reconfigure Session.
</p>
<h4>Contents</h4>
<ol><li>
<a href="#struct_SessionId">Session ID</a>
</li><li>
1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a> status
</li></ol>
<table border=1>
<tr><th>Status<th>Definition
<tr><td align="center">0<td>Destroyed: The session with the given ID is terminated.
<tr><td align="center">1<td>Created: In response to a Create Session, a new session with the given ID is now active.
<tr><td align="center">2<td>Updated: In response to a Reconfigure Session, an existing session with the given ID has been reconfigured.
<tr><td align="center">3<td>Invalid:
In response to a Create Session, the configuration is invalid. The included session ID should be ignored.
In response to a Reconfigure Session, the new configuration is invalid for the session with the given ID.
<tr><td align="center">4<td>Refused: In response to a Create Session, the router was unable to create the session,
perhaps due to limits being exceeded. The included session ID should be ignored. Since 0.9.12.
</table>
<h4>Notes</h4>
<p>
Status values include 0 for destroyed, 1 for created, 2 for updated, and
3 for invalid session.
If created, the Session ID is the identifier to be used for the rest of the session.
</p>
<h3 id="msg_SetDate">Set Date</h3>
<h4>Description</h4>
<p>
The current date and time.
Sent from Router to Client as a part of the initial handshake.
</p>
<h4>Contents</h4>
<ol><li>
<a href="{{ site_url('docs/spec/common-structures') }}#type_Date">Date</a>
</li><li>
I2CP Version <a href="{{ site_url('docs/spec/common-structures') }}#struct_String">String</a>
</li></ol>
<h4>Notes</h4>
<p>
This is generally the first message sent by the router.
The version string is included as of release 0.8.7.
This is only useful if the client and router are not in the same JVM.
If it is not present, the router is version 0.8.6 or earlier.
</p>
{% endblock %}
Reference in New Issue View Git Blame Copy Permalink