Software Update Specification

Overview

Routers automatically check for updates by polling a signed news feed distributed through the I2P network. When a newer version is advertised, the router downloads a cryptographically signed update archive (.su3) and stages it for installation.
This system ensures authenticated, tamper-resistant, and multi-channel distribution of official releases.

As of I2P 2.10.0, the update system uses:

• RSA-4096 / SHA-512 signatures
• SU3 container format (replacing legacy SUD/SU2)
• Redundant mirrors: in-network HTTP, clearnet HTTPS, and BitTorrent

1. News Feed

Routers poll the signed Atom feed every few hours to discover new versions and security advisories.
The feed is signed and distributed as a .su3 file, which may include:

• <i2p:version> — new version number
• <i2p:minVersion> — minimum supported router version
• <i2p:minJavaVersion> — required minimum Java runtime
• <i2p:update> — lists multiple download mirrors (I2P, HTTPS, torrent)
• <i2p:revocations> — certificate revocation data
• <i2p:blocklist> — network-level blocklists for compromised peers

Feed Distribution

Routers prefer the I2P feed but can fall back to clearnet or torrent distribution if necessary.

2. File Formats

SU3 (Current Standard)

Introduced in 0.9.9, SU3 replaced the legacy SUD and SU2 formats.
Each file contains a header, payload, and trailing signature.

Header Structure

Signature Verification Steps

1. Parse header and identify signature algorithm.
2. Verify hash and signature using stored signer certificate.
3. Confirm signer not revoked.
4. Compare embedded version string with payload metadata.

Routers ship with trusted signer certificates (currently zzz and str4d) and reject any unsigned or revoked sources.

SU2 (Obsolete)

• Used .su2 extension with Pack200-compressed JARs.
• Removed after Java 14 deprecated Pack200 (JEP 367).
• Disabled in I2P 0.9.48+; now fully replaced by ZIP compression.

SUD (Legacy)

• Early DSA-SHA1-signed ZIP format (pre-0.9.9).
• No signer ID or header, limited integrity.
• Superseded due to weak cryptography and lack of version enforcement.

3. Update Workflow

3.1 Header Verification

Routers fetch only the SU3 header to verify the version string before downloading full files.
This prevents wasting bandwidth on stale mirrors or outdated versions.

3.2 Full Download

After verifying the header, the router downloads the complete .su3 file from:

• In-network eepsite mirrors (preferred)
• HTTPS clearnet mirrors (fallback)
• BitTorrent (optional peer-assisted distribution)

Downloads use standard I2PTunnel HTTP clients, with retries, timeout handling, and mirror fallback.

3.3 Signature Verification

Each downloaded file undergoes:

• Signature check: RSA-4096/SHA512 verification
• Version matching: Header vs. payload version check
• Downgrade prevention: Ensures update is newer than installed version

Invalid or mismatched files are discarded immediately.

3.4 Installation Staging

Once verified:

1. Extract ZIP contents to temporary directory
2. Remove files listed in deletelist.txt
3. Replace native libraries if lib/jbigi.jar is included
4. Copy signer certificates to ~/.i2p/certificates/
5. Move update to i2pupdate.zip for application on next restart

The update installs automatically on next startup or when “Install update now” is triggered manually.

4. File Management

deletelist.txt

A plaintext list of obsolete files to remove before unpacking new contents.

Rules:

• One path per line (relative paths only)
• Lines starting with # ignored
• .. and absolute paths rejected

Native Libraries

To prevent stale or mismatched native binaries:

• If lib/jbigi.jar exists, old .so or .dll files are deleted
• Ensures platform-specific libraries are freshly extracted

5. Certificate Management

Routers can receive new signer certificates through updates or news feed revocations.

• New .crt files are copied to the certificate directory.
• Revoked certificates are deleted before future verifications.
• Supports key rotation without requiring manual user intervention.

All updates are signed offline using air-gapped signing systems.
Private keys are never stored on build servers.

6. Developer Guidelines

Future releases will explore post-quantum signature integration (see Proposal 169) and reproducible builds.

7. Security Overview

8. Versioning

• Router: 2.10.0 (API 0.9.67)
• Semantic versioning with Major.Minor.Patch.
• Minimum version enforcement prevents unsafe upgrades.
• Supported Java: Java 8–17. Future 2.11.0+ will require Java 17+.