i2pbind

Documentation

Overview

Package i2pbind provides a WireGuard Bind implementation that uses I2P for transport instead of regular UDP. This enables WireGuard tunnels to run over the I2P anonymizing network.

Prerequisites:

• A running I2P router with SAM enabled (default port 7656)
• The onramp and sam3 libraries from github.com/go-i2p

Example usage:

bind := i2pbind.NewI2PBind("my-wireguard-tunnel")
dev := device.NewDevice(tun, bind, logger)

Package i2pbind logging configuration

Index

• Constants
• type I2PBind
  • func NewI2PBind(name string) *I2PBind
  • func NewI2PBindWithOptions(name, samAddr string, options []string) *I2PBind
  • func NewI2PBindWithSAM(name, samAddr string) *I2PBind
  • func (b *I2PBind) BatchSize() int
  • func (b *I2PBind) Close() error
  • func (b *I2PBind) LocalAddress() (string, error)
  • func (b *I2PBind) LocalDestination() (i2pkeys.I2PAddr, error)
  • func (b *I2PBind) Open(port uint16) ([]conn.ReceiveFunc, uint16, error)
  • func (b *I2PBind) ParseEndpoint(s string) (conn.Endpoint, error)
  • func (b *I2PBind) Send(bufs [][]byte, endpoint conn.Endpoint) error
  • func (b *I2PBind) SetMark(mark uint32) error
  • func (b *I2PBind) SetMeshHandler(handler MeshMessageHandler)
• type I2PEndpoint
  • func NewI2PEndpoint(dest i2pkeys.I2PAddr) *I2PEndpoint
  • func (e *I2PEndpoint) ClearSrc()
  • func (e *I2PEndpoint) Destination() i2pkeys.I2PAddr
  • func (e *I2PEndpoint) DstIP() netip.Addr
  • func (e *I2PEndpoint) DstToBytes() []byte
  • func (e *I2PEndpoint) DstToString() string
  • func (e *I2PEndpoint) SrcIP() netip.Addr
  • func (e *I2PEndpoint) SrcToString() string
• type MeshMessageHandler

Constants

const (
	// MaxI2PDatagramSize is the maximum size for I2P datagrams (31KB)
	MaxI2PDatagramSize = 31 * 1024

	// DefaultSAMAddress is the default SAM bridge address
	DefaultSAMAddress = "127.0.0.1:7656"
)

Types

type I2PBind

type I2PBind struct {
	// contains filtered or unexported fields
}

I2PBind implements conn.Bind using I2P datagrams for transport

func NewI2PBind

func NewI2PBind(name string) *I2PBind

NewI2PBind creates a new I2P Bind with default settings

func NewI2PBindWithOptions

func NewI2PBindWithOptions(name, samAddr string, options []string) *I2PBind

NewI2PBindWithOptions creates a new I2P Bind with custom SAM address and tunnel options. The options parameter allows configuring I2P tunnel parameters such as:

• inbound.length, outbound.length (tunnel hop count, application default is 2)
• inbound.quantity, outbound.quantity (number of tunnels)
• inbound.backupQuantity, outbound.backupQuantity (backup tunnels)

If options is nil or empty, onramp.OPT_DEFAULTS will be used. See github.com/go-i2p/sam3 for available options.

func NewI2PBindWithSAM

func NewI2PBindWithSAM(name, samAddr string) *I2PBind

NewI2PBindWithSAM creates a new I2P Bind with a custom SAM address

func (*I2PBind) BatchSize

func (b *I2PBind) BatchSize() int

BatchSize returns the number of packets to batch - I2P doesn't support batching

func (*I2PBind) Close

func (b *I2PBind) Close() error

Close shuts down the I2P session

func (*I2PBind) LocalAddress

func (b *I2PBind) LocalAddress() (string, error)

LocalAddress returns this node's I2P destination address in base32 format.

This method will return an error if:

• The bind has not been opened yet (call Open() first)
• The SAM bridge is not running or accessible
• The I2P session failed to establish

After a successful Open() call, LocalAddress() should always succeed. If it fails after Open(), the I2P session may have been terminated.

func (*I2PBind) LocalDestination

func (b *I2PBind) LocalDestination() (i2pkeys.I2PAddr, error)

LocalDestination returns the full I2P destination.

This method will return an error if:

• The bind has not been opened yet (call Open() first)

After a successful Open() call, LocalDestination() should always succeed.

func (*I2PBind) Open

func (b *I2PBind) Open(port uint16) ([]conn.ReceiveFunc, uint16, error)

Open initializes the I2P datagram session and returns receive functions

func (*I2PBind) ParseEndpoint

func (b *I2PBind) ParseEndpoint(s string) (conn.Endpoint, error)

ParseEndpoint parses an I2P address string into an endpoint Accepts base32 addresses (xxx.b32.i2p) or full base64 destinations

func (*I2PBind) Send

func (b *I2PBind) Send(bufs [][]byte, endpoint conn.Endpoint) error

Send transmits packets to the specified I2P endpoint

func (*I2PBind) SetMark

func (b *I2PBind) SetMark(mark uint32) error

SetMark sets the socket mark - not applicable for I2P

func (*I2PBind) SetMeshHandler

func (b *I2PBind) SetMeshHandler(handler MeshMessageHandler)

SetMeshHandler sets the callback for handling mesh protocol messages. When a non-WireGuard packet is received (e.g., gossip or handshake messages), the handler will be called with the raw message data and sender address. This should be called before Open() to ensure no messages are dropped. A warning is logged if called after messages have already been received.

type I2PEndpoint

type I2PEndpoint struct {
	// contains filtered or unexported fields
}

I2PEndpoint represents an I2P destination as a WireGuard endpoint

func NewI2PEndpoint

func NewI2PEndpoint(dest i2pkeys.I2PAddr) *I2PEndpoint

NewI2PEndpoint creates a new I2P endpoint from a destination address

func (*I2PEndpoint) ClearSrc

func (e *I2PEndpoint) ClearSrc()

ClearSrc clears the source address used for sticky routing

func (*I2PEndpoint) Destination

func (e *I2PEndpoint) Destination() i2pkeys.I2PAddr

Destination returns the underlying I2P destination address

func (*I2PEndpoint) DstIP

func (e *I2PEndpoint) DstIP() netip.Addr

DstIP returns the destination "IP" - for I2P this is not meaningful Returns an invalid address since I2P doesn't use IP routing

func (*I2PEndpoint) DstToBytes

func (e *I2PEndpoint) DstToBytes() []byte

DstToBytes returns bytes representation of the destination for MAC2 cookies. Returns the raw 32-byte I2P destination hash for cryptographic operations.

func (*I2PEndpoint) DstToString

func (e *I2PEndpoint) DstToString() string

DstToString returns the destination I2P address as a base32 string

func (*I2PEndpoint) SrcIP

func (e *I2PEndpoint) SrcIP() netip.Addr

SrcIP returns the source "IP" - for I2P this is not meaningful

func (*I2PEndpoint) SrcToString

func (e *I2PEndpoint) SrcToString() string

SrcToString returns the source I2P address as a string

type MeshMessageHandler

type MeshMessageHandler func(data []byte, from i2pkeys.I2PAddr)

MeshMessageHandler is a callback function for handling mesh protocol messages. It is called when a non-WireGuard message is received (e.g., gossip/handshake messages). The data parameter contains the raw message bytes, and from is the sender's I2P address.