Description

Common header to all I2CP messages, containing the message length and message type.

Contents

1. 4 byte [Integer] specifying the length of the message body
2. 1 byte [Integer] specifying the message type.
3. The I2CP message body, 0 or more bytes

Notes

Actual message length limit is about 64 KB.

Description

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.

Contents

1. 4 byte [Integer]

Notes

Message IDs are unique within a session only; they are not globally unique.

Description

This structure is the content of a message being delivered from one Destination to another.

Contents

1. 4 byte [Integer] length
2. That many bytes

Notes

The payload is in a gzip format as specified on the I2CP Overview page [I2CP-FORMAT].

Actual message length limit is about 64 KB.

Description

Defines the configuration options for a particular client session.

Contents

1. [Destination]
2. [Mapping] of options
3. Creation [Date]
4. [Signature] of the previous 3 fields, signed by the [SigningPrivateKey]

Notes

• The options are specified on the I2CP Overview page [I2CP-OPTIONS].
• The [Mapping] must be sorted by key so that the signature will be validated correctly in the router.
• The creation date must be within +/- 30 seconds of the current time when processed by the router, or the config will be rejected.

Offline Signatures

• If the [Destination] is offline signed, the [Mapping] must contain the three options i2cp.leaseSetOfflineExpiration, i2cp.leaseSetTransientPublicKey, and i2cp.leaseSetOfflineSignature. The [Signature] is then generated by the transient [SigningPrivateKey] and is verified with the [SigningPublicKey] specified in i2cp.leaseSetTransientPublicKey. See [I2CP-OPTIONS] for details.

Description

Uniquely identifies a session on a particular router at a point in time.

Contents

1. 2 byte [Integer]

Notes

Session ID 0xffff is used to indicate "no session", for example for hostname lookups.

Description

Tell the client what the bandwidth limits are.

Sent from Router to Client in response to a GetBandwidthLimitsMessage.

Contents

1. 4 byte [Integer] Client inbound limit (KBps)
2. 4 byte [Integer] Client outbound limit (KBps)
3. 4 byte [Integer] Router inbound limit (KBps)
4. 4 byte [Integer] Router inbound burst limit (KBps)
5. 4 byte [Integer] Router outbound limit (KBps)
6. 4 byte [Integer] Router outbound burst limit (KBps)
7. 4 byte [Integer] Router burst time (seconds)
8. Nine 4-byte [Integer] (undefined)

Notes

The client limits may be the only values set, and may be the actual router limits, or a percentage of the router limits, or specific to the particular client, implementation-dependent. All the values labeled as router limits may be 0, implementation-dependent. As of release 0.7.2.

Description

Advise the router that a Destination is blinded, with optional lookup password and optional private key for decryption. See proposals 123 and 149 for details.

The router needs to know if a destination is blinded. If it is blinded and uses a secret or per-client authentication, it needs to have that information as well.

A Host Lookup of a new-format b32 address ("b33") tells the router that the address is blinded, but there's no mechanism to pass the secret or private key to the router in the Host Lookup message. While we could extend the Host Lookup message to add that information, it's cleaner to define a new message.

This message provides a programmatic way for the client to tell the router. Otherwise, the user would have to manually configure each destination.

Usage

Before a client sends a message to a blinded destination, it must either lookup the "b33" in a Host Lookup message, or send a Blinding Info message. If the blinded destination requires a secret or per-client authentication, the client must send a Blinding Info message.

The router does not send a reply to this message. Sent from Client to Router.

Contents

1. Session ID
2. 1 byte [Integer] Flags

• Bit order: 76543210
• Bit 0: 0 for everybody, 1 for per-client
• Bits 3-1: Authentication scheme, if bit 0 is set to 1 for per-client, otherwise 000
  • 000: DH client authentication (or no per-client authentication)
  • 001: PSK client authentication
• Bit 4: 1 if secret required, 0 if no secret required
• Bits 7-5: Unused, set to 0 for future compatibility

3. 1 byte [Integer] Endpoint type

• Type 0 is a [Hash]
• Type 1 is a hostname [String]
• Type 2 is a [Destination]
• Type 3 is a Sig Type and [SigningPublicKey]

4. 2 byte [Integer] Blinded Signature Type
5. 4 byte [Integer] Expiration Seconds since epoch
6. Endpoint: Data as specified, one of

• Type 0: 32 byte [Hash]

• Type 1: host name [String]

• Type 2: binary [Destination]

• Type 3: 2 byte [Integer] signature type, followed by

  [SigningPublicKey] (length as implied by sig type)

7. [PrivateKey] Decryption key Only present if flag bit 0 is set to 1. A 32-byte ECIES_X25519 private key, little-endian
8. [String] Lookup Password Only present if flag bit 4 is set to 1.

Notes

• As of release 0.9.43.
• The Hash endpoint type is probably not useful unless the router can do a reverse lookup in the address book to get the Destination.
• The hostname endpoint type is probably not useful unless the router can do a lookup in the address book to get the Destination.

Description

This message is sent in response to a RequestLeaseSetMessage or RequestVariableLeaseSetMessage and contains all of the [Lease] structures that should be published to the I2NP Network Database.

Sent from Client to Router.

Contents

1. Session ID
2. DSA [SigningPrivateKey] or 20 bytes ignored
3. [PrivateKey]
4. [LeaseSet]

Notes

The SigningPrivateKey matches the [SigningPublicKey] from within the LeaseSet, only if the signing key type is DSA. This is for LeaseSet revocation, which is unimplemented and is unlikely to ever be implemented. If the signing key type is not DSA, this field contains 20 bytes of random data. The length of this field is always 20 bytes, it does not ever equal the length of a non-DSA signing private key.

The PrivateKey matches the [PublicKey] from the LeaseSet. The PrivateKey is necessary for decrypting garlic routed messages.

Revocation is unimplemented. Connection to multiple routers is unimplemented in any client library.

Description

This message is sent in response to a RequestLeaseSetMessage or RequestVariableLeaseSetMessage and contains all of the [Lease] structures that should be published to the I2NP Network Database.

Sent from Client to Router. Since release 0.9.39. Per-client authentication for EncryptedLeaseSet supported as of 0.9.41. MetaLeaseSet is not yet supported via I2CP. See proposal 123 for more information.

Contents

1. Session ID
2. One byte type of lease set to follow.

• Type 1 is a [LeaseSet]
• Type 3 is a [LeaseSet2]
• Type 5 is a [EncryptedLeaseSet]
• Type 7 is a [MetaLeaseSet]

3. [LeaseSet] or [LeaseSet2] or [EncryptedLeaseSet] or [MetaLeaseSet]
4. One byte number of private keys to follow.
5. [PrivateKey] list. One for each public key in the lease set, in the same order. (Not present for Meta LS2)

• Encryption type (2 byte [Integer])
• Encryption key length (2 byte [Integer])
• Encryption [PrivateKey] (number of bytes specified)

Notes

The PrivateKeys match each of the [PublicKey] from the LeaseSet. The PrivateKeys are necessary for decrypting garlic routed messages.

See proposal 123 for more information on Encrypted LeaseSets.

The contents and format for MetaLeaseSet are preliminary and subject to change. There is no protocol specified for administration of multiple routers. See proposal 123 for more information.

The signing private key, previously defined for revocation and unused, is not present in LS2.

Preliminary version with message type 40 was in 0.9.38 but the format was changed. Type 40 is abandoned and is unsupported. Type 41 not valid until 0.9.39.

Description

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 SessionStatusMessage.

Contents

1. Session Config

Notes

• This is the second message sent by the client. Previously the client sent a GetDateMessage and received a SetDateMessage response.
• 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.
• If there is already a session on the router for this Destination, the session will be rejected.
• The [Mapping] in the Session Config must be sorted by key so that the signature will be validated correctly in the router.

Description

Sent from Client to Router. The router responds with a DestReplyMessage.

Contents

1. SHA-256 [Hash]

Notes

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.

HostLookupMessage is preferred as of release 0.9.11.

Description

Sent from Router to Client in response to a DestLookupMessage.

Contents

1. [Destination] on success, or [Hash] on failure

Notes

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.

Description

This message is sent from a client to destroy a session.

Sent from Client to Router. The router responds with a SessionStatusMessage.

Contents

1. Session ID

Notes

The router at this point should release all resources related to the session.

Description

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.

Contents

1. Reason [String]

Notes

Only implemented in the router-to-client direction. Disconnecting probably does end a session, in practice.

Description

Request that the router state what its current bandwidth limits are.

Sent from Client to Router. The router responds with a BandwidthLimitsMessage.

Contents

None

Notes

As of release 0.7.2.

As of release 0.8.3, supported in both I2PSimpleSession and in standard sessions.

Description

Sent from Client to Router. The router responds with a SetDateMessage.

Contents

1. I2CP API Version [String]
2. Authentication [Mapping] (optional, as of release 0.9.11)

Notes

• Generally the first message sent by the client after sending the protocol version byte.
• 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.
• As of release 0.9.11, the authentication [Mapping] 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 Session Config Mapping, and no authentication is enforced for GetDateMessage, GetBandwidthLimitsMessage, or DestLookupMessage. When enabled, authentication via GetDateMessage is required before any other messages as of release 0.9.16. This is only useful outside router context. This is an incompatible change, but will only affect sessions outside router context with authentication, which should be rare.

Description

Sent from Client to Router. The router responds with a HostReplyMessage.

This replaces the DestLookupMessage 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.

Contents

1. Session ID
2. 4 byte [Integer] request ID
3. 4 byte [Integer] timeout (ms)
4. 1 byte [Integer] request type
5. SHA-256 [Hash] or host name [String]

Notes

• As of release 0.9.11. Use DestLookupMessage for older routers.
• The session ID and request ID will be returned in the HostReplyMessage. Use 0xFFFF for the session ID if there is no session.
• 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.
• The request type is 0 for Hash and 1 for host name.
• Base 32 host name lookup is supported but it is preferred to convert it to a Hash first.

Description

Sent from Router to Client in response to a HostLookupMessage.

Contents

1. Session ID
2. 4 byte [Integer] request ID
3. 1 byte [Integer] result code

• 0: Success
• 1: Failure
• 2: Lookup password required (as of 0.9.43)
• 3: Private key required (as of 0.9.43)
• 4: Lookup password and private key required (as of 0.9.43)
• 5: Leaseset decryption failure (as of 0.9.43)

4. [Destination], only present if result code is zero.

Notes

• As of release 0.9.11. See HostLookupMessage notes.
• The session ID and request ID are those from the HostLookupMessage.
• The result code is 0 for success, 1-255 for failure. 1 indicates a generic failure. As of 0.9.43, the additional failure codes 2-5 were defined to support extended errors for "b33" lookups. See proposals 123 and 149 for additional information.

Description

Deliver the payload of a message to the client.

Sent from Router to Client. If i2cp.fastReceive=true, which is not the default, the client responds with a ReceiveMessageEndMessage.

Contents

1. Session ID
2. Message ID
3. Payload

Notes

Description

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 ReceiveMessageBeginMessage. For an outgoing message, this is a response to a SendMessageMessage or SendMessageExpiresMessage.

Contents

1. Session ID
2. Message ID generated by the router
3. 1 byte [Integer] status
4. 4 byte [Integer] size
5. 4 byte [Integer] nonce previously generated by the client

Notes

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 [MSM-JAVADOCS] for details. All status codes:

When status = 1 (accepted), the nonce matches the nonce in the SendMessageMessage, and the included Message ID will be used for subsequent success or failure notification. Otherwise, the nonce may be ignored.

Description

Request the router to deliver a message that it was previously notified of. Sent from Client to Router. The router responds with a MessagePayloadMessage.

Contents

1. Session ID
2. Message ID

Notes

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.

This is unused in "fast receive" mode, which is the default as of release 0.9.4.

Description

Tell the router that delivery of a message was completed successfully and that the router can discard the message.

Sent from Client to Router.

Contents

1. Session ID
2. Message ID

Notes

The ReceiveMessageEndMessage is sent after a MessagePayloadMessage fully delivers a message's payload.

This is unused in "fast receive" mode, which is the default as of release 0.9.4.

Description

Sent from Client to Router to update the session configuration. The router responds with a SessionStatusMessage.

Contents

1. Session ID
2. Session Config

Notes

• As of release 0.7.1.
• 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.
• The [Mapping] in the Session Config must be sorted by key so that the signature will be validated correctly in the router.
• Some configuration options may only be set in the CreateSessionMessage, and changes here will not be recognized by the router. Changes to tunnel options inbound.* and outbound.* are always recognized.
• In general, the router should merge the updated config with the current config, so the updated config only needs to contain the new or changed options. However, because of the merge, options may not be removed in this manner; they must be set explicitly to the desired default value.

Description

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.

Contents

1. Session ID
2. 1 byte [Integer] abuse severity (0 is minimally abusive, 255 being extremely abusive)
3. Reason [String]
4. Message ID

Notes

Unused. Not fully implemented. Both router and client can generate a ReportAbuseMessage, but neither has a handler for the message when received.

Description

Request that a client authorize the inclusion of a particular set of inbound tunnels. Sent from Router to Client. The client responds with a CreateLeaseSetMessage.

The first of these messages sent on a session is a signal to the client that tunnels are built and ready for traffic. The router must not send the first of these messages until at least one inbound AND one outbound tunnel have been built. Clients should timeout and destroy the session if the first of these messages is not received after some time (recommended: 5 minutes or more).

Contents

1. Session ID
2. 1 byte [Integer] number of tunnels
3. That many pairs of:
   1. [Hash]
   2. [TunnelId]
4. End [Date]

Notes

This requests a [LeaseSet] with all [Leases] set to expire at the same time. For client versions 0.9.7 or higher, RequestVariableLeaseSetMessage is preferred.

Description

Request that a client authorize the inclusion of a particular set of inbound tunnels.

Sent from Router to Client. The client responds with a CreateLeaseSetMessage or CreateLeaseSet2Message.

The first of these messages sent on a session is a signal to the client that tunnels are built and ready for traffic. The router must not send the first of these messages until at least one inbound AND one outbound tunnel have been built. Clients should timeout and destroy the session if the first of these messages is not received after some time (recommended: 5 minutes or more).

Contents

1. Session ID
2. 1 byte [Integer] number of tunnels
3. That many [Leases]

Notes

This requests a [LeaseSet] with an individual expiration time for each [Lease].

As of release 0.9.7. For clients before that release, use RequestLeaseSetMessage.

Description

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 MessageStatusMessage.

Contents

1. Session ID
2. [Destination]
3. Payload
4. 4 byte [Integer] nonce

Notes

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.

As of release 0.8.1, the router does not send either MessageStatusMessage if i2cp.messageReliability=none.

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 MessageStatusMessage, i.e. it acts as if i2cp.messageReliability=none for this message only.

Prior to release 0.9.14, a session with i2cp.messageReliability=none could not be overridden on a per-message basis. As of release 0.9.14, in a session with i2cp.messageReliability=none, the client may request delivery of a MessageStatusMessage with the delivery success or failure by setting the nonce to a nonzero value. The router will not send the "accepted" MessageStatusMessage but it will later send the client a MessageStatusMessage with the same nonce, and a success or failure value.

Description

Sent from Client to Router. Same as SendMessageMessage, except includes an expiration and options.

Contents

1. Session ID
2. [Destination]
3. Payload
4. 4 byte [Integer] nonce
5. 2 bytes of flags (options)
6. Expiration [Date] truncated from 8 bytes to 6 bytes

Notes

As of release 0.7.1.

In "best effort" mode, 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.

As of release 0.8.1, the router does not send either Message Status Message if i2cp.messageReliability=none.

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.

Prior to release 0.9.14, a session with i2cp.messageReliability=none could not be overridden on a per-message basis. As of release 0.9.14, in a session with i2cp.messageReliability=none, the client may request delivery of a Message Status Message with the delivery success or failure by setting the nonce to a nonzero value. The router will not send the "accepted" Message Status Message but it will later send the client a Message Status Message with the same nonce, and a success or failure value.

Flags Field

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.

Bit order: 15...0

Bits 15-11

Unused, must be zero

Bits 10-9

Message Reliability Override (Unimplemented, to be removed).

Bit 8

If 1, don't bundle a lease set in the garlic with this message. If 0, the router may bundle a lease set at its discretion.

Bits 7-4

Low tag threshold. If there are less than this many tags available, send more. This is advisory and does not force tags to be delivered.

Bits 3-0

Number of tags to send if required. This is advisory and does not force tags to be delivered.

Description

Instruct the client as to the status of its session.

Sent from Router to Client, in response to a CreateSessionMessage, ReconfigureSessionMessage, or DestroySessionMessage. In all cases, including in response to CreateSessionMessage, the router should respond immediately (do not wait for tunnels to be built).

Contents

1. Session ID
2. 1 byte [Integer] status

Notes

Status values are defined above. If the status is Created, the Session ID is the identifier to be used for the rest of the session.

Description

The current date and time. Sent from Router to Client as a part of the initial handshake. As of release 0.9.20, may also be sent at any time after the handshake to notify the client of a clock shift.

Contents

1. [Date]
2. I2CP API Version [String]

Notes

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.

Additional SetDate messages will not be sent to clients in the same JVM.