go-i2p/go-i2p

A pure Go implementation of the I2P router.
📝 1608 commits
📅 Last updated: April 2, 2026
📜 MIT License

README

go-i2p

A pure Go implementation of the I2P router.

Status

go-i2p is in active development. We recently completed several significant milestones including:

  • Complete I2CP Protocol Server: Full session lifecycle management, message routing, and client support
  • End-to-End Message Routing: Complete message routing system connecting I2CP clients through tunnels to other destinations with garlic encryption
  • Tunnel System: Automatic tunnel building, pool management, and cryptographic processing
  • Transport Layer: Full NTCP2 implementation with session management

The core router functionality is now operational. We have tested functionality using i2psnark-standalone against our I2CP API server. Basic compatibility is available. We are now focused application layer protocols. We have a mostly-complete I2CP client, a prototype of a Streaming library, and a pretty boring Datagrams library, all of which are requirements for SAMv3.3(which we also have), which is what all our applications use. Refining these components and making them production-ready is the immediate goal. After the turn of the year, we will return our focus to transports by implementing SSU2.

The current release(0.1.4 and earlier) have literally hundreds of bugs pending resolution in 0.1.5. Probably hold off until I release it in a few days.

go-i2p’s network presence is HIGHLY DISTINCTIVE at this time. This is because:

  • SSU2 is available but disabled by default. Peer Tests and Introducers are still in progress.
  • We do not implement Elgamal or AES+SessionTag or DSA. This will not change.

Implemented Features

  • Clients
  • Cryptographic primitives(see also: https://github.com/go-i2p/crypto)
    • Signing
      • [X] ECDSA_SHA256_P256
      • [X] ECDSA_SHA384_P384
      • [X] ECDSA_SHA512_P521
      • [X] Ed25519
    • Verifying
      • [X] DSA
      • [X] ECDSA_SHA256_P256
      • [X] ECDSA_SHA384_P384
      • [X] ECDSA_SHA512_P521
      • [X] RSA_SHA256_2048
      • [X] RSA_SHA384_3072
      • [X] RSA_SHA512_4096
      • [X] Ed25519
      • [X] Red25519
    • [X] ElGamal
    • [X] AES256
    • [X] X25519
    • [X] ChaCha20/Poly1305
    • [X] Elligator2
    • [X] HKDF
    • [X] HMAC
    • [X] Noise subsystem
  • End-to-End Crypto (crypto engine in go-noise/ratchet)
    • [X] Garlic messages (thin adapter in lib/i2np/garlic_session.go → go-noise/ratchet.SessionManager)
    • [X] ECIES-X25519-AEAD-Ratchet (primary, implemented in go-noise/ratchet/)
    • [X] Tunnel build record crypto (adapter in lib/i2np/build_record_crypto.go → go-noise/ratchet.BuildRecordCrypto)
    • [ ] ElGamal/AES+SessionTag (not implemented - ECIES-only destinations supported)
  • I2NP
    • [X] Message parsing and serialization
    • [X] Message interfaces and factory patterns
    • [X] Database Store/Lookup message structures
    • [X] Tunnel Build message structures
    • [X] Data, DeliveryStatus, TunnelData messages
    • [X] Build Request/Response Record parsing
    • [X] Message routing and handling
  • NetDB
    • [X] Local storage interface
    • [X] Reseed functionality (basic implementation)
    • [X] Persistence to disk
    • [X] RouterInfo management
    • [X] LeaseSet management
    • [X] Lookups
    • [X] Expiry
    • [X] Exploration
    • [X] Publishing
    • [X] Floodfill
    • [X] LS2 and Encrypted Leasesets (I2CP clients can publish; storage/retrieval supported; inbound client-side decryption and MetaLeaseSet resolution implemented)
  • Transport Layer
    • [X] Transport manager and interfaces
    • NTCP2
      • [X] Session handshake using noise protocol
      • [X] Connection management
      • [X] I2NP message framing and unframing
      • [X] Session lifecycle management
      • [X] Message queuing and worker threads
    • SSU2
      • [X] Session handshake
      • [X] Connection management
      • [~] Peer Tests
      • [~] Introducers
    • Noise Subsystem (see also https://github.com/go-i2p/go-noise)
      • [X] Noise Socket Framework
      • [X] NTCP2 Socket Framework
      • [X] ECIES-X25519-AEAD-Ratchet engine (ratchet/ package)
      • [X] SSU2 Socket Framework
  • Tunnels
    • [X] Message structure parsing (delivery instructions)
    • [X] Fragment handling and reassembly
    • [X] Build Request/Response record interfaces
    • [X] Tunnel building and management
    • [X] Tunnel cryptography (layered encryption)
    • [X] Gateway and endpoint implementation
    • [X] Participant functionality
  • Common Data Structures(see also: https://github.com/go-i2p/common
    • [X] Keys and Cert
    • [X] Key Certificates
    • [X] Certificate
    • [X] Lease
    • [X] Lease Set
    • [X] Router Info
    • [X] Router Identity
    • [X] Router Address
    • [X] Session Key
    • [X] Signature Types
    • [X] Destination
    • [X] Data Types
    • [X] Session Tag

Verbosity

Logging can be enabled and configured using the DEBUG_I2P environment variable. By default, logging is disabled.

Note: Logging is configured via environment variables (not config.yaml or command-line flags) because it is managed by an external logger package and needs to be set before the application starts.

There are three available log levels:

  • Debug
export DEBUG_I2P=debug
  • Warn
export DEBUG_I2P=warn
  • Error
export DEBUG_I2P=error

If DEBUG_I2P is set to an unrecognized variable, it will fall back to “debug”.

Fast-Fail mode

Fast-Fail mode can be activated by setting WARNFAIL_I2P to any non-empty value. When set, every warning or error is Fatal. It is unsafe for production use, and intended only for debugging and testing purposes.

export WARNFAIL_I2P=true

If WARNFAIL_I2P is set and DEBUG_I2P is unset, DEBUG_I2P will be set to debug.

SSU2 Transport

SSU2 is the UDP-based transport protocol for I2P. It is available but disabled by default because Peer Tests and Introducers are still in progress.

Configuration

Enable SSU2 via command-line flags:

# Enable SSU2 transport
go-i2p --transport.ssu2-enabled=true

# Set a specific listen port (default: 0 = random)
go-i2p --transport.ssu2-enabled=true --transport.ssu2-port=9002

Or via config.yaml:

transport:
  ssu2_enabled: true
  ssu2_port: 0  # 0 = random port assigned by OS

I2CP Server

The I2CP (I2P Client Protocol) server allows client applications to communicate with the I2P router. It is enabled by default and listens on localhost:7654.

Configuration

You can configure the I2CP server using command-line flags:

# Disable I2CP server
go-i2p --i2cp.enabled=false

# Change listen address
go-i2p --i2cp.address=0.0.0.0:7654

# Adjust maximum sessions (default is 100)
go-i2p --i2cp.max-sessions=200

# Use Unix domain socket instead of TCP
go-i2p --i2cp.network=unix --i2cp.address=/tmp/i2cp.sock

Features

  • Session Management: Create, reconfigure, and destroy client sessions
  • Message Protocol: Full I2CP v0.9.67 protocol implementation
  • Multi-client Support: Handle multiple concurrent client sessions (default: 100)
  • Thread-safe: Concurrent session access with proper synchronization

For more details, see lib/i2cp/README.md.

Contributing

See CONTRIBUTING.md for more information.

License

This project is licensed under the MIT license, see LICENSE for more information.

Top Contributors

e
eyedeekay
1251 commits
H
Haris Khan
176 commits
H
Hayden Parker
65 commits
J
Jeff Becker
35 commits
H
Hayden Parker
28 commits
View all contributors on GitHub →