509 lines
16 KiB
HTML
509 lines
16 KiB
HTML
{% extends "_layout.html" %}
|
|
{% block title %}Common structure Specification{% endblock %}
|
|
{% block content %}
|
|
<h1>Data types Specification</h1>
|
|
<p>
|
|
This document describes some data types common to all I2P-protocols, like I2NP, I2CP, NTCP, etc.
|
|
</p>
|
|
|
|
<h2 id="type_Integer">Integer</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
Represents a nonnegative integer.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
1 or more 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>
|
|
|
|
<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 the appropiate spec.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
256 byte <a href="#type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<h2 id="type_PrivateKey">PrivateKey</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
This structure is used in ElGama decryption, representing only the exponent, not the primes which are constant and defined in the appropiate spec.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
256 byte <a href="#type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<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 byte <a href="#type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<h2 id="type_SigningPublicKey">SigningPublicKey</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
This structure is used for verifying DSA signatures.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
128 byte <a href="#type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<h2 id="type_SigningPrivateKey">SigningPrivateKey</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
This structure is used for creating DSA signatures.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
20 byte <a href="#type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<h2 id="type_Signature">Signature</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
This structure represents the DSA signature of some data.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
40 byte <a href="#type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<h2 id="type_Hash">Hash</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
Represents the SHA256 of some data.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
32 bytes
|
|
</p>
|
|
|
|
<h2 id="type_TunnelId">TunnelId</h2>
|
|
<h4>Description</h4>
|
|
<p>
|
|
Defines an identifier that is unique within a particular set of routers for a tunnel.
|
|
</p>
|
|
<h4>Contents</h4>
|
|
<p>
|
|
4 byte <a href="type_Integer">Integer</a>
|
|
</p>
|
|
|
|
<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>
|
|
|
|
|
|
|
|
<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> entangled with the <a href="#type_PublicKey">PublicKey</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
|
|
|
|
{% endfilter %}
|
|
</pre>
|
|
|
|
<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> entangled with the <a href="#type_PublicKey">PublicKey</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
|
|
{% endfilter %}
|
|
</pre>
|
|
|
|
<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 then a start <a href="#type_Date">Date</a> and finally an end <a href="#type_Date">Date</a>
|
|
</p>
|
|
<pre>
|
|
{% filter escape %}
|
|
+----+----+----+----+----+----+----+----+
|
|
| tunnel_gw |
|
|
+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+ +----+----+----+----+
|
|
| | tunnel_id |
|
|
+----+----+----+----+----+----+----+----+
|
|
| start_date |
|
|
+----+----+----+----+----+----+----+----+
|
|
| end_date |
|
|
+----+----+----+----+----+----+----+----+
|
|
|
|
tunnel_gw :: RouterIdentity
|
|
length -> >= 387 bytes
|
|
|
|
tunnel_id :: TunnelId
|
|
length -> 4 bytes
|
|
|
|
start_date :: Date
|
|
length -> 8 bytes
|
|
|
|
end_date :: Date
|
|
length -> 8 bytes
|
|
{% endfilter %}
|
|
</pre>
|
|
|
|
<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>
|
|
<p/>
|
|
<pre>
|
|
{% filter escape %}
|
|
+----+----+----+----+----+----+----+----+
|
|
| destination |
|
|
+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| encryption_key |
|
|
+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| signing_key |
|
|
+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
|num | Lease 0 |
|
|
+----+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| Lease 1 |
|
|
+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| Lease ($num-1) |
|
|
+ +
|
|
| |
|
|
~ ~
|
|
|
|
~ ~
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
| signature |
|
|
+ +
|
|
| |
|
|
+ +
|
|
| |
|
|
+ +
|
|
| |
|
|
+ +
|
|
| |
|
|
+----+----+----+----+----+----+----+----+
|
|
|
|
destination :: Destination
|
|
length -> >= 397 bytes
|
|
|
|
encryption_key :: PublicKey
|
|
length -> 256 bytes
|
|
|
|
signing_key :: SigningPublicKey
|
|
length -> 128 bytes
|
|
|
|
num :: Integer
|
|
length -> 1 byte
|
|
|
|
leases :: [Lease]
|
|
length -> >= $num*407 bytes
|
|
|
|
signature :: Signature
|
|
length -> 40 bytes
|
|
|
|
{% endfilter %}
|
|
</pre>
|
|
|
|
|
|
|
|
<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>
|
|
|
|
<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 |
|
|
+----+----+----+----+-//-+----+----+----+
|
|
|
|
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
|
|
{% endfilter %}
|
|
</pre>
|
|
|
|
{% endblock %}
|