kytv/I2P_Website
1
0
Fork 0
forked from I2P_Developers/i2p.www
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Started adding translation tags to docs/spec/*

Browse Source
This commit is contained in:
str4d
2013-02-05 23:23:58 +00:00
parent 2def970aa8
commit 9b9145e185
5 changed files with 540 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
i2p2www/pages/site/docs/spec/blockfile.html
View File

@ -1,17 +1,17 @@
{% extends "global/layout.html" %}
{% block title %}I2P Blockfile Specification{% endblock %}
{% block lastupdated %}January 2012{% endblock %}
{% block title %}{% trans %}I2P Blockfile Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}January 2012{% endtrans %}{% endblock %}
{% block accuratefor %}0.8.12{% endblock %}
{% block content %}
<h2>
Blockfile and Hosts Database Specification
</h2>
<h3>Overview</h3>
<p>
<h2>{% trans %}Blockfile and Hosts Database Specification{% endtrans %}</h2>
<h3>{% trans %}Overview{% endtrans %}</h3>
<p>{% trans naming=site_url('docs/naming') -%}
This document specifies
the I2P blockfile file format
and the tables in the hostsdb.blockfile used by the Blockfile <a href="naming.html">Naming Service</a>.
</p><p>
and the tables in the hostsdb.blockfile used by the Blockfile <a href="{{ naming }}">Naming Service</a>.
{%- endtrans %}</p>
<p>{% trans -%}
The blockfile provides fast Destination lookup in a compact format. While the blockfile page overhead is substantial,
the destinations are stored in binary rather than in Base 64 as in the hosts.txt format.
In addition, the blockfile provides the capability of arbitrary metadata storage
@ -19,30 +19,37 @@ In addition, the blockfile provides the capability of arbitrary metadata storage
The metadata may be used in the future to provide advanced addressbook features.
The blockfile storage requirement is a modest increase over the hosts.txt format, and the blockfile provides
approximately 10x reduction in lookup times.
</p><p>
{%- endtrans %}</p>
<p>{% trans url='http://www.metanotion.net/software/sandbox/block.html' -%}
A blockfile is simply on-disk storage of multiple sorted maps (key-value pairs),
implemented as skiplists.
The blockfile format is adopted from the
<a href="http://www.metanotion.net/software/sandbox/block.html">Metanotion Blockfile Database</a>.
<a href="{{ url }}">Metanotion Blockfile Database</a>.
First we will define the file format, then the use of that format by the BlockfileNamingService.
{%- endtrans %}</p>
<h3>Blockfile Format</h3>
<p>
<h3>{% trans %}Blockfile Format{% endtrans %}</h3>
<p>{% trans -%}
The original blockfile spec was modified to add magic numbers to each page.
The file is structured in 1024-byte pages. Pages are numbered starting from 1.
The "superblock" is always at page 1, i.e. starting at byte 0 in the file.
The metaindex skiplist is always at page 2, i.e. starting at byte 1024 in the file.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
All 2-byte integer values are unsigned.
All 4-byte integer values (page numbers) are signed and negative values are illegal.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
The database is designed to be opened and accessed by a single thread.
The BlockfileNamingService provides synchronization.
</p>
{%- endtrans %}</p>
<p>
<p>{% trans -%}
Superblock format:
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-5 Magic number 0x3141de493250 ("1A" 0xde "I2P")
@ -55,9 +62,9 @@ Byte Contents
24-1023 unused
</pre>
<p>
<p>{% trans -%}
Skip list block page format:
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-7 Magic number 0x536b69704c697374 "SkipList"
@ -70,10 +77,10 @@ Byte Contents
</pre>
<p>
<p>{% trans -%}
Skip level block page format is as follows.
All levels have a span. Not all spans have levels.
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-7 Magic number 0x42534c6576656c73 "BSLevels"
@ -85,12 +92,12 @@ remaining bytes unused
</pre>
<p>
<p>{% trans -%}
Skip span block page format is as follows.
Key/value structures are sorted by key within each span and across all spans.
Key/value structures are sorted by key within each span.
Spans other than the first span may not be empty.
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-3 Magic number 0x5370616e "Span"
@ -102,9 +109,9 @@ Byte Contents
20-1023 key/value structures
</pre>
<p>
<p>{% trans -%}
Span Continuation block page format:
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-3 Magic number 0x434f4e54 "CONT"
@ -113,14 +120,14 @@ Byte Contents
</pre>
<p>
<p>{% trans -%}
Key/value structure format is as follows.
Key and value lengths must not be split across pages, i.e. all 4 bytes must be on the same page.
If there is not enough room the last 1-3 bytes of a page are unused and the lengths will
be at offset 8 in the continuation page.
Key and value data may be split across pages.
Max key and value lengths are 65535 bytes.
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-1 key length in bytes
@ -129,9 +136,9 @@ Byte Contents
value data
</pre>
<p>
<p>{% trans -%}
Free list block page format:
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-7 Magic number 0x2366724c69737423 "#frList#"
@ -141,32 +148,32 @@ Byte Contents
</pre>
<p>
<p>{% trans -%}
Free page block format:
</p>
{%- endtrans %}</p>
<pre>
Byte Contents
0-7 Magic number 0x7e2146524545217e "~!FREE!~"
8-1023 unused
</pre>
<p>
<p>{% trans -%}
The metaindex (located at page 2) is a mapping of US-ASCII strings to 4-byte integers.
The key is the name of the skiplist and the value is the page index of the skiplist.
</p>
{%- endtrans %}</p>
<h3>Blockfile Naming Service Tables</h3>
<p>
<h3>{% trans %}Blockfile Naming Service Tables{% endtrans %}</h3>
<p>{% trans -%}
The tables created and used by the BlockfileNamingService are as follows.
The maximum number of entries per span is 16.
</p>
{%- endtrans %}</p>
<h4>Properties Skiplist</h4>
<p>
"%%__INFO__%%" is the master database skiplist with String/Properties key/value entries containing only one entry:
</p>
<h4>{% trans %}Properties Skiplist{% endtrans %}</h4>
<p>{% trans -%}
"%%__INFO__%%" is the master database skiplist with String/Properties key/value entries containing only one entry:
{%- endtrans %}</p>
<pre>
"info": a Properties (UTF-8 String/String Map), serialized as a <a href="{{ site_url('docs/spec/common_structures') }}#type_Mapping">Mapping</a>:
"info": a Properties (UTF-8 String/String Map), serialized as a <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a>:
"version": "2"
"created": Java long time (ms)
"upgraded": Java long time (ms) (as of database version 2)
@ -174,14 +181,14 @@ The maximum number of entries per span is 16.
searched in-order for lookups. Almost always "privatehosts.txt,userhosts.txt,hosts.txt".
</pre>
<h4>Reverse Lookup Skiplist</h4>
<p>
<h4>{% trans %}Reverse Lookup Skiplist{% endtrans %}</h4>
<p>{% trans -%}
"%%__REVERSE__%%" is the reverse lookup skiplist with Integer/Properties key/value entries
(as of database version 2):
</p>
{%- endtrans %}</p>
<pre>
The skiplist keys are 4-byte Integers, the first 4 bytes of the hash of the Destination.
The skiplist values are each a Properties (a UTF-8 String/String Map) serialized as a <a href="{{ site_url('docs/spec/common_structures') }}#type_Mapping">Mapping</a>
The skiplist values are each a Properties (a UTF-8 String/String Map) serialized as a <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a>
There may be multiple entries in the properties, each one is a reverse mapping,
as there may be more than one hostname for a given destination,
or there could be collisions with the same first 4 bytes of the hash.
@ -189,28 +196,30 @@ The maximum number of entries per span is 16.
Each property value is the empty string.
</pre>
<h4>hosts.txt, userhosts.txt, and privatehosts.txt Skiplists</h4>
<p>
<h4>{% trans %}hosts.txt, userhosts.txt, and privatehosts.txt Skiplists{% endtrans %}</h4>
<p>{% trans -%}
For each host database, there is a skiplist containing
the hosts for that database.
The keys/values in these skiplists are as follows:
</p>
{%- endtrans %}</p>
<pre>
key: a UTF-8 String (the hostname)
value: a DestEntry, which is a Properties (a UTF-8 String/String Map) serialized as a <a href="{{ site_url('docs/spec/common_structures') }}#type_Mapping">Mapping</a>
followed by a binary Destination (serialized <a href="{{ site_url('docs/spec/common_structures') }}#struct_Destination">as usual</a>).
value: a DestEntry, which is a Properties (a UTF-8 String/String Map) serialized as a <a href="{{ site_url('docs/spec/common-structures') }}#type_Mapping">Mapping</a>
followed by a binary Destination (serialized <a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">as usual</a>).
</pre>
<p>
<p>{% trans -%}
The DestEntry Properties typically contains:
</p>
{%- endtrans %}</p>
<pre>
"a": The time added (Java long time in ms)
"s": The original source of the entry (typically a file name or subscription URL)
others: TBD
</pre>
<p>
<p>{% trans -%}
Hostname keys are stored in lower-case and always end in ".i2p".
{%- endtrans %}</p>
{% endblock %}

494
i2p2www/pages/site/docs/spec/common-structures.html
View File

@ -1,182 +1,184 @@
{% extends "global/layout.html" %}
{% block title %}Common structure Specification{% endblock %}
{% block lastupdated %}March 2012{% endblock %}
{% block title %}{% trans %}Common structure Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}March 2012{% endtrans %}{% endblock %}
{% block accuratefor %}0.8.13{% endblock %}
{% block content %}
<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="{{ site_url('docs/transport/ssu') }}">SSU</a>,
etc.
</p>
<h1>{% trans %}Data types Specification{% endtrans %}</h1>
<p>{% trans i2np=site_url('docs/protocol/i2np'),
i2cp=site_url('docs/protocol/i2cp'),
ssu=site_url('docs/transport/ssu') -%}
This document describes some data types common to all I2P protocols, like
<a href="{{ i2np }}">I2NP</a>, <a href="{{ i2cp }}">I2CP</a>,
<a href="{{ ssu }}">SSU</a>, etc.
{%- endtrans %}</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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
Represents a non-negative integer.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
1 to 8 bytes in network byte order representing an unsigned integer
{% endtrans %}</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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
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.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
8 byte <a href="#type_Integer">Integer</a>
{% endtrans %}</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.
Length limit is 255 bytes (not characters). Length may be 0.
</p>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
Represents a UTF-8 encoded string.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
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.
{% endtrans %}</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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
A boolean value, supporting null/unknown representation
0=false, 1=true, 2=unknown/null
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
1 byte <a href="#type_Integer">Integer</a>
{% endtrans %}</p>
<h4>{% trans %}Notes{% endtrans %}</h4>
<p>{% trans -%}
Deprecated - unused
{% endtrans %}</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
<a href="{{ site_url('docs/how/cryptography') }}#elgamal">the cryptography specification</a>.
</p>
<h4>Contents</h4>
<p>
256 bytes
</p>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans cryptography=site_url('docs/how/cryptography') -%}
This structure is used in ElGamal encryption, representing only the exponent, not the primes, which are constant and defined in
<a href="{{ cryptography }}#elgamal">the cryptography specification</a>.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
256 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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="{{ site_url('docs/how/cryptography') }}#elgamal">the cryptography specification</a>.
</p>
<h4>Contents</h4>
<p>
256 bytes
</p>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans cryptography=site_url('docs/how/cryptography') -%}
This structure is used in ElGamal decryption, representing only the exponent, not the primes which are constant and defined in
<a href="{{ cryptography }}#elgamal">the cryptography specification</a>.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
256 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
This structure is used for AES256 encryption and decryption.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
32 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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="{{ site_url('docs/how/cryptography') }}#DSA">DSA</a> signatures.
</p>
<h4>Contents</h4>
<p>
128 bytes
</p>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans cryptography=site_url('docs/how/cryptography') -%}
This structure is used for verifying <a href="{{ cryptography }}#DSA">DSA</a> signatures.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
128 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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="{{ site_url('docs/how/cryptography') }}#DSA">DSA</a> signatures.
</p>
<h4>Contents</h4>
<p>
20 bytes
</p>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans cryptography=site_url('docs/how/cryptography') -%}
This structure is used for creating <a href="{{ cryptography }}#DSA">DSA</a> signatures.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
20 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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="{{ site_url('docs/how/cryptography') }}#DSA">DSA</a> signature of some data.
</p>
<h4>Contents</h4>
<p>
40 bytes
</p>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans cryptography=site_url('docs/how/cryptography') -%}
This structure represents the <a href="{{ cryptography }}#DSA">DSA</a> signature of some data.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
40 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
Represents the SHA256 of some data.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
32 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
A random number
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
32 bytes
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
Defines an identifier that is unique to each router in a tunnel.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
4 byte <a href="#type_Integer">Integer</a>
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
A certificate is a container for various receipts or proof of works used throughout the I2P network.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
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.
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+--//
@ -200,31 +202,38 @@ payload :: data
{% endfilter %}
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<ul>
<li>
<li>{% trans -%}
For <a href="#struct_RouterIdentity">Router Identities</a>, the Certificate is always NULL, no others are currently implemented.
</li><li>
For <a href="{{ site_url('docs/spec/i2np') }}#struct_GarlicClove">Garlic Cloves</a>, the Certificate is always NULL, no others are currently implemented.
</li><li>
For <a href="{{ site_url('docs/spec/i2np') }}#msg_Garlic">Garlic Messages</a>, the Certificate is always NULL, no others are currently implemented.
</li><li>
{%- endtrans %}</li>
<li>{% trans i2np=site_url('docs/spec/i2np') -%}
For <a href="{{ i2np }}#struct_GarlicClove">Garlic Cloves</a>, the Certificate is always NULL, no others are currently implemented.
{%- endtrans %}</li>
<li>{% trans i2np=site_url('docs/spec/i2np') -%}
For <a href="{{ i2np }}#msg_Garlic">Garlic Messages</a>, the Certificate is always NULL, no others are currently implemented.
{%- endtrans %}</li>
<li>{% trans -%}
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>
{%- endtrans %}</li>
</ul>
<h4><a href="http://docs.i2p-projekt.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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
A set of key/value mappings or properties
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
A 2-byte size Integer followed by a series of String=String; pairs
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
@ -249,40 +258,51 @@ val string :: String
{% endfilter %}
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<ul>
<li>
<li>{% trans -%}
The encoding isn't optimal - we either need the '=' and ';' characters, or the string lengths, but not both
<li>
{%- endtrans %}</li>
<li>{% trans -%}
Some documentation says that the strings may not include '=' or ';' but this encoding supports them
<li>
{%- endtrans %}</li>
<li>{% trans -%}
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.
<li>
{%- endtrans %}</li>
<li>{% trans -%}
Mappings contained in I2NP messages (i.e. in a RouterAddress or RouterInfo)
must be sorted by key so that the signature will be invariant.
<li>
{%- endtrans %}</li>
<li>{% trans -%}
Key and value string length limits are 255 bytes (not characters) each, plus the length byte. Length byte may be 0.
<li>
{%- endtrans %}</li>
<li>{% trans -%}
Total length limit is 65535 bytes, plus the 2 byte size field, or 65537 total.
{%- endtrans %}</li>
</ul>
<h4><a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/DataHelper.html">Javadoc</a></h4>
<h1>Common structure specification</h1>
<h1>{% trans %}Common structure specification{% endtrans %}</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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
Defines the way to uniquely identify a particular router
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
<a href="#type_PublicKey">PublicKey</a> followed by <a href="#type_SigningPublicKey">SigningPublicKey</a> and then a <a href="#type_Certificate">Certificate</a>
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
@ -318,20 +338,22 @@ Total length: 387+ bytes
{% endfilter %}
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<p>{% trans -%}
The certificate for a RouterIdentity is currently unused and is always NULL.
{%- endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
A Destination defines a particular endpoint to which messages can be directed for secure delivery.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
<a href="#type_PublicKey">PublicKey</a> followed by a <a href="#type_SigningPublicKey">SigningPublicKey</a> and then a <a href="#type_Certificate">Certificate</a>
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
@ -370,15 +392,15 @@ Total length: 387+ bytes
<h4><a href="http://docs.i2p-projekt.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>
SHA256 <a href="#type_Hash">Hash</a> of the
<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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
Defines the authorization for a particular tunnel to receive messages targeting a <a href="#struct_Destination">Destination</a>.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
SHA256 <a href="#type_Hash">Hash</a> of the
<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>
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
@ -406,27 +428,29 @@ end_date :: Date
{% endfilter %}
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<ul>
<li>
<li>{% trans -%}
Total size: 44 bytes
</li></ul>
{%- endtrans %}</li>
</ul>
<h4><a href="http://docs.i2p-projekt.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 <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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
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 <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>.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
<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>
{%- endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
@ -514,35 +538,43 @@ signature :: Signature
{% endfilter %}
</pre>
<h4>Notes</h4>
<ul><li>
<h4>{% trans %}Notes{% endtrans %}</h4>
<ul>
<li>{% trans -%}
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?
</li><li>
The encryption key is used for end-to-end <a href="{{ site_url('docs/how/elgamalaes') }}">ElGamal/AES+SessionTag</a> encryption.
{%- endtrans %}</li>
<li>{% trans elgamalaes=site_url('docs/how/elgamal-aes') -%}
The encryption key is used for end-to-end <a href="{{ elgamalaes }}">ElGamal/AES+SessionTag</a> encryption.
It is currently generated anew at every router startup, it is not persistent.
</li><li>
{%- endtrans %}</li>
<li>{% trans -%}
The signature may be verified using the signing public key of the destination.
</li><li>
{%- endtrans %}</li>
<li>{% trans -%}
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.
</li></ul>
{%- endtrans %}</li>
</ul>
<h4><a href="http://docs.i2p-projekt.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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
This structure defines the means to contact a router through a transport protocol.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
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.
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+
@ -573,27 +605,30 @@ options :: Mapping
{% endfilter %}
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<ul>
<li>
<li>{% trans -%}
Cost is typically 5 or 6 for SSU, and 10 or 11 for NTCP.
</li><li>
{%- endtrans %}</li>
<li>{% trans -%}
Expiration is currently unused, always null (all zeroes))
</li></ul>
{%- endtrans %}</li>
</ul>
<h4><a href="http://docs.i2p-projekt.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>
<h4>{% trans %}Description{% endtrans %}</h4>
<p>{% trans -%}
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>.
{% endtrans %}</p>
<h4>{% trans %}Contents{% endtrans %}</h4>
<p>{% trans -%}
<a href="#struct_RouterIdentity">RouterIdentity</a> followed by the <a href="#type_Date">Date</a>, when the entry was published
{% endtrans %}</p>
<pre>
{% filter escape %}
+----+----+----+----+----+----+----+----+
@ -671,16 +706,21 @@ signature :: Signature
{% endfilter %}
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<p>{% trans -%}
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>
{% endtrans %}</p>
<p>{% trans -%}
The signature may be verified using the signing public key of the router_ident.
{% endtrans %}</p>
<h4><a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/RouterInfo.html">Javadoc</a></h4>
<h2 id="struct_DeliveryInstructions">Delivery Instructions</h2>
Defined in the <a href="{{ site_url('docs/spec/tunnel_message') }}#delivery">Tunnel Message Specification</a>.
<p>{% trans tunnelmessage=site_url('docs/spec/tunnel-message') -%}
Defined in the <a href="{{ tunnelmessage }}#delivery">Tunnel Message Specification</a>.
{% endtrans %}</p>
{% endblock %}

119
i2p2www/pages/site/docs/spec/configuration.html
View File

@ -1,104 +1,107 @@
{% extends "global/layout.html" %}
{% block title %}Configuration File Specification{% endblock %}
{% block lastupdated %}September 2012{% endblock %}
{% block title %}{% trans %}Configuration File Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}September 2012{% endtrans %}{% endblock %}
{% block accuratefor %}0.9.2{% endblock %}
{% block content %}
<h2>Overview</h2>
<p>
<h2>{% trans %}Overview{% endtrans %}</h2>
<p>{% trans -%}
This page provides a general specification of I2P configuration files,
used by the router and various applications.
It also gives an overview of the information contained in the various files,
and links to detailed documentation where available.
</p>
{%- endtrans %}</p>
<h2>General Format</h2>
<p>
<h2>{% trans %}General Format{% endtrans %}</h2>
<p>{% trans url='http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Properties.html#load%28java.io.InputStream%29' -%}
An I2P configuration file is formatted as specified in
<a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Properties.html#load%28java.io.InputStream%29">Java Properties</a>
<a href="{{ url }}">Java Properties</a>
with the following exceptions:
{%- endtrans %}</p>
<ul>
<li>Encoding must be UTF-8
<li>Does not use or recognize any escapes, including '\', so lines may not be continued
<li>'#' or ';' starts a comment, but '!' does not
<li>'#' starts a comment in any position but ';' must be in column 1 to start a comment
<li>Leading and trailing whitespace is not trimmed on keys
<li>Leading and trailing whitespace is trimmed on values
<li>'=' is the only key-termination character (not ':' or whitespace)
<li>Lines without '=' are ignored. It does not store the key with a value of ""
<li>As there are no escapes,
keys may not contain '#', '=', or '\n', or start with ';'
<li>As there are no escapes,
values may not contain '#' or '\n', or start or end with '\r' or whitespace
<li>{% trans %}Encoding must be UTF-8{% endtrans %}</li>
<li>{% trans %}Does not use or recognize any escapes, including '\', so lines may not be continued{% endtrans %}</li>
<li>{% trans %}'#' or ';' starts a comment, but '!' does not{% endtrans %}</li>
<li>{% trans %}'#' starts a comment in any position but ';' must be in column 1 to start a comment{% endtrans %}</li>
<li>{% trans %}Leading and trailing whitespace is not trimmed on keys{% endtrans %}</li>
<li>{% trans %}Leading and trailing whitespace is trimmed on values{% endtrans %}</li>
<li>{% trans %}'=' is the only key-termination character (not ':' or whitespace){% endtrans %}</li>
<li>{% trans %}Lines without '=' are ignored. It does not store the key with a value of ""{% endtrans %}</li>
<li>{% trans %}As there are no escapes, keys may not contain '#', '=', or '\n', or start with ';'{% endtrans %}</li>
<li>{% trans %}As there are no escapes, values may not contain '#' or '\n', or start or end with '\r' or whitespace{% endtrans %}</li>
</ul>
</p><p>
<p>{% trans -%}
The file need not be sorted, but most applications do sort by key when
writing to the file, for ease of reading and manual editing.
</p><p>
{%- endtrans %}</p>
<p>{% trans url='http://docs.i2p-projekt.de/javadoc/net/i2p/data/DataHelper.html',
commonstructures=site_url('docs/spec/common-structures') -%}
Reads and writes are implemented in
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/DataHelper.html">DataHelper loadProps() and storeProps()</a>.
<a href="{{ url }}">DataHelper loadProps() and storeProps()</a>.
Note that the file format is significantly different than the
serialized format for I2P protocols specified in
<a href="{{ site_url('docs/spec/common_structures') }}#type_Mapping">Mapping</a>.
</p>
<a href="{{ commonstructures }}#type_Mapping">Mapping</a>.
{%- endtrans %}</p>
<h2>Core library and router</h2>
<h2>{% trans %}Core library and router{% endtrans %}</h2>
<h3>Clients (clients.config)</h3>
<p>
<h3>{% trans %}Clients{% endtrans %} (clients.config)</h3>
<p>{% trans -%}
Configured via /configclients in the router console.
</p>
{%- endtrans %}</p>
<h3>Logger (logger.config)</h3>
<p>
<h3>{% trans %}Logger{% endtrans %} (logger.config)</h3>
<p>{% trans -%}
Configured via /configlogging in the router console.
</p>
{%- endtrans %}</p>
<h3>Individual Plugin (xxx/plugin.config)</h3>
<p>
See <a href="{{ site_url('docs/spec/plugin') }}">the plugin specification</a>.
</p>
<h3>{% trans %}Individual Plugin{% endtrans %} (xxx/plugin.config)</h3>
<p>{% trans pluginspec=site_url('docs/spec/plugin') -%}
See <a href="{{ pluginspec }}">the plugin specification</a>.
{%- endtrans %}</p>
<h3>Plugins (plugins.config)</h3>
<p>
Enable/disable for each installed plugin..
</p>
<h3>{% trans %}Plugins{% endtrans %} (plugins.config)</h3>
<p>{% trans -%}
Enable/disable for each installed plugin.
{%- endtrans %}</p>
<h3>Router (router.config)</h3>
<p>
<h3>{% trans %}Router{% endtrans %} (router.config)</h3>
<p>{% trans -%}
Configured via /configadvanced in the router console.
</p>
{%- endtrans %}</p>
<h2>Applications</h2>
<h2>{% trans %}Applications{% endtrans %}</h2>
<h3>Addressbook (addressbook/config.txt)</h3>
<p>
<h3>{% trans %}Addressbook{% endtrans %} (addressbook/config.txt)</h3>
<p>{% trans -%}
See documentation in SusiDNS.
</p>
{%- endtrans %}</p>
<h3>I2PSnark (i2psnark.config)</h3>
<p>
<p>{% trans -%}
Configured via the application gui.
</p>
{%- endtrans %}</p>
<h3>I2PTunnel (i2ptunnel.config)</h3>
<p>
<p>{% trans -%}
Configured via the /i2ptunnel application in the router console.
</p>
{%- endtrans %}</p>
<h3>Router Console</h3>
<p>
<h3>{% trans %}Router Console{% endtrans %}</h3>
<p>{% trans -%}
The router console uses the router.config file.
</p>
{%- endtrans %}</p>
<h3>SusiMail (susimail.config)</h3>
<p>
<p>{% trans -%}
See post on zzz.i2p.
</p>
{%- endtrans %}</p>
<!--
<h3>Systray (systray.config)</h3>
<p>
TBD
</p>
-->
{% endblock %}

133
i2p2www/pages/site/docs/spec/datagrams.html
View File

@ -1,100 +1,120 @@
{% extends "global/layout.html" %}
{% block title %}Datagram Specification{% endblock %}
{% block lastupdated %}August 2010{% endblock %}
{% block title %}{% trans %}Datagram Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}August 2010{% endtrans %}{% endblock %}
{% block accuratefor %}0.8{% endblock %}
{% block content %}
<h2>Datagram Overview</h2>
<p>Datagrams build upon the base <a href="i2cp.html">I2CP</a> to provide authenticated
<h2>{% trans %}Datagram Overview{% endtrans %}</h2>
<p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
Datagrams build upon the base <a href="{{ i2cp }}">I2CP</a> to provide authenticated
and repliable messages in a standard format. This lets applications reliably read
the "from" address out of a datagram and know that the address really sent the
message. This is necessary for some applications since the base I2P message is
completely raw - it has no "from" address (unlike IP packets). In addition, the
message and sender are authenticated by signing the payload.</p>
<p>
Datagrams, like <a href="{{ site_url('docs/api/streaming') }}">streaming library packets</a>,
message and sender are authenticated by signing the payload.
{%- endtrans %}</p>
<p>{% trans streaming=site_url('docs/api/streaming'),
transports=site_url('docs/transport') -%}
Datagrams, like <a href="{{ streaming }}">streaming library packets</a>,
are an application-level construct.
These protocols are independent of the low-level <a href="{{ site_url('docs/transport') }}">transports</a>;
These protocols are independent of the low-level <a href="{{ transports }}">transports</a>;
the protocols are converted to I2NP messages by the router, and
either protocol may be carried by either transport.
</p>
{%- endtrans %}</p>
<h2>Application Guide</h2>
<p>Applications written in Java may use the
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/datagram/package-summary.html">datagram API</a>,
<h2>{% trans %}Application Guide{% endtrans %}</h2>
<p>{% trans url='http://docs.i2p-projekt.de/javadoc/net/i2p/client/datagram/package-summary.html',
sam= site_url('docs/api/sam'),
socks=site_url('docs/api/socks') -%}
Applications written in Java may use the
<a href="{{ url }}">datagram API</a>,
while applications in other languages
can use <a href="{{ site_url('docs/api/sam') }}">SAM</a>'s datagram support.
There is also limited support in i2ptunnel in the <a href="{{ site_url('docs/api/socks') }}">SOCKS proxy</a>,
can use <a href="{{ sam }}">SAM</a>'s datagram support.
There is also limited support in i2ptunnel in the <a href="{{ socks }}">SOCKS proxy</a>,
the 'streamr' tunnel types, and udpTunnel classes.
</p>
{%- endtrans %}</p>
<h3>Datagram Length</h3>
<p>
<h3>{% trans %}Datagram Length{% endtrans %}</h3>
<p>{% trans -%}
The application designer should carefully consider the tradeoff of repliable vs. non-repliable
datagrams. Also, the datagram size will affect reliability, due to tunnel fragmentation into 1KB
tunnel messages. The more message fragments, the more likely that one of them will be dropped
by an intermediate hop. Messages larger than a few KB are not recommended.
</p>
<p>
{%- endtrans %}</p>
<p>{% trans elgamalaes=site_url('docs/how/elgamal-aes') -%}
Also note that the various overheads added by lower layers, in particular asymmetric
<a href="{{ site_url('docs/how/elgamalaes') }}">ElGamal/AES</a>, place a large burden on intermittent messages
<a href="{{ elgamalaes }}">ElGamal/AES</a>, place a large burden on intermittent messages
such as used by a Kademlia-over-UDP application. The implementations are currently tuned
for frequent traffic using the streaming library. There are a high number
of session tags delivered, and a short session tag lifetime, for example.
There are currently no configuration parameters available within I2CP to tune
the ElGamal Session Tag parameters.
</p>
{%- endtrans %}</p>
<h3>I2CP Protocol Number and Ports</h3>
<p>
<h3>{% trans %}I2CP Protocol Number and Ports{% endtrans %}</h3>
<p>{% trans -%}
The standard I2CP protocol number for datagrams is 17. Applications may or may not choose to set the
protocol in the I2CP header. It is not set by default.
It must be set to demultiplex datagram and streaming traffic received on the same Destination.
</p>
<p>
{%- endtrans %}</p>
<p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
As datagrams are not connection-oriented, the application may require
port numbers to correlate datagrams with particular peers or communications sessions,
as is traditional with UDP over IP.
Applications may add 'from' and 'to' ports to the I2CP (gzip) header as described in
the <a href="i2cp.html#format">I2CP page</a>.
</p>
<p>
the <a href="{{ i2cp }}#format">I2CP page</a>.
{%- endtrans %}</p>
<p>{% trans -%}
There is no method within the datagram API to specify whether it is non-repliable (raw)
or repliable. The application should be designed to expect the appropriate type.
The I2CP protocol number or port could also be used by the application to
indicate datagram type.
</p>
<p>
{%- endtrans %}</p>
<p>{% trans i2psession='http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSession.html',
i2psessionmuxed='http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSessionMuxedImpl.html' -%}
The protocols and ports may be set in I2CP's
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSession.html">I2PSession API</a>,
<a href="{{ i2psession }}">I2PSession API</a>,
as implemented in
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSessionMuxedImpl.html">I2PSessionMuxedImpl</a>.
</p>
<a href="{{ i2psessionmuxed }}">I2PSessionMuxedImpl</a>.
{%- endtrans %}</p>
<h3>Data Integrity</h3>
<h3>{% trans %}Data Integrity{% endtrans %}</h3>
<p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
Data integrity is assured by the gzip CRC-32 checksum implemented in
<a href="i2cp.html#format">the I2CP layer</a>.
<a href="{{ i2cp }}#format">the I2CP layer</a>.
There is no checksum field in the datagram protocol.
{%- endtrans %}</p>
<h3>Packet Encapsulation</h3>
<h3>{% trans %}Packet Encapsulation{% endtrans %}</h3>
<p>{% trans garlicrouting=site_url('docs/how/garlic-routing'),
i2cp=site_url('docs/protocol/i2cp'),
i2np=site_url('docs/protocol/i2np'),
tunnelmessage=site_url('docs/spec/tunnel-message') -%}
Each datagram is sent through I2P as a single message (or as an individual clove in a
<a href="{{ site_url('docs/how/garlicrouting') }}">Garlic Message</a>).
<a href="{{ garlicrouting }}">Garlic Message</a>).
Message encapsulation is implemented in the underlying
<a href="i2cp.html">I2CP</a>,
<a href="i2np.html">I2NP</a>, and
<a href="{{ site_url('docs/spec/tunnel_message') }}">tunnel message</a> layers.
<a href="{{ i2cp }}">I2CP</a>,
<a href="{{ i2np }}">I2NP</a>, and
<a href="{{ tunnelmessage }}">tunnel message</a> layers.
There is no packet delimiter mechanism or length field in the datagram protocol.
{%- endtrans %}</p>
<h2 id="spec">{% trans %}Specification{% endtrans %}</h2>
<h2 id="spec">Specification</h2>
<h3 id="raw">Non-Repliable Datagrams</h3>
<h3 id="raw">{% trans %}Non-Repliable Datagrams{% endtrans %}</h3>
<p>{% trans -%}
Non-repliable datagrams have no 'from' address and are not authenticated.
They are also called "raw" datagrams.
Strictly speaking, they are not "datagrams" at all, they are just raw data.
They are not handled by the datagram API.
However, SAM and the I2PTunnel classes support "raw datagrams".
{%- endtrans %}</p>
<h4>Format</h4>
<h4>{% trans %}Format{% endtrans %}</h4>
<pre>
+----+----+----+----+----//
| payload...
@ -104,16 +124,20 @@ However, SAM and the I2PTunnel classes support "raw datagrams".
Length: 0 - unlimited (see notes)
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<p>{% trans tunnelmessage=site_url('docs/spec/tunnel-message'),
transports=site_url('docs/transport') -%}
The practical length is limited by lower layers of protocols - the
<a href="{{ site_url('docs/spec/tunnel_message') }}#notes">tunnel message spec</a>
<a href="{{ tunnelmessage }}#notes">tunnel message spec</a>
limits messages to about 61.2 KB and the
<a href="{{ site_url('docs/transport') }}">transports</a>
<a href="{{ transports }}">transports</a>
currently limit messages to about 32 KB, although this may be raised in the future.
{%- endtrans %}</p>
<h3 id="repliable">Repliable Datagrams</h3>
<h3 id="repliable">{% trans %}Repliable Datagrams{% endtrans %}</h3>
<p>{% trans -%}
Repliable datagrams contain a 'from' address and a signature. These add 427 bytes of overhead.
{%- endtrans %}</p>
<h4>Format</h4>
<pre>
+----+----+----+----+----+----+----+----+
@ -142,11 +166,11 @@ Repliable datagrams contain a 'from' address and a signature. These add 427 byte
from :: a <a href="{{ site_url('docs/spec/common_structures') }}#type_Destination">Destination</a>
from :: a <a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>
length: 387+ bytes
The originator and signer of the datagram
signature :: a <a href="{{ site_url('docs/spec/common_structures') }}#type_Signature">Signature</a>
signature :: a <a href="{{ site_url('docs/spec/common-structures') }}#type_Signature">Signature</a>
length: 40 bytes
The <a href="{{ site_url('docs/how/cryptography') }}#DSA">DSA</a> signature of the SHA256 hash of the payload, which may be verified by the
DSA signing public key of the 'from' Destination
@ -159,12 +183,13 @@ Total length: Payload length + 427+
</pre>
<h4>Notes</h4>
<h4>{% trans %}Notes{% endtrans %}</h4>
<p>{% trans transports=site_url('docs/transport') -%}
The practical length is limited by lower layers of protocols - the
<a href="{{ site_url('docs/transport') }}">transports</a>
<a href="{{ transports }}">transports</a>
currently limit messages to about 32 KB, so the data length here is limited to about
31.5 KB.
{%- endtrans %}</p>

113
i2p2www/pages/site/docs/spec/updates.html
View File

@ -1,71 +1,85 @@
{% extends "global/layout.html" %}
{% block title %}I2P Software Update Specification{% endblock %}
{% block lastupdated %}November 2011{% endblock %}
{% block title %}{% trans %}I2P Software Update Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}November 2011{% endtrans %}{% endblock %}
{% block accuratefor %}0.8.12{% endblock %}
{% block content %}
<h3>Overview</h3>
<p>
<h3>{% trans %}Overview{% endtrans %}</h3>
<p>{% trans -%}
I2P uses a simple, yet secure, system for automated software update.
The router console periodically pulls a news file from a configurable I2P URL.
There is a hardcoded backup URL pointing to the project website, in case
the default project news host goes down.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
The contents of the news file are displayed on the home page of the router console.
In addition, the news file contains the most recent version number of the software.
If the version is higher than the router's version number, it will
display an indication to the user that an update is available.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
The router may optionally download, or download and install, the new version
if configured to do so.
</p>
{%- endtrans %}</p>
<h3>News File Specification</h3>
<p>
<h3>{% trans %}News File Specification{% endtrans %}</h3>
<p>{% trans -%}
The news.xml file may contain the following elements:
</p>
{%- endtrans %}</p>
<pre>
&lt;i2p.news date="$Date: 2010-01-22 00:00:00 $" /&gt;
&lt;i2p.release version="0.7.14" date="2010/01/22" minVersion="0.6" /&gt;
</pre>
<p>
<p>{% trans -%}
The elements may be included inside XML comments to prevent interpretation by browsers.
The i2p.release element and version are required. All others are optional and are
currently unused.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
The news source is trusted only to indicate that a new version is available.
It does not specify the URL of the update, the checksum, or any other information.
</p>
{%- endtrans %}</p>
<h3>Update File Specification</h3>
<p>
<h3>{% trans %}Update File Specification{% endtrans %}</h3>
<p>{% trans -%}
The signed update file, traditionally named i2pupdate.sud,
is simply a zip file with a prepended 56 byte header.
The header contains:
{%- endtrans %}</p>
<ul>
<li>
A 40-byte <a href="{{ site_url('docs/spec/common_structures') }}#type_signature">DSA signature</a>
</li><li>
<li>{% trans commonstructures=site_url('docs/spec/common-structures') -%}
A 40-byte <a href="{{ commonstructures }}#type_signature">DSA signature</a>
{%- endtrans %}</li>
<li>{% trans -%}
A 16-byte I2P version in UTF-8, padded with trailing zeroes if necessary
</li></ul>
</p><p>
{%- endtrans %}</li>
</ul>
<p>{% trans commonstructures=site_url('docs/spec/common-structures') -%}
The signature covers only the zip archive - not the prepended version.
The signature must match one of the <a href="{{ site_url('docs/spec/common_structures') }}#type_SigningPublicKey">DSA public keys</a> configured into the router,
The signature must match one of the <a href="{{ commonstructures }}#type_SigningPublicKey">DSA public keys</a> configured into the router,
which has a hardcoded default list of keys of the current project release managers.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
For version comparison purposes, version fields contain [0-9]*, field separators are
'-', '_', and '.', and all other characters are ignored.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
As of version 0.8.8, the version must also be specified as a zip file comment in UTF-8,
without the trailing zeroes.
The updating router verifes that the version in the header (not covered by the signature)
matches the version in the zip file comment, which is covered by the signature.
This prevents spoofing of the version number in the header.
</p>
{%- endtrans %}</p>
<h3>Download and Installation</h3>
<p>
<h3>{% trans %}Download and Installation{% endtrans %}</h3>
<p>{% trans -%}
The router first downloads the header of the update file from one in a configurable list of I2P URLs,
using the built-in HTTP client and proxy,
and checks that the version is newer.
@ -74,45 +88,58 @@ The router then downloads the full update file.
The router verifies that the update file version is newer before installation.
It also, of course, verifies the signature, and
verifes that the zip file comment matches the header version, as explained above.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
The zip file is extracted in the base $I2P installation directory.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
As of release 0.7.12, the router supports Pack200 decompression.
Files inside the zip archive with a .jar.pack or .war.pack suffix
are transparently decompressed to a .jar or .war file.
Update files containing .pack files are traditionally named with a '.su2' suffix.
Pack200 shrinks the update files by about 60%.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
As of release 0.8.7, the router will delete the libjbigi.so and libjcpuid.so files
if the zip archive contains a lib/jbigi.jar file, so that the new files will
be extracted from jbigi.jar.
</p><p>
{%- endtrans %}</p>
<p>{% trans -%}
As of release 0.8.12, if the zip archive contains a file deletelist.txt, the router will
delete the files listed there. The format is:
<ul><li>
One file name per line
</li><li>
All file names are relative to the installation directory; no absolute file names allowed, no files starting with ".."
</li><li>
Comments start with '#'
</li></ul>
{%- endtrans %}</p>
<ul>
<li>{% trans %}One file name per line{% endtrans %}</li>
<li>{% trans %}All file names are relative to the installation directory; no absolute file names allowed, no files starting with ".."{% endtrans %}</li>
<li>{% trans %}Comments start with '#'{% endtrans %}</li>
</ul>
<p>{% trans -%}
The router will then delete the deletelist.txt file.
</p>
{%- endtrans %}</p>
<h3>Future Work</h3>
<ul><li>
<h3>{% trans %}Future Work{% endtrans %}</h3>
<ul>
<li>{% trans -%}
When a new update file specification is defined, it should use a larger
DSA signature, and the signature should cover the version.
A file format version number might be a good idea too.
</li><li>
{%- endtrans %}</li>
<li>{% trans -%}
The network will eventually grow too large for update over HTTP.
The built-in BitTorrent client, i2psnark, may be used as a distributed update method.
This development effort was started in 2009 but is on hold until it is required.
</li><li>
{%- endtrans %}</li>
<li>{% trans -%}
The router update mechanism is part of the web router console.
There is currently no provision for updates of an embedded router lacking the router console.
</li></ul>
{%- endtrans %}</li>
</ul>