Issues with the previous .sud/.su2 format

• No magic number or flags
• No way to specify compression, pack200 or not, or signing algo
• 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)
• Signer not specified so verifier must try all known keys
• Signature-before-data format requires two passes to generate file

Goals

• Fix above problems
• Migrate to more secure signature algorithm
• Keep version info in same format and offset for compatibility with existing version checkers
• One-pass signature verification and file extraction

Specification

All unused fields must be set to 0 for compatibility with future versions.

Signature Details

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).

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.

Signature lengths for the various signature types are given in the [Signature] specification. Pad the signature with leading zeros if necessary. See the cryptography details page [CRYPTO-SIG] for parameters of the various signature types.

Notes

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.

All values are in network byte order (big endian).

For a python implementation of Raw RSA signatures compatible with Java "NONEwithRSA", see this Stack Overflow article: [Python]

SU3 Details

• SU3 Content Type: 1 (ROUTER UPDATE)
• SU3 File Type: 0 (ZIP)
• SU3 Version: The router version
• Jar and war files in the zip are no longer compressed with pack200 as documented above for "su2" files, because recent Java runtimes no longer support it.

Notes

• For releases, the SU3 version is the "base" router version, e.g. "0.9.20".
• For development builds, which are supported as of release 0.9.20, the SU3 version is the "full" router version, e.g. "0.9.20-5" or "0.9.20-5-rc". See RouterVersion.java [I2P-SRC].

Goals

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

Specification

1. The file must be named "i2pseeds.su3". As of 0.9.42, the requestor should append a query string "?netid=2" to the request URL, assuming the current network ID of 2. This may be used to prevent cross-network connections. Test networks should set a different network ID. See proposal 147 for details.
2. The file must be in the same directory as the router infos on the web server.
3. 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.

SU3 Details

• SU3 Content Type: 3 (RESEED)
• SU3 File Type: 0 (ZIP)
• SU3 Version: Seconds since the epoch, in ASCII (date +%s). Does NOT roll over in 2038 or 2106.
• Router info files in the zip file must be at the "top level". No directories are in the zip file.
• 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.

SU3 Details

• SU3 Content Type: 2 (PLUGIN)
• SU3 File Type: 0 (ZIP)
  • See the plugin specification [PLUGIN] for details.
• SU3 Version: The plugin version, must match that in plugin.config.
• Jar and war files in the zip should not be compressed with pack200 as documented above for "su2" files, as recent Java runtimes no longer support it.

Goals

• Signed news with strong signatures and trusted certificates
• Use su3 file format already used for updates, reseeding, and plugins
• Standard XML format for use with standard parsers
• Standard Atom format for use with standard feed readers and generators
• Sanitization and verification of HTML before displaying on console
• Suitable for easy implementation on Android and other platforms without an HTML console

SU3 Details

• SU3 Content Type: 4 (NEWS)
• SU3 File Type: 1 (XML) or 3 (XML.GZ)
• SU3 Version: Seconds since the epoch, in ASCII (date +%s). Does NOT roll over in 2038 or 2106.
• File Format: XML or gzipped XML, containing an [RFC-4287] (Atom) XML Feed. Charset must be UTF-8.

Specification

Atom <feed> Details:

The following <feed> elements are used:

<entry>

A news item. See below.

<i2p:release>

I2P update metadata. See below.

<i2p:revocations>

Certificate revocations. See below.

<i2p:blocklist>

Blocklist data. See below.

<updated>

Required

Timestamp for the feed (conforming to [RFC-4287] (Atom) section 3.3 and [RFC-3339].

Atom <entry> Details:

Each Atom <entry> in the news feed may be parsed and displayed in the router console. The following elements are used:

<author>

Optional

Containing:

<name>

The name of the entry author

<content>

Required

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.

<link>

Optional

Link for further information

<summary>

Optional

Short summary, suitable for a tooltip

<title>

Required

Title of the news entry

<updated>

Required

Timestamp for this entry (conforming to [RFC-4287] (Atom) section 3.3 and [RFC-3339]).

Atom <i2p:release> Details:

There must be at least one <i2p:release> entity in the feed. Each contains the following attributes and entities:

date (attribute)

Required

Timestamp for this entry (conforming to [RFC-4287] (Atom) section 3.3 and [RFC-3339].

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.

minJavaVersion (attribute)

If present, the minimum version of Java required to run the current version.

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.

<i2p:version>

Required

The latest current router version available.

<i2p:update>

An update file (one or more). It must contain at least one child.

type (attribute)

"sud", "su2", or "su3".

Must be unique across all <i2p:update> elements.

<i2p:clearnet>

Out-of-network direct download links (zero or more)

href (attribute)

A standard clearnet http link

<i2p:clearnetssl>

Out-of-network direct download links (zero or more)

href (attribute)

A standard clearnet https link

<i2p:torrent>

In-network magnet link

href (attribute)

A magnet link

<i2p:url>

In-network direct download links (zero or more)

href (attribute)

An in-network http .i2p link

Atom <i2p:revocations> Details:

This entity is optional and there is at most one <i2p:revocations> entity in the feed. This feature is supported as of release 0.9.26.

The <i2p:revocations> entity contains one or more <i2p:crl> entities. The <i2p:crl> entity contains the following attributes:

updated (attribute)

Required

Timestamp for this entry (conforming to [RFC-4287] (Atom) section 3.3 and [RFC-3339].

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.

id (attribute)

Required

A unique id for the creator of this CRL.

(entity content)

Required

A standard base 64 encoded Certificate Revocation List (CRL) with newlines, starting with the line '-----BEGIN X509 CRL-----' and ending with the line '-----END X509 CRL-----'. See [RFC-5280] for more information on CRLs.

Atom <i2p:blocklist> Details:

This entity is optional and there is at most one <i2p:blocklist> entity in the feed. This feature is scheduled for implementation in release 0.9.28. The specification below is preliminary and subject to change.

The <i2p:blocklist> entity contains one or more <i2p:block> or <i2p:unblock> entities, an "updated" entity, and "signer" and "sig" attributes:

signer (attribute)

Required

A unique id (UTF-8) for the public key used to sign this blocklist.

sig (attribute)

Required

A signature in the format code:b64sig, where code is the ASCII signature type number, and b64sig is the base 64 encoded signature (I2P alphabet). See below for specification of data to be signed.

<updated>

Required

Timestamp for the blocklist (conforming to [RFC-4287] (Atom) section 3.3 and [RFC-3339].

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.

<i2p:block>

Optional, multiple entities are allowed

A single entry, either a literal IPv4 or IPv6 address, or a 44-character base 64 router hash (I2P alphabet). IPv6 addresses may be in abbreviated format (containing "::"). Support for entries with a netmask, e.g. x.y.0.0/16, is optional. Support for host names is optional.

<i2p:unblock>

Optional, multiple entities are allowed

Same format as <i2p:block>.

Signature specification: To generate the data to be signed or verified, concatenate the following data in ASCII encoding: The updated string followed by a newline (ASCII 0x0a), then each block entry in the order received with a newline after each, then each unblock entry in the order received with a newline after each.