Data types Specification
This document describes some data types common to all I2P protocols, like I2NP, I2CP, SSU, etc.
Integer
Description
Represents a non-negative integer.
Contents
1 to 8 bytes in network byte order representing an unsigned integer
Date
Description
The number of milliseconds since midnight on January 1, 1970 in the GMT timezone. If the number is 0, the date is undefined or null.
Contents
8 byte Integer
String
Description
Represents a UTF-8 encoded string.
Contents
1 or more bytes where the first byte is the number of bytes (not characters!) in the string and the remaining 0-255 bytes are the non-null terminated UTF-8 encoded character array
Boolean
Description
A boolean value, supporting null/unknown representation 0=false, 1=true, 2=unknown/null
Contents
1 byte Integer
Notes
Deprecated - unusedPublicKey
Description
This structure is used in ElGamal encryption, representing only the exponent, not the primes, which are constant and defined in the cryptography specification.
Contents
256 bytes
Javadoc
PrivateKey
Description
This structure is used in ElGamal decryption, representing only the exponent, not the primes which are constant and defined in the cryptography specification.
Contents
256 bytes
Javadoc
SessionKey
Description
This structure is used for AES256 encryption and decryption.
Contents
32 bytes
Javadoc
SigningPublicKey
Description
This structure is used for verifying DSA signatures.
Contents
128 bytes
Javadoc
SigningPrivateKey
Description
This structure is used for creating DSA signatures.
Contents
20 bytes
Javadoc
Signature
Description
This structure represents the DSA signature of some data.
Contents
40 bytes
Javadoc
Hash
Description
Represents the SHA256 of some data.
Contents
32 bytes
Javadoc
Session Tag
Description
A random number
Contents
32 bytes
Javadoc
TunnelId
Description
Defines an identifier that is unique to each router in a tunnel.
Contents
4 byte Integer
Javadoc
Certificate
Description
A certificate is a container for various receipts or proof of works used throughout the I2P network.
Contents
1 byte Integer specifying certificate type, followed by a 2 Integer specifying the size of the certificate payload, then that many bytes.
+----+----+----+----+----+--//
|type| length | payload
+----+----+----+----+----+--//
type :: Integer
length -> 1 byte
case 0 -> NULL
case 1 -> HASHCASH
case 2 -> HIDDEN
case 3 -> SIGNED
case 4 -> MULTIPLE
length :: Integer
length -> 2 bytes
payload :: data
length -> $length bytes
Notes
- For Router Identities, the Certificate is always NULL, no others are currently implemented.
- For Garlic Cloves, the Certificate is always NULL, no others are currently implemented.
- For Garlic Messages, the Certificate is always NULL, no others are currently implemented.
- For Destinations, the Certificate may be non-NULL, however non-NULL certs are not widely used, and any checking is left to the application-level.
Javadoc
Mapping
Description
A set of key/value mappings or properties
Contents
A 2-byte size Integer followed by a series of String=String; pairs
+----+----+----+----+----+----+----+----+
| size |key string (len + data) | = |
+----+----+----+----+----+----+----+----+
| val string (len + data) | ; | ...
+----+----+----+----+----+----+----+
size :: Integer
length -> 2 bytes
Total number of bytes that follow
key string :: String
A string (one byte length followed by UTF-8 encoded characters)
= :: A single byte containing '='
val string :: String
A string (one byte length followed by UTF-8 encoded characters)
; :: A single byte containing ';'
Notes
- The encoding isn't optimal - we either need the '=' and ';' characters, or the string lengths, but not both
- Some documentation says that the strings may not include '=' or ';' but this encoding supports them
- Strings are defined to be UTF-8 but in the current implementation, I2CP uses UTF-8 but I2NP does not. For example, UTF-8 strings in a RouterInfo options mapping in a I2NP Database Store Message will be corrupted.
- Mappings contained in I2NP messages (i.e. in a RouterAddress or RouterInfo) must be sorted by key so that the signature will be invariant.
Javadoc
Common structure specification
RouterIdentity
Description
Defines the way to uniquely identify a particular router
Contents
PublicKey followed by SigningPublicKey and then a Certificate
+----+----+----+----+----+----+----+----+
| public_key |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| signing_key |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| certificate |
+----+----+----+--//
public_key :: PublicKey
length -> 256 bytes
signing_key :: SigningPublicKey
length -> 128 bytes
certificate :: Certificate
length -> >= 3 bytes
Total length: 387+ bytes
Notes
The certificate for a RouterIdentity is currently unused and is always NULL.Javadoc
Destination
Description
A Destination defines a particular endpoint to which messages can be directed for secure delivery.
Contents
PublicKey followed by a SigningPublicKey and then a Certificate
+----+----+----+----+----+----+----+----+
| public_key |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| signing_public_key |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| certificate
+---//
public_key :: PublicKey
length -> 256 bytes
signing_public_key :: SigningPublicKey
length -> 128 bytes
certificate :: Certificate
length -> >= 3 bytes
Total length: 387+ bytes
Javadoc
Lease
Description
Defines the authorization for a particular tunnel to receive messages targeting a Destination.
Contents
SHA256 Hash of the RouterIdentity of the gateway router, then the TunnelId, and finally an end Date
+----+----+----+----+----+----+----+----+
| tunnel_gw |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| tunnel_id | end_date
+----+----+----+----+----+----+----+----+
|
+----+----+----+----+
tunnel_gw :: Hash of the RouterIdentity of the tunnel gateway
length -> >= 32 bytes
tunnel_id :: TunnelId
length -> 4 bytes
end_date :: Date
length -> 8 bytes
Notes
- Total size: 44 bytes
Javadoc
LeaseSet
Description
Contains all of the currently authorized Leases for a particular Destination, the PublicKey to which garlic messages can be encrypted, and then the public key that can be used to revoke this particular version of the structure. The LeaseSet is one of the two structures stored in the network database( the other being RouterInfo), and is keyed under the SHA256 of the contained Destination.
Contents
Destination, followed by a PublicKey for encryption, then a SigningPublicKey which can be used to revoke this version of the LeaseSet, then a 1 byte Integer specifying how many Lease structures are in the set, followed by the actual Lease structures and finally a Signature of the previous bytes signed by the Destination's SigningPrivateKey
+----+----+----+----+----+----+----+----+
| destination |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| encryption_key |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| signing_key |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
|num | Lease 0 |
+----+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| Lease 1 |
+ +
| |
~ ~
~ ~
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| Lease ($num-1) |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| signature |
+ +
| |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
destination :: Destination
length -> >= 387 bytes
encryption_key :: PublicKey
length -> 256 bytes
signing_key :: SigningPublicKey
length -> 128 bytes
num :: Integer
length -> 1 byte
value: 0 <= num <= 6
leases :: [Lease]
length -> >= $num*44 bytes
signature :: Signature
length -> 40 bytes
Notes
- The public key of the destination was used for the old i2cp-to-i2cp encryption which was disabled in version 0.6, it is currently unused?
- The encryption key is used for end-to-end ElGamal/AES+SessionTag encryption. It is currently generated anew at every router startup, it is not persistent.
- The signature may be verified using the signing public key of the destination.
- The signing_key is currently unused. It was intended for LeaseSet revocation, which is unimplemented. It is currently generated anew at every router startup, it is not persistent.
Javadoc
RouterAddress
Description
This structure defines the means to contact a router through a transport protocol.
Contents
1 byte Integer defining the relative cost of using the address, where 0 is free and 255 is expensive, followed by the expiration Date after which the address should not be used, or if null, the address never expires. After that comes a String defining the transport protocol this router address uses. Finally there is a Mapping containing all of the transport specific options necessary to establish the connection, such as IP address, port number, email address, URL, etc.
+----+
|cost|
+----+----+----+----+----+----+----+----+
| expiration |
+----+----+----+----+--//+----+----+----+
| transport_style |
+----+----+----+----+--//+----+----+----+
| options |
+----+----+----+----+--//+----+----+----+
cost :: Integer
length -> 1 byte
case 0 -> free
case 255 -> expensive
expiration :: Date
length -> 8 bytes
case null -> never expires
transport_style :: String
length -> 1-256 bytes
options :: Mapping
Notes
- Cost is typically 5 or 6 for SSU, and 10 or 11 for NTCP.
- Expiration is currently unused, always null (all zeroes))
Javadoc
RouterInfo
Description
Defines all of the data that a router wants to publish for the network to see. The RouterInfo is one of two structures stored in the network database(the other being LeaseSet, and is keyed under the SHA256 of the contained RouterIdentity.
Contents
RouterIdentity followed by the Date, when the entry was published
+----+----+----+----+----+----+----+----+
| router_ident |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| published |
+----+----+----+----+----+----+----+----+
|size| RouterAddress 0 |
+----+ +
| |
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| RouterAddress 1 |
+ +
| |
~ ~
~ ~
~ ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| RouterAddress ($size-1) |
+ +
| |
~ ~
~ ~
| |
+----+----+----+----+-//-+----+----+----+
|psiz| options |
+----+----+----+----+-//-+----+----+----+
| signature |
+ +
| |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
router_ident :: RouterIdentity
length -> >= 387 bytes
published :: Date
length -> 8 bytes
size :: Integer
length -> 1 byte
addresses :: [RouterAddress]
length -> >= $size*267 bytes
peer_size :: Integer
length -> 1 byte
value -> 0
options :: Mapping
signature :: Signature
length -> 40 bytes
Notes
The peer_size Integer may be followed by a list of that many router hashes. This is currently unused. It was intended for a form of restricted routes, which is unimplemented.The signature may be verified using the signing public key of the router_ident.