i2p-vectors

Warning

This entire project was written by GitHub Copilot; the human author only supervised.

Shell-first harness for generating reproducible I2P test vectors from the official Java reference implementation.

File tree

.
├── .gitignore
├── LICENSE
├── README.md
├── samples
│   ├── common-types.json
│   ├── crypto.json
│   ├── garlic.json
│   ├── structures.json
│   └── tunnel.json
├── scripts
│   ├── fetch-reference.sh
│   └── generate-vectors.sh
└── src
    └── VectorGenerator.java

Design

• Shell layer: scripts/generate-vectors.sh fetches pinned jars, compiles the Java glue with javac, and runs generation.
• Java layer: src/VectorGenerator.java uses public APIs from the upstream net.i2p:i2p and net.i2p:router jars to build ground-truth vectors.
• Build choice: plain javac/java keeps dependencies to the JDK and the reference jars only; a Gradle/Maven project would add unnecessary tooling for a single Java source file.
• Consumer harnesses: ./harnesses/libi2pd/README.md documents the C++ libi2pd validator.
• Consumer harnesses: ./harnesses/go-i2p/README.md documents the Go go-i2p validator.
• Consumer harnesses: ./harnesses/i2p-node/README.md documents the TypeScript i2p-node validator.
• Consumer harnesses: ./harnesses/emissary/README.md documents the Rust emissary validator.
• Consumer harnesses: ./harnesses/i2p-cs-renewed/README.md documents the C#/.NET i2p-cs-renewed validator.

Pinned reference version

• Reference implementation: Java I2P (geti2p.net)
• Maven artifacts:
  • net.i2p:i2p:2.12.0
  • net.i2p:router:2.12.0

The exact pinned version is also written into every generated JSON file under metadata.reference_version.

Prerequisites

• POSIX shell
• curl
• JDK with javac and java

Usage

Generate all categories into an output directory:

cd /tmp/workspace/go-i2p/i2p-vectors
./scripts/generate-vectors.sh /tmp/i2p-vectors-out

Generate only selected categories:

cd /tmp/workspace/go-i2p/i2p-vectors
./scripts/generate-vectors.sh /tmp/i2p-vectors-out crypto structures

Refresh the tracked sample output:

cd /tmp/workspace/go-i2p/i2p-vectors
./scripts/generate-vectors.sh /tmp/workspace/go-i2p/i2p-vectors/samples

Downloaded jars and compiled classes are cached under .cache/ and ignored by git.

Coverage

Current harness output:

• Cryptographic primitives
  • key generation + sign/verify for:
    • DSA-SHA1 (DSA_SHA1) — legacy
    • ECDSA P-256 (ECDSA_SHA256_P256) — intermediate
    • ECDSA P-384 (ECDSA_SHA384_P384) — intermediate
    • ECDSA P-521 (ECDSA_SHA512_P521) — intermediate
    • Ed25519 (EdDSA_SHA512_Ed25519) — modern
    • RedDSA Ed25519 (RedDSA_SHA512_Ed25519) — modern (used for LS2 signing / garlic blinding)
  • ElGamal encrypt/decrypt — legacy
  • X25519 Diffie-Hellman key agreement (ECIES_X25519) — modern (Curve25519 primitive used in ECIES-X25519-AEAD-Ratchet)
  • AES safe-encrypt/safe-decrypt
  • HKDF key derivation
• Data structures
  • Destination round-trip
  • LeaseSet round-trip + signature verification
  • RouterInfo round-trip + signature verification
• Common data types
  • I2P Base32 / Base64 round-trips
  • Certificate serialization
  • Mapping/property serialization
  • SHA-256 structure digests (included with structure vectors)
• Tunnel
  • TunnelDataMessage serialization round-trip
  • Single-hop layer transform: AES_ECB_decrypt(ivKey, IV) XOR data[992..1007] → IV; AES_CBC_decrypt(layerKey, IV, data) → payload
• Garlic
  • GarlicClove serialization round-trip (LOCAL delivery instructions + DataMessage payload)
  • ElGamal+AES session-key encrypted garlic message: 222-byte ElGamal key block [session_key | pre_IV | SHA-256(body)], AES-CBC body with IV = SHA-256(pre_IV)[0..15], full encrypt/decrypt round-trip verification

Determinism and reproducibility

The harness uses a fixed PRNG seed inside a minimal custom I2PAppContext so that vectors remain stable across runs, including signature algorithms that are normally randomized.

Each JSON file includes:

• descriptive vector name
• input parameters
• expected output
• brief validation comment
• pinned reference metadata

Sample output

Tracked sample files are committed in ./samples/. For example:

• ./samples/crypto.json
• ./samples/common-types.json
• ./samples/structures.json
• ./samples/tunnel.json
• ./samples/garlic.json