=============================== Common structures Specification =============================== .. meta:: :category: Design :lastupdated: January 2019 :accuratefor: 0.9.38 .. contents:: This document describes some data types common to all I2P protocols, like [I2NP]_, [I2CP]_, [SSU]_, etc. Common type specification ========================= .. _type-Integer: Integer ------- Description ``````````` Represents a non-negative integer. Contents ```````` 1 to 8 bytes in network byte order representing an unsigned integer .. _type-Date: 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_ .. _type-String: 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. Length limit is 255 bytes (not characters). Length may be 0. .. _type-PublicKey: PublicKey --------- Description ``````````` This structure is used in ElGamal encryption, representing only the exponent, not the primes, which are constant and defined in the cryptography specification [ELGAMAL]_. Contents ```````` Key type and length are inferred from context or are specified in the Key Certificate of a Destination or RouterInfo, or the key type field in a LeaseSet2_. The default type is ElGamal. As of release 0.9.38, other types may be supported, depending on context. ========== ============== ====== ===== Type Length (bytes) Since Usage ========== ============== ====== ===== ElGamal 256 All Router Identities and Destinations P256 64 TBD Reserved, see proposal 145 P384 96 TBD Reserved, see proposal 145 P521 132 TBD Reserved, see proposal 145 X25519 32 TBD Reserved, see proposal 144 =========== ============= ====== ===== JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/PublicKey.html .. _type-PrivateKey: 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 [ELGAMAL]_. Contents ```````` Key type and length are inferred from context or are specified in the Key Certificate of a Destination or RouterInfo, or the key type field in a LeaseSet2_. The default type is ElGamal. As of release 0.9.38, other types may be supported, depending on context. ========== ============== ====== ===== Type Length (bytes) Since Usage ========== ============== ====== ===== ElGamal 256 All Router Identities and Destinations P256 32 TBD Reserved, see proposal 145 P384 48 TBD Reserved, see proposal 145 P521 66 TBD Reserved, see proposal 145 X25519 32 TBD Reserved, see proposal 144 =========== ============= ====== ===== JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/PrivateKey.html .. _type-SessionKey: SessionKey ---------- Description ``````````` This structure is used for AES256 encryption and decryption. Contents ```````` 32 bytes JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/SessionKey.html .. _type-SigningPublicKey: SigningPublicKey ---------------- Description ``````````` This structure is used for verifying signatures. Contents ```````` Key type and length are inferred from context or are specified in the Key Certificate of a Destination. The default type is DSA_SHA1. As of release 0.9.12, other types may be supported, depending on context. ====================== ============== ====== ===== Type Length (bytes) Since Usage ====================== ============== ====== ===== DSA_SHA1 128 Legacy Router Identities and Destinations ECDSA_SHA256_P256 64 0.9.12 Recent Destinations ECDSA_SHA384_P384 96 0.9.12 Rarely used for Destinations ECDSA_SHA512_P521 132 0.9.12 Rarely used for Destinations RSA_SHA256_2048 256 0.9.12 Offline signing, never used for Router Identities or Destinations RSA_SHA384_3072 384 0.9.12 Offline signing, never used for Router Identities or Destinations RSA_SHA512_4096 512 0.9.12 Offline signing, never used for Router Identities or Destinations EdDSA_SHA512_Ed25519 32 0.9.15 Recent Router Identities and Destinations EdDSA_SHA512_Ed25519ph 32 0.9.25 Offline signing, never used for Router Identities or Destinations ====================== ============== ====== ===== Notes ````` * When a key is composed of two elements (for example points X,Y), it is serialized by padding each element to length/2 with leading zeros if necessary. * All types are Big Endian, except for EdDSA, which is stored and transmitted in a Little Endian format. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/SigningPublicKey.html .. _type-SigningPrivateKey: SigningPrivateKey ----------------- Description ``````````` This structure is used for creating signatures. Contents ```````` Key type and length are specified when created. The default type is DSA_SHA1. As of release 0.9.12, other types may be supported, depending on context. ====================== ============== ====== ===== Type Length (bytes) Since Usage ====================== ============== ====== ===== DSA_SHA1 20 Legacy Router Identities and Destinations ECDSA_SHA256_P256 32 0.9.12 Recent Destinations ECDSA_SHA384_P384 48 0.9.12 Rarely used for Destinations ECDSA_SHA512_P521 66 0.9.12 Rarely used for Destinations RSA_SHA256_2048 512 0.9.12 Offline signing, never used for Router Identities or Destinations RSA_SHA384_3072 768 0.9.12 Offline signing, never used for Router Identities or Destinations RSA_SHA512_4096 1024 0.9.12 Offline signing, never used for Router Identities or Destinations EdDSA_SHA512_Ed25519 32 0.9.15 Recent Router Identities and Destinations EdDSA_SHA512_Ed25519ph 32 0.9.25 Offline signing, never used for Router Identities or Destinations ====================== ============== ====== ===== Notes ````` * When a key is composed of two elements (for example points X,Y), it is serialized by padding each element to length/2 with leading zeros if necessary. * All types are Big Endian, except for EdDSA, which is stored and transmitted in a Little Endian format. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/SigningPrivateKey.html .. _type-Signature: Signature --------- Description ``````````` This structure represents the signature of some data. Contents ```````` Signature type and length are inferred from the type of key used. The default type is DSA_SHA1. As of release 0.9.12, other types may be supported, depending on context. ====================== ============== ====== ===== Type Length (bytes) Since Usage ====================== ============== ====== ===== DSA_SHA1 40 Legacy Router Identities and Destinations ECDSA_SHA256_P256 64 0.9.12 Recent Destinations ECDSA_SHA384_P384 96 0.9.12 Rarely used for Destinations ECDSA_SHA512_P521 132 0.9.12 Rarely used for Destinations RSA_SHA256_2048 256 0.9.12 Offline signing, never used for Router Identities or Destinations RSA_SHA384_3072 384 0.9.12 Offline signing, never used for Router Identities or Destinations RSA_SHA512_4096 512 0.9.12 Offline signing, never used for Router Identities or Destinations EdDSA_SHA512_Ed25519 64 0.9.15 Recent Router Identities and Destinations EdDSA_SHA512_Ed25519ph 64 0.9.25 Offline signing, never used for Router Identities or Destinations ====================== ============== ====== ===== Notes ````` * When a signature is composed of two elements (for example values R,S), it is serialized by padding each element to length/2 with leading zeros if necessary. * All types are Big Endian, except for EdDSA, which is stored and transmitted in a Little Endian format. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/Signature.html .. _type-Hash: Hash ---- Description ``````````` Represents the SHA256 of some data. Contents ```````` 32 bytes JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/Hash.html .. _type-SessionTag: Session Tag ----------- Description ``````````` A random number Contents ```````` 32 bytes JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/SessionTag.html .. _type-TunnelId: TunnelId -------- Description ``````````` Defines an identifier that is unique to each router in a tunnel. A Tunnel ID is generally greater than zero; do not use a value of zero except in special cases. Contents ```````` 4 byte Integer_ JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/TunnelId.html .. _type-Certificate: 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 byte Integer_ specifying the size of the certificate payload, then that many bytes. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+-// |type| length | payload +----+----+----+----+----+-// type :: `Integer` length -> 1 byte case 0 -> NULL case 1 -> HASHCASH case 2 -> HIDDEN case 3 -> SIGNED case 4 -> MULTIPLE case 5 -> KEY length :: `Integer` length -> 2 bytes payload :: data length -> $length bytes {% endhighlight %} Notes ````` * For `Router Identities`_, the Certificate is always NULL through version 0.9.15. As of 0.9.16, a Key Certificate may be used to specify the signing public key type. See below. * 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. As of 0.9.12, a Key Certificate may be used to specify the signing public key type. See below. * Implementers are cautioned to prohibit excess data in Certificates. The appropriate length for each certificate type should be enforced. .. _Router Identities: #struct_RouterIdentity .. _Garlic Cloves: {{ site_url('docs/spec/i2np') }}#struct_GarlicClove .. _Garlic Messages: {{ site_url('docs/spec/i2np') }}#msg_Garlic .. _Destinations: #struct_Destination Certificate Types ````````````````` The following certificate types are defined: ======== ========= ============== ============ ===== Type Type Code Payload Length Total Length Notes ======== ========= ============== ============ ===== Null 0 0 3 HashCash 1 varies varies Experimental, unused. Payload contains an ASCII colon-separated hashcash string. Hidden 2 0 3 Experimental, unused. Hidden routers generally do not announce that they are hidden. Signed 3 40 or 72 43 or 75 Experimental, unused. Payload contains a 40-byte DSA signature, optionally followed by the 32-byte Hash of the signing Destination. Multiple 4 varies varies Experimental, unused. Payload contains multiple certificates. Key 5 4+ 7+ Since 0.9.12. See below for details. ======== ========= ============== ============ ===== Key Certificates ```````````````` Key certificates were introduced in release 0.9.12. Prior to that release, all PublicKeys were 256-byte ElGamal keys, and all SigningPublicKeys were 128-byte DSA-SHA1 keys. A key certificate provides a mechanism to indicate the type of the PublicKey and SigningPublicKey in the Destination or RouterIdentity, and to package any key data in excess of the standard lengths. By maintaining exactly 384 bytes before the certificate, and putting any excess key data inside the certificate, we maintain compatibility for any software that parses Destinations and Router Identities. The key certificate payload contains: ================================== ====== Data Length ================================== ====== Signing Public Key Type (Integer_) 2 Crypto Public Key Type (Integer_) 2 Excess Signing Public Key Data 0+ Excess Crypto Public Key Data 0+ ================================== ====== The defined Signing Public Key types are: ====================== =========== ======================= ====== ===== Type Type Code Total Public Key Length Since Usage ====================== =========== ======================= ====== ===== DSA_SHA1 0 128 0.9.12 Legacy Router Identities and Destinations, never explicitly set ECDSA_SHA256_P256 1 64 0.9.12 Recent Destinations ECDSA_SHA384_P384 2 96 0.9.12 Sometimes used for Destinations ECDSA_SHA512_P521 3 132 0.9.12 Sometimes used for Destinations RSA_SHA256_2048 4 256 0.9.12 Offline only; never used in Key Certificates for Router Identities or Destinations RSA_SHA384_3072 5 384 0.9.12 Offline only; never used in Key Certificates for Router Identities or Destinations RSA_SHA512_4096 6 512 0.9.12 Offline only; never used in Key Certificates for Router Identities or Destinations EdDSA_SHA512_Ed25519 7 32 0.9.15 Recent Router Identities and Destinations EdDSA_SHA512_Ed25519ph 8 32 0.9.25 Offline only; never used in Key Certificates for Router Identities or Destinations reserved 9 Reserved, see proposal 134 reserved 10 Reserved, see proposal 134 reserved 65280-65534 Reserved for experimental use reserved 65535 Reserved for future expansion ====================== =========== ======================= ====== ===== The defined Crypto Public Key types are: ======== =========== ======================= ===== Type Type Code Total Public Key Length Usage ======== =========== ======================= ===== ElGamal 0 256 All Router Identities and Destinations P256 1 64 Reserved, see proposal 145 P384 2 96 Reserved, see proposal 145 P521 3 132 Reserved, see proposal 145 X25519 4 32 Reserved, see proposal 144 reserved 65280-65534 Reserved for experimental use reserved 65535 Reserved for future expansion ======== =========== ======================= ===== When a Key Certificate is not present, the preceeding 384 bytes in the Destination or RouterIdentity are defined as the 256-byte ElGamal PublicKey followed by the 128-byte DSA-SHA1 SigningPublicKey. When a Key Certificate is present, the preceeding 384 bytes are redefined as follows: * Complete or first portion of Crypto Public Key * Random padding if the total lengths of the two keys are less than 384 bytes * Complete or first portion of Signing Public Key The Crypto Public Key is aligned at the start and the Signing Public Key is aligned at the end. The padding (if any) is in the middle. The lengths and boundaries of the initial key data, the padding, and the excess key data portions in the certificates are not explicitly specified, but are derived from the lengths of the specified key types. If the total lengths of the Crypto and Signing Public Keys exceed 384 bytes, the remainder will be contained in the Key Certificate. If the Crypto Public Key length is not 256 bytes, the method for determining the boundary between the two keys is to be specified in a future revision of this document. Example layouts using an ElGamal Crypto Public Key and the Signing Public Key type indicated: ====================== ============== =============================== Signing Key Type Padding Length Excess Signing Key Data in Cert ====================== ============== =============================== DSA_SHA1 0 0 ECDSA_SHA256_P256 64 0 ECDSA_SHA384_P384 32 0 ECDSA_SHA512_P521 0 4 RSA_SHA256_2048 0 128 RSA_SHA384_3072 0 256 RSA_SHA512_4096 0 384 EdDSA_SHA512_Ed25519 96 0 EdDSA_SHA512_Ed25519ph 96 0 ====================== ============== =============================== JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/Certificate.html Notes ````` * Implementers are cautioned to prohibit excess data in Key Certificates. The appropriate length for each certificate type should be enforced. .. _type-Mapping: Mapping ------- Description ``````````` A set of key/value mappings or properties Contents ```````` A 2-byte size Integer followed by a series of String=String; pairs .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | 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 ';' {% endhighlight %} 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. * The encoding allows duplicate keys, however in any usage where the mapping is signed, duplicates may cause a signature failure. * Mappings contained in I2NP messages (i.e. in a RouterAddress or RouterInfo) must be sorted by key so that the signature will be invariant. Duplicate keys are not allowed. * Mappings contained in an `I2CP SessionConfig`_ must be sorted by key so that the signature will be invariant. Duplicate keys are not allowed. * The sort method is defined as in Java String.compareTo(), using the Unicode value of the characters. * While it is application-dependent, keys and values are generally case-sensitive. * Key and value string length limits are 255 bytes (not characters) each, plus the length byte. Length byte may be 0. * Total length limit is 65535 bytes, plus the 2 byte size field, or 65537 total. .. _I2CP SessionConfig: {{ site_url('docs/spec/i2cp') }}#struct_SessionConfig JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/DataHelper.html Common structure specification ============================== .. _struct-KeysAndCert: KeysAndCert ----------- Description ``````````` An encryption public key, a signing public key, and a certificate, used as either a RouterIdentity or a Destination. Contents ```````` A PublicKey_ followed by a SigningPublicKey_ and then a Certificate_. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | public_key | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | padding (optional) | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | signing_key | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | certificate | +----+----+----+-// public_key :: `PublicKey` (partial or full) length -> 256 bytes or as specified in key certificate padding :: random data length -> 0 bytes or as specified in key certificate padding length + signing_key length == 128 bytes signing__key :: `SigningPublicKey` (partial or full) length -> 128 bytes or as specified in key certificate padding length + signing_key length == 128 bytes certificate :: `Certificate` length -> >= 3 bytes total length: 387+ bytes {% endhighlight %} Notes ````` * Do not assume that these are always 387 bytes! They are 387 bytes plus the certificate length specified at bytes 385-386, which may be non-zero. * As of release 0.9.12, if the certificate is a Key Certificate, the boundaries of the key fields may vary. See the Key Certificate section above for details. * The Crypto Public Key is aligned at the start and the Signing Public Key is aligned at the end. The padding (if any) is in the middle. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/KeysAndCert.html .. _struct-RouterIdentity: RouterIdentity -------------- Description ``````````` Defines the way to uniquely identify a particular router Contents ```````` Identical to KeysAndCert. Notes ````` * The certificate for a RouterIdentity was always NULL until release 0.9.12. * Do not assume that these are always 387 bytes! They are 387 bytes plus the certificate length specified at bytes 385-386, which may be non-zero. * As of release 0.9.12, if the certificate is a Key Certificate, the boundaries of the key fields may vary. See the Key Certificate section above for details. * The Crypto Public Key is aligned at the start and the Signing Public Key is aligned at the end. The padding (if any) is in the middle. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/router/RouterIdentity.html .. _struct-Destination: Destination ----------- Description ``````````` A Destination defines a particular endpoint to which messages can be directed for secure delivery. Contents ```````` Identical to KeysAndCert_. 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 except for the IV for LeaseSet encryption, which is deprecated. The public key in the LeaseSet is used instead. * Do not assume that these are always 387 bytes! They are 387 bytes plus the certificate length specified at bytes 385-386, which may be non-zero. * As of release 0.9.12, if the certificate is a Key Certificate, the boundaries of the key fields may vary. See the Key Certificate section above for details. * The Crypto Public Key is aligned at the start and the Signing Public Key is aligned at the end. The padding (if any) is in the middle. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/Destination.html .. _struct-Lease: 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_. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | 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 {% endhighlight %} Notes ````` * Total size: 44 bytes JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/Lease.html .. _struct-LeaseSet: 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 SigningPublicKey_ 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_. .. _Leases: #struct-lease 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_. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | 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 or as specified in destination's key certificate num :: `Integer` length -> 1 byte Number of leases to follow value: 0 <= num <= 16 leases :: [`Lease`] length -> $num*44 bytes signature :: `Signature` length -> 40 bytes or as specified in destination's key certificate {% endhighlight %} 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 [ELGAMAL-AES]_. 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. The signing key type is always the same as the destination's signing key type. * The earliest expiration of all the Leases is treated as the timestamp or version of the LeaseSet. Routers will generally not accept a store of a LeaseSet unless it is "newer" than the current one. Take care when publishing a new LeaseSet where the oldest Lease is the same as the oldest Lease in the previous LeaseSet. The publishing router should generally increment the expiration of the oldest Lease by at least 1 ms in that case. * Prior to release 0.9.7, when included in a DatabaseStore Message sent by the originating router, the router set all the published leases' expirations to the same value, that of the earliest lease. As of release 0.9.7, the router publishes the actual lease expiration for each lease. This is an implementation detail and not part of the structures specification. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/LeaseSet.html .. _struct-Lease2: Lease2 ------ Description ``````````` Defines the authorization for a particular tunnel to receive messages targeting a Destination_. Same as Lease_ but with a 4-byte end_date. Used by LeaseSet2_. Supported as of 0.9.38; see proposal 123 for more information. Contents ```````` SHA256 Hash_ of the RouterIdentity_ of the gateway router, then the TunnelId_, and finally a 4 byte end date. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | 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 :: 4 byte date length -> 4 bytes Seconds since the epoch, rolls over in 2106. {% endhighlight %} Notes ````` * Total size: 40 bytes JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/Lease2.html .. _struct-OfflineSignature: OfflineSignature ---------------- Description ``````````` This is an optional part of the LeaseSet2Header_. Also used in streaming and I2CP. Supported as of 0.9.38; see proposal 123 for more information. Contents ```````` Contains the Destination_, two timestamps, and an optional OfflineSignature_. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | expires | sigtype | | +----+----+----+----+----+----+ + | transient_public_key | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | signature | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ expires :: 4 byte date length -> 4 bytes Seconds since the epoch, rolls over in 2106. sigtype :: 2 byte type of the transient_public_key length -> 2 bytes transient_public_key :: `SigningPublicKey` length -> As inferred from the sigtype signature :: `Signature` length -> As inferred from the sigtype of the signing public key in the `Destination` that preceded this offline signature. Signature of expires timestamp, transient sig type, and public key, by the destination public key, This section can, and should, be generated offline. {% endhighlight %} Notes ````` .. _struct-LeaseSet2Header: LeaseSet2Header --------------- Description ``````````` This is the common part of the LeaseSet2_ and MetaLeaseSet_. Supported as of 0.9.38; see proposal 123 for more information. Contents ```````` Contains the Destination_, two timestamps, and an optional OfflineSignature_. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | destination | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | published | expires | flags | +----+----+----+----+----+----+----+----+ | offline_signature (optional) | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ destination :: `Destination` length -> >= 387+ bytes published :: 4 byte date length -> 4 bytes Seconds since the epoch, rolls over in 2106. expires :: 2 byte date length -> 2 bytes Offset from published timestamp in seconds, 18.2 hours max flags :: 2 bytes Bit order: 15 14 ... 3 2 1 0 Bit 0: If 0, no offline keys; if 1, offline keys Bit 1: If 0, a standard published leaseset. If 1, an unpublished leaseset. Should not be flooded, published, or sent in response to a query. If this leaseset expires, do not query the netdb for a new one. Bits 15-2: set to 0 for compatibility with future uses offline_signature :: `OfflineSignature` length -> varies Optional, only present if bit 0 is set in the flags. {% endhighlight %} Notes ````` * Total size: 395 bytes minimum .. _struct-LeaseSet2: LeaseSet2 --------- Description ``````````` Contained in a I2NP DatabaseStore message of type 3. Supported as of 0.9.38; see proposal 123 for more information. Contains all of the currently authorized Lease2_ for a particular Destination_, the PublicKey_ to which garlic messages can be encrypted, and then the SigningPublicKey_ 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 ```````` LeaseSet2Header_, followed by a options, then one or more PublicKey_ for encryption, Integer_ specifying how many Lease2_ structures are in the set, followed by the actual Lease2_ structures and finally a Signature_ of the previous bytes signed by the Destination_'s SigningPrivateKey_ or the transient key. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | ls2_header | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | options | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ |numk| keytype0| keylen0 | | +----+----+----+----+----+ + | encryption_key_0 | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | keytypen| keylenn | | +----+----+----+----+ + | encryption_key_n | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | num| Lease2 0 | +----+ + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | Lease2($num-1) | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | signature | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ ls2header :: `LeaseSet2Header` length -> varies options :: `Mapping` length -> varies, 2 bytes minimum numk :: `Integer` length -> 1 byte Number of key types, key lengths, and `PublicKey`s to follow value: 1 <= numk <= max TBD keytype :: The encryption type of the `PublicKey` to follow. length -> 2 bytes keylen :: The length of the `PublicKey` to follow. Must match the specified length of the encryption type. length -> 2 bytes encryption_key :: `PublicKey` length -> 256 bytes num :: `Integer` length -> 1 byte Number of `Lease2`s to follow value: 0 <= num <= 16 leases :: [`Lease2`] length -> $num*40 bytes signature :: `Signature` length -> 40 bytes or as specified in destination's key certificate, or by the sigtype of the transient public key, if present in the header {% endhighlight %} 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 keys are used for end-to-end ElGamal/AES+SessionTag encryption [ELGAMAL-AES]_ (type 0) or other end-to-end encryption schemes. See proposals 123, 144, and 145. They are currently generated anew at every router startup they are not persistent. * The signature is over the data above, PREPENDED with the single byte containing the DatabaseStore type (3). * The signature may be verified using the signing public key of the destination, or the transient signing public key, if an offline signature is included in the leaseset2 header. * The key length is provided for each key, so that floodfills and clients may parse the structure even if not all encryption types are known or supported. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/LeaseSet.html .. _struct-MetaLease: MetaLease --------- Description ``````````` Defines the authorization for a particular tunnel to receive messages targeting a Destination_. Same as Lease2_ but with flags and cost instead of a tunnel id. Used by MetaLeaseSet_. Contained in a I2NP DatabaseStore message of type 7. Supported as of 0.9.38; see proposal 123 for more information. Contents ```````` SHA256 Hash_ of the RouterIdentity_ of the gateway router, then flags and cost, and finally a 4 byte end date. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | tunnel_gw | + + | | + + | | + + | | +----+----+----+----+----+----+----+----+ | flags |cost| end_date | +----+----+----+----+----+----+----+----+ tunnel_gw :: Hash of the `RouterIdentity` of the tunnel gateway, or the hash of another `MetaLeaseSet`. length -> 32 bytes flags :: 3 bytes of flags Bit order: 23 22 ... 3 2 1 0 Bits 3-0: Type of the entry. If 0, unknown. If 1, a `LeaseSet`. If 3, a `LeaseSet2`. If 5, a `MetaLeaseSet`. Bits 23-4: set to 0 for compatibility with future uses length -> 3 bytes cost :: 1 byte, 0-255. Lower value is higher priority. length -> 1 byte end_date :: 4 byte date length -> 4 bytes Seconds since the epoch, rolls over in 2106. {% endhighlight %} Notes ````` * Total size: 40 bytes JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/MetaLease.html .. _struct-MetaLeaseSet: MetaLeaseSet ------------ Description ``````````` Contained in a I2NP DatabaseStore message of type 7. Supported as of 0.9.38; see proposal 123 for more information. Contains all of the currently authorized MetaLease_ for a particular Destination_, the PublicKey_ to which garlic messages can be encrypted, and then the SigningPublicKey_ 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 ```````` LeaseSet2Header_, followed by a options, Integer_ specifying how many Lease2_ structures are in the set, followed by the actual Lease2_ structures and finally a Signature_ of the previous bytes signed by the Destination_'s SigningPrivateKey_ or the transient key. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | ls2_header | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | options | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | num| MetaLease 0 | +----+ + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | MetaLease($num-1) | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ |numr| | +----+ + | revocation_0 | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | revocation_n | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | signature | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ ls2header :: `LeaseSet2Header` length -> varies options :: `Mapping` length -> varies, 2 bytes minimum num :: `Integer` length -> 1 byte Number of `MetaLease`s to follow value: 1 <= num <= max TBD leases :: `MetaLease`s length -> $numr*40 bytes numr :: `Integer` length -> 1 byte Number of `Hash`es to follow value: 0 <= numr <= max TBD revocations :: [`Hash`] length -> $numr*32 bytes signature :: `Signature` length -> 40 bytes or as specified in destination's key certificate, or by the sigtype of the transient public key, if present in the header {% endhighlight %} 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 signature is over the data above, PREPENDED with the single byte containing the DatabaseStore type (7). * The signature may be verified using the signing public key of the destination, or the transient signing public key, if an offline signature is included in the leaseset2 header. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/MetaLeaseSet.html .. _struct-EncryptedLeaseSet: EncryptedLeaseSet ----------------- Description ``````````` Contained in a I2NP DatabaseStore message of type 5. Supported as of 0.9.38; see proposal 123 for more information. Contains all of the currently authorized MetaLease_ for a particular Destination_, the PublicKey_ to which garlic messages can be encrypted, and then the SigningPublicKey_ 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 ```````` LeaseSet2Header_, followed by a options, Integer_ specifying how many Lease2_ structures are in the set, followed by the actual Lease2_ structures and finally a Signature_ of the previous bytes signed by the Destination_'s SigningPrivateKey_ or the transient key. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | sigtype | | +----+----+ + | blinded_public_key | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | published | expires | flags | +----+----+----+----+----+----+----+----+ | offline_signature (optional) | + + | | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | len | | +----+----+ + | encrypted_data | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ | signature | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ sigtype :: A two byte signature type of the public key to follow length -> 2 bytes blinded_public_key :: `SigningPublicKey` length -> As inferred from the sigtype published :: 4 byte date length -> 4 bytes Seconds since the epoch, rolls over in 2106. expires :: 2 byte date length -> 2 bytes Offset from published timestamp in seconds, 18.2 hours max flags :: 2 bytes Bit order: 15 14 ... 3 2 1 0 Bit 0: If 0, no offline keys; if 1, offline keys Bit 1: If 0, a standard published leaseset. If 1, an unpublished leaseset. Should not be flooded, published, or sent in response to a query. If this leaseset expires, do not query the netdb for a new one. Bits 15-2: set to 0 for compatibility with future uses offline_signature :: `OfflineSignature` length -> varies Optional, only present if bit 0 is set in the flags. len :: `Integer` length -> 2 bytes length of encrypted_data to follow value: 1 <= num <= max TBD encrypted_data :: Data encrypted length -> len bytes signature :: `Signature` length -> 40 bytes or as specified in destination's key certificate, or by the sigtype of the transient public key, if present in the header {% endhighlight %} 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 signature is over the data above, PREPENDED with the single byte containing the DatabaseStore type (5). * The signature may be verified using the signing public key of the destination, or the transient signing public key, if an offline signature is included in the leaseset2 header. * Blinding and encryption schemes are TBD; see proposal 123. * This structure does not use the LeaseSet2Header_. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/EncryptedLeaseSet.html .. _struct-RouterAddress: 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. .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ |cost| expiration +----+----+----+----+----+----+----+----+ | transport_style | +----+----+----+----+-//-+----+----+----+ | | + + | options | ~ ~ ~ ~ | | +----+----+----+----+----+----+----+----+ cost :: `Integer` length -> 1 byte case 0 -> free case 255 -> expensive expiration :: `Date` (must be all zeros, see notes below) length -> 8 bytes case null -> never expires transport_style :: `String` length -> 1-256 bytes options :: `Mapping` {% endhighlight %} Notes ````` * Cost is typically 5 or 6 for SSU, and 10 or 11 for NTCP. * Expiration is currently unused, always null (all zeroes). As of release 0.9.3, the expiration is assumed zero and not stored, so any non-zero expiration will fail in the RouterInfo signature verification. Implementing expiration (or another use for these bytes) will be a backwards-incompatible change. Routers MUST set this field to all zeros. As of release 0.9.12, a non-zero expiration field is again recognized, however we must wait several releases to use this field, until the vast majority of the network recognizes it. * The following options, while not required, are standard and expected to be present in most router addresses: "host" (an IPv4 or IPv6 address or host name) and "port". JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/router/RouterAddress.html .. _struct-RouterInfo: 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 .. raw:: html {% highlight lang='dataspec' -%} +----+----+----+----+----+----+----+----+ | 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 The number of `RouterAddress`es to follow, 0-255 addresses :: [`RouterAddress`] length -> varies peer_size :: `Integer` length -> 1 byte The number of peer `Hash`es to follow, 0-255, unused, always zero value -> 0 options :: `Mapping` signature :: `Signature` length -> 40 bytes or as specified in router_ident's key certificate {% endhighlight %} 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. Certain implementations may require the list to be sorted so the signature is invariant. To be researched before enabling this feature. * The signature may be verified using the signing public key of the router_ident. * See the network database page [NETDB-ROUTERINFO]_ for standard options that are expected to be present in all router infos. * Very old routers required the addresses to be sorted by the SHA256 of their data so the signature is invariant. This is no longer required, and not worth implementing for backward compatibility. JavaDoc: http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/router/RouterInfo.html .. _struct-DeliveryInstructions: Delivery Instructions --------------------- Tunnel Message Delivery Instructions are defined in the Tunnel Message Specification [TUNNEL-DELIVERY]_. Garlic Message Delivery Instructions are defined in the I2NP Message Specification [GARLIC-DELIVERY]_. References ========== .. [ELGAMAL] {{ site_url('docs/how/cryptography', True) }}#elgamal .. [ELGAMAL-AES] {{ site_url('docs/how/elgamal-aes', True) }} .. [GARLIC-DELIVERY] {{ ctags_url('GarlicCloveDeliveryInstructions') }} .. [I2CP] {{ site_url('docs/protocol/i2cp', True) }} .. [I2NP] {{ site_url('docs/protocol/i2np', True) }} .. [NETDB-ROUTERINFO] {{ site_url('docs/how/network-database', True) }}#routerInfo .. [SSU] {{ site_url('docs/transport/ssu', True) }} .. [TUNNEL-DELIVERY] {{ ctags_url('TunnelMessageDeliveryInstructions') }}