Files
i2p.www/www.i2p2/pages/common_structures_spec.html
2010-09-15 14:40:36 +00:00

668 lines
20 KiB
HTML

{% extends "_layout.html" %}
{% block title %}Common structure Specification{% endblock %}
{% block content %}
Updated August 2010, current as of router version 0.8
<h1>Data types Specification</h1>
<p>
This document describes some data types common to all I2P protocols, like
<a href="i2np.html">I2NP</a>,
<a href="i2cp.html">I2CP</a>,
<a href="udp.html">SSU</a>,
etc.
</p>
<h2 id="type_Integer">Integer</h2>
<h4>Description</h4>
<p>
Represents a non-negative integer.
</p>
<h4>Contents</h4>
<p>
1 to 8 bytes in network byte order representing an unsigned integer
</p>
<h2 id="type_Date">Date</h2>
<h4>Description</h4>
<p>
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.
</p>
<h4>Contents</h4>
<p>
8 byte <a href="#type_Integer">Integer</a>
</p>
<h2 id="type_String">String</h2>
<h4>Description</h4>
<p>
Represents a UTF-8 encoded string.
</p>
<h4>Contents</h4>
<p>
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
</p>
<h2 id="type_Boolean">Boolean</h2>
<h4>Description</h4>
<p>
A boolean value, supporting null/unknown representation
0=false, 1=true, 2=unknown/null
</p>
<h4>Contents</h4>
<p>
1 byte <a href="#type_Integer">Integer</a>
</p>
<h4>Notes</h4>
Deprecated - unused
<h2 id="type_PublicKey">PublicKey</h2>
<h4>Description</h4>
<p>
This structure is used in ElGamal encryption, representing only the exponent, not the primes, which are constant and defined in
<a href="how_cryptography.html#elgamal">the cryptography specification</a>.
</p>
<h4>Contents</h4>
<p>
256 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/PublicKey.html">Javadoc</a></h4>
<h2 id="type_PrivateKey">PrivateKey</h2>
<h4>Description</h4>
<p>
This structure is used in ElGamal decryption, representing only the exponent, not the primes which are constant and defined in
<a href="how_cryptography.html#elgamal">the cryptography specification</a>.
</p>
<h4>Contents</h4>
<p>
256 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/PrivateKey.html">Javadoc</a></h4>
<h2 id="type_SessionKey">SessionKey</h2>
<h4>Description</h4>
<p>
This structure is used for AES256 encryption and decryption.
</p>
<h4>Contents</h4>
<p>
32 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/SessionKey.html">Javadoc</a></h4>
<h2 id="type_SigningPublicKey">SigningPublicKey</h2>
<h4>Description</h4>
<p>
This structure is used for verifying <a href="how_cryptography.html#DSA">DSA</a> signatures.
</p>
<h4>Contents</h4>
<p>
128 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/SigningPublicKey.html">Javadoc</a></h4>
<h2 id="type_SigningPrivateKey">SigningPrivateKey</h2>
<h4>Description</h4>
<p>
This structure is used for creating <a href="how_cryptography.html#DSA">DSA</a> signatures.
</p>
<h4>Contents</h4>
<p>
20 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/SigningPrivateKey.html">Javadoc</a></h4>
<h2 id="type_Signature">Signature</h2>
<h4>Description</h4>
<p>
This structure represents the <a href="how_cryptography.html#DSA">DSA</a> signature of some data.
</p>
<h4>Contents</h4>
<p>
40 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/Signature.html">Javadoc</a></h4>
<h2 id="type_Hash">Hash</h2>
<h4>Description</h4>
<p>
Represents the SHA256 of some data.
</p>
<h4>Contents</h4>
<p>
32 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/Hash.html">Javadoc</a></h4>
<h2 id="type_SessionTag">Session Tag</h2>
<h4>Description</h4>
<p>
A random number
</p>
<h4>Contents</h4>
<p>
32 bytes
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/SessionTag.html">Javadoc</a></h4>
<h2 id="type_TunnelId">TunnelId</h2>
<h4>Description</h4>
<p>
Defines an identifier that is unique to each router in a tunnel.
</p>
<h4>Contents</h4>
<p>
4 byte <a href="#type_Integer">Integer</a>
</p>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/TunnelID.html">Javadoc</a></h4>
<h2 id="type_Certificate">Certificate</h2>
<h4>Description</h4>
<p>
A certificate is a container for various receipts or proof of works used throughout the I2P network.
</p>
<h4>Contents</h4>
<p>
1 byte <a href="#type_Integer">Integer</a> specifying certificate type, followed by a 2 <a href="#type_Integer">Integer</a> specifying the size of the certificate payload, then that many bytes.
</p>
<pre>
{% filter escape %}
+----+----+----+----+----+--//
|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
{% endfilter %}
</pre>
<h4>Notes</h4>
<ul>
<li>
For <a href="#struct_RouterIdentity">Router Identities</a>, the Certificate is always NULL, no others are currently implemented.
</li><li>
For <a href="i2np_spec.html#struct_GarlicClove">Garlic Cloves</a>, the Certificate is always NULL, no others are currently implemented.
</li><li>
For <a href="i2np_spec.html#msg_Garlic">Garlic Messages</a>, the Certificate is always NULL, no others are currently implemented.
</li><li>
For <a href="#struct_Destination">Destinations</a>, the Certificate may be non-NULL,
however non-NULL certs are not widely used, and any checking is left to the application-level.
</li></ul>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/Certificate.html">Javadoc</a></h4>
<h2 id="type_Mapping">Mapping</h2>
<h4>Description</h4>
<p>
A set of key/value mappings or properties
</p>
<h4>Contents</h4>
<p>
A 2-byte size Integer followed by a series of String=String; pairs
</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| 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 ';'
{% endfilter %}
</pre>
<h4>Notes</h4>
<ul>
<li>
The encoding isn't optimal - we either need the '=' and ';' characters, or the string lengths, but not both
<li>
Some documentation says that the strings may not include '=' or ';' but this encoding supports them
<li>
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.
</ul>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/DataHelper.html">Javadoc</a></h4>
<h1>Common structure specification</h1>
<h2 id="struct_RouterIdentity">RouterIdentity</h2>
<h4>Description</h4>
<p>
Defines the way to uniquely identify a particular router
</p>
<h4>Contents</h4>
<p>
<a href="#type_PublicKey">PublicKey</a> followed by <a href="#type_SigningPublicKey">SigningPublicKey</a> and then a <a href="#type_Certificate">Certificate</a>
</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| 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
{% endfilter %}
</pre>
<h4>Notes</h4>
The certificate for a RouterIdentity is currently unused and is always NULL.
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/RouterIdentity.html">Javadoc</a></h4>
<h2 id="struct_Destination">Destination</h2>
<h4>Description</h4>
<p>
A Destination defines a particular endpoint to which messages can be directed for secure delivery.
</p>
<h4>Contents</h4>
<p>
<a href="#type_PublicKey">PublicKey</a> followed by a <a href="#type_SigningPublicKey">SigningPublicKey</a> and then a <a href="#type_Certificate">Certificate</a>
</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| 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
{% endfilter %}
</pre>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/Destination.html">Javadoc</a></h4>
<h2 id="struct_Lease">Lease</h2>
<h4>Description</h4>
<p>
Defines the authorization for a particular tunnel to receive messages targeting a <a href="#struct_Destination">Destination</a>.
</p>
<h4>Contents</h4>
<p>
<a href="#struct_RouterIdentity">RouterIdentity</a> of the gateway router, then the <a href="#type_TunnelId">TunnelId</a>, and finally an end <a href="#type_Date">Date</a>
</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| tunnel_gw |
+ +
| |
~ ~
~ ~
| |
+ +----+----+----+----+
| | tunnel_id |
+----+----+----+----+----+----+----+----+
| end_date |
+----+----+----+----+----+----+----+----+
tunnel_gw :: RouterIdentity of the tunnel gateway
length -> >= 387 bytes
tunnel_id :: TunnelId
length -> 4 bytes
end_date :: Date
length -> 8 bytes
{% endfilter %}
</pre>
<h4>Notes</h4>
<ul>
<li>
Could this be optimized to include the Hash of the Router Identity instead of the full Router Identtity?
</li></ul>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/Lease.html">Javadoc</a></h4>
<h2 id="struct_LeaseSet">LeaseSet</h2>
<h4>Description</h4>
<p>
Contains all of the currently authorized <a href="#struct_Lease">Lease</a>s for a particular <a href="#struct_Destination">Destination</a>, the <a href="#type_PublicKey">PublicKey</a> to which garlic messages can be encrypted,
and then the the <a href="#type_SigningPublicKey">public key</a> that can be used to revoke this particular version of the structure. The <a href="#struct_LeaseSet">LeaseSet</a> is one of the two structures stored in the network database(
the other being <a href="#struct_RouterInfo">RouterInfo</a>), and is keyed under the SHA256 of the contained <a href="#struct_Destination">Destination</a>.
</p>
<h4>Contents</h4>
<p>
<a href="#struct_Destination">Destination</a>, followed by a <a href="#type_PublicKey">PublicKey</a> for encryption, then a <a href="#type_SigningPublicKey">SigningPublicKey</a> which can be used to revoke this version of the <a href="#struct_LeaseSet">LeaseSet</a>,
then a 1 byte <a href="#type_Integer">Integer</a> specifying how many <a href="#struct_Lease">Lease</a> structures are in the set, followed by the actual <a href="#struct_Lease">Lease</a> structures and finally a <a href="#type_Signature">Signature</a> of the previous
bytes signed by the <a href="#struct_Destination">Destination's</a> <a href="#type_SigningPrivateKey">SigningPrivateKey</a>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| 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*399 bytes
signature :: Signature
length -> 40 bytes
{% endfilter %}
</pre>
<h4>Notes</h4>
<p>
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.
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/LeaseSet.html">Javadoc</a></h4>
<h2 id="struct_RouterAddress">RouterAddress</h2>
<h4>Description</h4>
<p>
This structure defines the means to contact a router through a transport protocol.
</p>
<h4>Contents</h4>
<p>
1 byte <a href="#type_Integer">Integer</a> defining the relative cost of using the address, where 0 is free and 255 is expensive, followed by the expiration <a href="#type_Date">Date</a> after which the address should not be used, or if null, the address never expires.
After that comes a <a href="#type_String">String</a> defining the transport protocol this router address uses. Finally there is a <a href="#type_Mapping">Mapping</a> containing all of the transport specific options necessary to establish the connection, such as
IP address, port number, email address, URL, etc.
</p>
<pre>
{% filter escape %}
+----+
|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
{% endfilter %}
</pre>
<h4>Notes</h4>
<ul>
<li>
Cost is typically 5 or 6 for SSU, and 10 or 11 for NTCP.
</li><li>
Expiration is currently unused, always null (all zeroes))
</li></ul>
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/RouterAddress.html">Javadoc</a></h4>
<h2 id="struct_RouterInfo">RouterInfo</h2>
<h4>Description</h4>
<p>
Defines all of the data that a router wants to publish for the network to see. The <a href="#struct_RouterInfo">RouterInfo</a> is one of two structures stored in the network database(the other being <a href="#struct_LeaseSet">LeaseSet</a>, and is keyed under the SHA256 of
the contained <a href="#struct_RouterIdentity">RouterIdentity</a>.
</p>
<h4>Contents</h4>
<p>
<a href="#struct_RouterIdentity">RouterIdentity</a> followed by the <a href="#type_Date">Date</a>, when the entry was published
</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
| 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
{% endfilter %}
</pre>
<h4>Notes</h4>
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.
<p>
The signature may be verified using the signing public key of the router_ident.
<h4><a href="http://docs.i2p2.de/javadoc/net/i2p/data/RouterInfo.html">Javadoc</a></h4>
<h2 id="struct_DeliveryInstructions">Delivery Instructions</h2>
Defined in the <a href="tunnel_message_spec.html#delivery">Tunnel Message Specification</a>.
{% endblock %}