i2p.www/i2p2www/pages/site/docs/spec/updates.html

{% extends "global/layout.html" %}
{% block title %}{% trans %}I2P Software Update Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}December 2014{% endtrans %}{% endblock %}
{% block accuratefor %}0.9.17{% endblock %}
{% block content %}
<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.
{%- 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.
{%- endtrans %}</p>

<p>{% trans -%}
The router may optionally download, or download and install, the new version
if configured to do so.
{%- endtrans %}</p>

<h3>{% trans %}Old News File Specification{% endtrans %}</h3>
<p>{% trans -%}
This format is replaced by the su3 news format as of release 0.9.17.
{%- endtrans %}</p>
<p>{% trans -%}
The news.xml file may contain the following elements:
{%- 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>{% trans -%}
Parameters in the i2p.release entry are as follows.
All keys are case-insensitive. All values must be enclosed in double quotes.
{%- endtrans %}</p>

<ul>
<li>
date: The release date of the router version. Unused. Format not specified.
</li><li>
minJavaVersion: The minimum version of Java required to run the current version.
As of release 0.9.9.
</li><li>
minVersion: The minimum version of the router required to update to the current version.
If a router is older than this, the user must (manually?) update to an intermediate version first.
As of release 0.9.9.
</li><li>
su3Clearnet: One or more HTTP URLs where the .su3 update file may
be found on the clearnet (non-I2P).
Multiple URLs must be separated by a space or comma.
As of release 0.9.9.
</li><li>
su3SSL: One or more HTTPS URLs where the .su3 update file may
be found on the clearnet (non-I2P).
Multiple URLs must be separated by a space or comma.
As of release 0.9.9.
</li><li>
sudTorrent: The magnet link for the .sud (non-pack200) torrent of the update.
As of release 0.9.4.
</li><li>
su2Torrent: The magnet link for the .su2 (pack200) torrent of the update.
As of release 0.9.4.
</li><li>
su3Torrent: The magnet link for the .su3 (new format) torrent of the update.
As of release 0.9.9.
</li><li>
version: Required. The latest current router version available.
</li></ul>

<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.
NOTE: Due to parser limitations an entire element must be on a single line.
{%- endtrans %}</p>


<h3>{% trans %}Update File Specification{% endtrans %}</h3>
<p>{% trans -%}
As of release 0.9.9, the signed update file, named i2pupdate.su3, will
use the "su3" file format specified below.
Approved release signers will use 4096-bit RSA keys.
The X.509 public key certificates for these signers are distributed in the router installation packages.
The updates may contain certificates for new, approved signers, and/or contain
a list of certificates to delete for revocation.
{%- endtrans %}</p>


<h3>{% trans %}Old Update File Specification{% endtrans %}</h3>
<p>{% trans -%}
This format is obsolete as of release 0.9.9.
{%- endtrans %}</p>
<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>{% 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
{%- 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="{{ 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.
{%- endtrans %}</p>

<p>{% trans -%}
For version comparison purposes, version fields contain [0-9]*, field separators are
'-', '_', and '.', and all other characters are ignored.
{%- 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.
{%- endtrans %}</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.
This prevents the problem of update hosts that do not have the latest file.
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.
{%- endtrans %}</p>

<p>{% trans -%}
The zip file is extracted and copied to "i2pupdate.zip" in the I2P configuration directory (~/.i2p on Linux).
{%- 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&#37;.
{%- 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.
{%- 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:
{%- 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.
{%- endtrans %}</p>



<h3 id="su3">{% trans %}SU3 File Specification{% endtrans %}</h3>

<p>{% trans -%}
This specification is used for router updates as of release 0.9.9, reseed data as of release 0.9.14,
plugins as of release 0.9.15, and the news file as of release 0.9.17.
{%- endtrans %}</p>

<h4>{% trans %}Issues with the previous .sud/.su2 format:{% endtrans %}</h4>
<ul>
<li>{% trans -%}
No magic number or flags
{%- endtrans %}</li>
<li>{% trans -%}
No way to specify compression, pack200 or not, or signing algo
{%- endtrans %}</li>
<li>{% trans -%}
Version is not covered by signature, so it is enforced by requiring it
to be in the zip file comment (for router files) or in the plugin.config
file (for plugins)
{%- endtrans %}</li>
<li>{% trans -%}
Signer not specified so verifier must try all known keys
{%- endtrans %}</li>
<li>{% trans -%}
Signature-before-data format requires two passes to generate file
{%- endtrans %}</li>
</ul>


<h4>{% trans %}Goals:{% endtrans %}</h4>

<ul>
<li>{% trans -%}
Fix above problems
{%- endtrans %}</li>
<li>{% trans -%}
Migrate to more secure signature algorithm
{%- endtrans %}</li>
<li>{% trans -%}
Keep version info in same format and offset for compatibility with
existing version checkers
{%- endtrans %}</li>
<li>{% trans -%}
One-pass signature verification and file extraction
{%- endtrans %}</li>
</ul>

<h4>{% trans %}Specification:{% endtrans %}</h4>

<table><tr>
<th>Bytes<th>Contents
<tr><td>
0-5	<td>Magic number "I2Psu3"
<tr><td>
6	<td>unused = 0
<tr><td>
7	<td>su3 file format version = 0
<tr><td>
8-9	<td>Signature type
		<ul><li>0x0000 = DSA-SHA1
		</li><li>0x0001 = ECDSA-SHA256-P256
		</li><li>0x0002 = ECDSA-SHA384-P384
		</li><li>0x0003 = ECDSA-SHA512-P521
		</li><li>0x0004 = RSA-SHA256-2048
		</li><li>0x0005 = RSA-SHA384-3072
		</li><li>0x0006 = RSA-SHA512-4096
		</li></ul>
<tr><td>
10-11	<td>Signature length, e.g. 40 (0x0028) for DSA-SHA1.
            Must match that specified for the signature type on the
            <a href="{{ site_url('docs/spec/common-structures') }}#type_Signature">common structures page</a>.
<tr><td>
12	<td>unused = 0
<tr><td>
13	<td>Version length (in bytes not chars, including padding)
        must be at least 16 (0x10) for compatibility
<tr><td>
14	<td>unused = 0
<tr><td>
15	<td>Signer ID length (in bytes not chars)
<tr><td>
16-23	<td>Content length (not including header or sig)
<tr><td>
24	<td>unused = 0
<tr><td>
25	<td>File type
		<ul><li>0x00 = zip file
		</li><li>0x01 = xml file (as of 0.9.15)
		</li><li>0x02 = html file (as of 0.9.17)
		</li><li>0x03 = xml.gz file (as of 0.9.17)
		</li></ul>
<tr><td>
26	<td>unused = 0
<tr><td>
27	<td>Content type
		<ul><li>0x00 = unknown
		</li><li>0x01 = router update
		</li><li>0x02 = plugin or plugin update
		</li><li>0x03 = reseed data
		</li><li>0x04 = news feed (as of 0.9.15)
		</li></ul>
<tr><td>
28-39	<td>unused = 0
<tr><td>
40-55+	<td>Version, UTF-8 padded with trailing 0x00, 16 bytes minimum, length specified at byte 13.
            Do not append 0x00 bytes if the length is 16 or more.
<tr><td>
xx+	<td>ID of signer, (e.g. "zzz@mail.i2p") UTF-8, not padded, length specified at byte 15
<tr><td>
xx+	<td>Content: Length specified in header at bytes 16-23,
                     format specified in header at byte 25,
                     content specified in header at byte 27
<tr><td>
xx+	<td>Signature: Length is specified in header at bytes 10-11, covers everything starting at byte 0
</table>

<p>{% trans -%}
All unused fields must be set to 0 for compatibility with future versions.
{%- endtrans %}</p>


<h4>{% trans %}Signature Details{% endtrans %}</h4>
<p>
The signature covers the entire header starting at byte 0,
through the end of the content.
We use raw signatures. Take the hash of the data (using the hash type
implied by the signature type at bytes 8-9) and pass that
to a "raw" sign or verify function (e.g. "NONEwithRSA" in Java).
<p></p>
While signature verification and content extraction may be implemented in one pass,
an implementation must read and buffer the first 10 bytes to determine the hash type
before starting to verify.
<p></p>
Signature lengths for the various signature types are specified on the
<a href="{{ site_url('docs/spec/common-structures') }}#type_Signature">common structures page</a>.
Pad the signature with leading zeros if ncecessary.
See <a href="{{ site_url('docs/how/cryptography') }}#sig">the cryptography details page</a>
for parameters of the various signature types.
</p>



<h4>{% trans %}Notes{% endtrans %}</h4>
<p>
The content type specifies the trust domain.
For each content type, clients maintain a set of X.509 public key certificates for
parties trusted to sign that content.
Only certificates for the specified content type may be used.
The certificate is looked up by the ID of the signer.
Clients must verify that the content type is that expected for the application.
<p></p>
All values are in network byte order (big endian).
</p>




<h3>{% trans %}SU3 Router Update File Specification{% endtrans %}</h3>

<p><b>SU3 Details:</b></p>
<ul><li>
SU3 Content Type: 1 (ROUTER UPDATE)
</li><li>
SU3 File Type: 0 (ZIP)
</li><li>
SU3 Version: The router version
</li><li>
Jar and war files in the zip are compressed with pack200 as documented above for "su2" files.
If the client does not support pack200, it must download the update in a "sud" format.
</li></ul>




<h3>{% trans %}SU3 Reseed File Specification{% endtrans %}</h3>
<p>{% trans -%}
As of 0.9.14, reseed data is delivered in an "su3" file format.
{%- endtrans %}</p>

<h4>{% trans %}Goals:{% endtrans %}</h4>

<ul>
<li>{% trans -%}
Signed files with strong signatures and trusted certificates
to prevent man-in-the-middle attacks that could boot victims into a separate, untrusted network.
{%- endtrans %}</li>
<li>{% trans -%}
Use su3 file format already used for updates, reseeding, and plugins
{%- endtrans %}</li>
<li>{% trans -%}
Single compressed file to speed up reseeding, which was slow to fetch 200 files
{%- endtrans %}</li>
</ul>

<h4>{% trans %}Specification:{% endtrans %}</h4>

<p><ol>
<li>{% trans -%}
The file must be named "i2pseeds.su3".
{%- endtrans %}</li>
<li>{% trans -%}
The file must be in the same directory as the router infos on the web server.
{%- endtrans %}</li>
<li>{% trans -%}
A router will first try to fetch (index URL)/i2pseeds.su3; if that fails it will fetch the index URL
and then fetch the individual router info files found in the links.
{%- endtrans %}</li>
</ol></p>

<p><b>SU3 Details:</b></p>
<ul><li>
SU3 Content Type: 3 (RESEED)
</li><li>
SU3 File Type: 0 (ZIP)
</li><li>
SU3 Version: Seconds since the epoch, in ASCII (date +%s)
</li><li>
Router info files in the zip file must be at the "top level". No directories are in the zip file.
</li><li>
Router info files must be named "routerInfo-(44 character base 64 router hash).dat", as in the old reseed mechanism.
The I2P base 64 alphabet must be used.
</li></ul>




<h3>{% trans %}SU3 Plugin File Specification{% endtrans %}</h3>

<p>{% trans -%}
As of 0.9.15, plugins may be packaged in an "su3" file format.
{%- endtrans %}</p>

<p><b>SU3 Details:</b></p>
<ul><li>
SU3 Content Type: 2 (PLUGIN)
</li><li>
SU3 File Type: 0 (ZIP)
See <a href="plugin">the plugin specification</a> for details.
</li><li>
SU3 Version: The plugin version, must match that in plugin.config.
</li><li>
Jar and war files in the zip are compressed with pack200 as documented above for "su2" files.
</li></ul>






<h3>{% trans %}SU3 News File Specification{% endtrans %}</h3>
<p>{% trans -%}
As of 0.9.17, the news is delivered in an "su3" file format.
{%- endtrans %}</p>

<h4>{% trans %}Goals:{% endtrans %}</h4>

<ul>
<li>{% trans -%}
Signed news with strong signatures and trusted certificates
{%- endtrans %}</li>
<li>{% trans -%}
Use su3 file format already used for updates, reseeding, and plugins
{%- endtrans %}</li>
<li>{% trans -%}
Standard XML format for use with standard parsers
{%- endtrans %}</li>
<li>{% trans -%}
Standard Atom format for use with standard feed readers and generators
{%- endtrans %}</li>
<li>{% trans -%}
Sanitization and verification of HTML before displaying on console
{%- endtrans %}</li>
<li>{% trans -%}
Suitable for easy implementation on Android and other platforms without an HTML console
{%- endtrans %}</li>
</ul>

<h4>{% trans %}Specification:{% endtrans %}</h4>

<p><b>SU3 Details:</b></p>
<ul><li>
SU3 Content Type: 4 (NEWS)
</li><li>
SU3 File Type: 1 (XML) or 3 (XML.GZ)
</li><li>
SU3 Version: Seconds since the epoch, in ASCII (date +%s)
</li><li>
File Format: XML or gzipped XML, containing an <a href="http://tools.ietf.org/html/rfc4287">RFC 4287 (Atom) XML Feed</a>.
Charset must be UTF-8.
</li></ul>


<p><b>Atom &lt;feed&gt; Details:</b></p>
The following &lt;feed&gt; elements are used:
<ul><li>
&lt;entry&gt; A news item. See below.
</li><li>
&lt;i2p:release&gt; I2P update metadata. See below.
</li><li>
&lt;updated&gt; Timestamp for the feed (conforming to
<a href="http://tools.ietf.org/html/rfc4287">RFC 4287 (Atom) section 3.3</a> and
<a href="http://tools.ietf.org/html/rfc3339">RFC 3339</a>. (required)
</li></ul>


<p><b>Atom &lt;entry&gt; Details:</b></p>
Each Atom &lt;entry&gt; in the news feed may be parsed and displayed in the router console.
The following elements are used:
<ul><li>
&lt;author&gt; (optional) containing:
  <ul><li>
  &lt;name&gt; The name of the entry author
  </li></ul>
</li><li>
&lt;content&gt; Content, must be type="xhtml".
The XHTML will be sanitized with a whitelist of allowed elements
and a blacklist of disallowed attributes.
Clients may ignore an element, or the enclosing entry, or the entire feed
when a non-whitelisted element is encountered. (required)
</li><li>
&lt;link&gt; Link for further information (optional)
</li><li>
&lt;summary&gt; Short summary, suitable for a tooltip (optional)
</li><li>
&lt;title&gt; Title of the news entry (required)
</li><li>
&lt;updated&gt; Timestamp for this entry (conforming to
<a href="http://tools.ietf.org/html/rfc4287">RFC 4287 (Atom) section 3.3</a> and
<a href="http://tools.ietf.org/html/rfc3339">RFC 3339</a>. (required)
</li></ul>


<p><b>Atom &lt;i2p:release&gt; Details:</b></p>
There must be at least one &lt;i2p:release&gt; entity in the feed. Each contains the following attributes and entities:
<ul><li>
date (attribute): Timestamp for this entry (conforming to
<a href="http://tools.ietf.org/html/rfc4287">RFC 4287 (Atom) section 3.3</a> and
<a href="http://tools.ietf.org/html/rfc3339">RFC 3339</a>. (required)
The date also may be in truncated format yyyy-mm-dd (without the 'T'); this is the "full-date" format in RFC 3339.
In this format the time is assumed to be 00:00:00 UTC for any processing.
</li><li>
minJavaVersion (attribute): If present, the minimum version of Java required to run the current version.
</li><li>
minVersion (attribute):
If present, the minimum version of the router required to update to the current version.
If a router is older than this, the user must (manually?) update to an intermediate version first.
</li><li>
&lt;i2p:version&gt; Required. The latest current router version available.
</li><li>
&lt;i2p:update&gt; An update file (one or more). It must contain at least one child.
  <ul><li>
  type (attribute): "sud", "su2", or "su3". Must be unique across all &lt;i2p:update&gt; elements.
  </li><li>
  &lt;i2p:clearnet&gt; Out-of-network direct download links (zero or more)
    <ul><li>
    href (attribute): a standard clearnet http link
    </li></ul>
  </li><li>
  &lt;i2p:clearnetssl&gt; Out-of-network direct download links (zero or more)
    <ul><li>
    href (attribute): a standard clearnet https link
    </li></ul>
  </li><li>
  &lt;i2p:torrent&gt; In-network magnet link
    <ul><li>
    href (attribute): a magnet link
    </li></ul>
  </li><li>
  &lt;i2p:url&gt; In-network direct download links (zero or more)
    <ul><li>
    href (attribute): an in-network http .i2p link
    </li></ul>
  </li></ul>
</li></ul>



<h3>{% trans %}Future Work{% endtrans %}</h3>
<ul>
<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.
{%- endtrans %}</li>
</ul>



{% endblock %}