238 lines
8.0 KiB
HTML
238 lines
8.0 KiB
HTML
{% extends "global/layout.html" %}
|
|
{% block title %}{% trans %}I2P Software Update Specification{% endtrans %}{% endblock %}
|
|
{% block lastupdated %}{% trans %}July 2013{% endtrans %}{% endblock %}
|
|
{% block accuratefor %}0.9.7{% 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 %}News File Specification{% endtrans %}</h3>
|
|
<p>{% trans -%}
|
|
The news.xml file may contain the following elements:
|
|
{%- endtrans %}</p>
|
|
<pre>
|
|
<i2p.news date="$Date: 2010-01-22 00:00:00 $" />
|
|
<i2p.release version="0.7.14" date="2010/01/22" minVersion="0.6" />
|
|
</pre>
|
|
|
|
<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.
|
|
{%- 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.
|
|
{%- endtrans %}</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>{% 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 in the base $I2P installation directory.
|
|
{%- 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%.
|
|
{%- 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>{% trans %}New "su3" Update File Specification{% endtrans %}</h3>
|
|
|
|
<p>{% trans -%}
|
|
This specification is preliminary and is not yet implemented.
|
|
{%- endtrans %}</p>
|
|
|
|
<h4>{% trans %}Issues with existing .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>
|
|
</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 <td>unused
|
|
<tr><td>
|
|
9 <td>Signature type 0x00 = DSA-160, 0x01 = new algo
|
|
<tr><td>
|
|
10-11 <td>Signature length 40 (0x0028) = DSA-160
|
|
<tr><td>
|
|
12 <td>unused
|
|
<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
|
|
<tr><td>
|
|
15 <td>Signer ID length (in bytes not chars)
|
|
<tr><td>
|
|
16-23 <td>Compressed content length (not including header or sig)
|
|
<tr><td>
|
|
24 <td>unused
|
|
<tr><td>
|
|
25 <td>Compressed type 0x00 = zip
|
|
<tr><td>
|
|
26 <td>unused
|
|
<tr><td>
|
|
27 <td>Content type 0x00 = router w/o pack200, 0x01 = router w/ pack200, 0x02 = plugin
|
|
<tr><td>
|
|
28-39 <td>unused
|
|
<tr><td>
|
|
40-55+ <td>Version, UTF-8 padded with trailing 0x00, 16 bytes min.
|
|
<tr><td>
|
|
xx+ <td>ID of signer, (e.g. "zzz@mail.i2p") UTF-8, not padded
|
|
<tr><td>
|
|
xx+ <td>Compressed content, length and format specified in header
|
|
No requirement on the zip file comment since the sig covers the version.
|
|
<tr><td>
|
|
xx+ <td>Signature, length specified in header, covers everything starting at byte 0
|
|
</table>
|
|
|
|
<p>{% trans -%}
|
|
All unused fields must be set to 0 for compatibility with future versions.
|
|
{%- endtrans %}</p>
|
|
|
|
|
|
<h3>{% trans %}Future Work{% endtrans %}</h3>
|
|
<ul>
|
|
<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 is ongoing and should be completed by late 2013.
|
|
{%- 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.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
|
|
|
|
{% endblock %}
|