destination

README

destination

-- import "github.com/go-i2p/common/destination"

Package destination implements the I2P Destination common data structure

Usage

const I2PBase32Suffix = ".b32.i2p"

I2PBase32Suffix is the standard suffix for I2P base32 addresses. Used in destination address generation to create valid I2P hostnames.

type Destination

type Destination struct {
	*keys_and_cert.KeysAndCert
}

Destination is the representation of an I2P Destination.

https://geti2p.net/spec/common-structures#destination

func NewDestination

func NewDestination(keysAndCert *keys_and_cert.KeysAndCert) (*Destination, error)

NewDestination creates a new Destination from KeysAndCert. Returns an error if the provided KeysAndCert is invalid or uses prohibited key types.

func NewDestinationFromBytes

func NewDestinationFromBytes(data []byte) (*Destination, []byte, error)

NewDestinationFromBytes creates a Destination by parsing bytes. Returns the parsed Destination, remaining bytes, and any errors encountered.

func ReadDestination

func ReadDestination(data []byte) (Destination, []byte, error)

ReadDestination returns Destination from a []byte. The remaining bytes after the specified length are also returned. Returns an error if parsing fails or if the destination uses prohibited key types.

func (*Destination) Validate

func (d *Destination) Validate() error

Validate checks if the Destination is properly initialized and uses permitted key types. Returns an error if the destination or its components are invalid, or if prohibited key types (MLKEM crypto, RSA/Ed25519ph signing) are present.

func (*Destination) IsValid

func (d *Destination) IsValid() bool

IsValid returns true if the Destination is properly initialized. This is a convenience method that returns false instead of an error.

func (*Destination) Hash

func (d *Destination) Hash() ([32]byte, error)

Hash returns the SHA-256 hash of the Destination's binary representation. Returns an error if the destination is not properly initialized.

func (*Destination) Equals

func (d *Destination) Equals(other *Destination) bool

Equals returns true if two Destinations are byte-for-byte identical. Returns false if either destination is nil or not properly initialized.

func (Destination) Bytes

func (d Destination) Bytes() ([]byte, error)

Bytes returns the binary representation of the Destination. Returns an error if the destination is not properly initialized.

func (Destination) Base32Address

func (d Destination) Base32Address() (string, error)

Base32Address returns the I2P base32 address for this Destination. Returns an error if the destination is not properly initialized.

func (Destination) Base64

func (d Destination) Base64() (string, error)

Base64 returns the I2P base64 address for this Destination. Returns an error if the destination is not properly initialized.

func (Destination) String

func (d Destination) String() string

String returns the I2P base32 address as the default string representation. Implements the fmt.Stringer interface.

destination

github.com/go-i2p/common/destination

go-i2p template file

Documentation

Overview

Package destination implements the I2P Destination common data structure

Package destination implements the I2P Destination common data structure

Package destination implements the I2P Destination common data structure

Package destination implements the I2P Destination common data structure according to specification version 0.9.67.

A Destination represents a unique cryptographic identity in the I2P network, consisting of public encryption and signing keys along with a certificate. Destinations are used to identify services, routers, and endpoints within I2P.

Overview

A Destination contains:

• Public encryption key (ElGamal or X25519)
• Public signing key (DSA, ECDSA, EdDSA, or RSA)
• Certificate (typically a KEY certificate with cryptographic parameters)
• Optional padding for alignment

Safe Constructors

The package provides validated constructors for creating destinations:

// Create from KeysAndCert
dest, err := destination.NewDestination(keysAndCert)
if err != nil {
    return err
}

// Parse from bytes
dest, remainder, err := destination.NewDestinationFromBytes(data)
if err != nil {
    return err
}

Validation

Destinations support validation to ensure proper initialization:

// Full validation
if err := dest.Validate(); err != nil {
    return err
}

// Boolean check
if !dest.IsValid() {
    return errors.New("invalid destination")
}

Encoding Formats

Destinations can be encoded in multiple formats:

// Base64 encoding (standard I2P format)
base64Str, err := dest.Base64()
if err != nil {
    return err
}

// Base32 address (human-readable .i2p address)
address, err := dest.Base32Address()
if err != nil {
    return err
}

// Raw bytes
bytes, err := dest.Bytes()
if err != nil {
    return err
}

Parsing from Bytes

Destinations can be safely parsed from byte streams:

dest, remainder, err := destination.ReadDestination(data)
if err != nil {
    return err
}
if !dest.IsValid() {
    return errors.New("invalid destination")
}

Key Access

Public keys can be accessed safely:

// Get public encryption key
pubKey, err := dest.PublicKey()
if err != nil {
    return err
}

// Get signing public key
sigKey, err := dest.SigningPublicKey()
if err != nil {
    return err
}

// Get certificate
cert := dest.Certificate()

Best Practices

• Always use NewDestination() or NewDestinationFromBytes() constructors
• Validate destinations after parsing from untrusted sources
• Use error-checking methods when accessing keys and encoding
• Prefer Ed25519/X25519 for new destinations (modern cryptography)

Specification

Reference: https://geti2p.net/spec/common-structures#destination

This implementation follows I2P specification version 0.9.67 and provides comprehensive validation and error handling for all destination operations.

Index

• Constants
• type Destination
  • func CanonicalizeDestination(d *Destination) (*Destination, error)
  • func NewDestination(keysAndCert *keys_and_cert.KeysAndCert) (*Destination, error)
  • func NewDestinationFromBytes(data []byte) (*Destination, []byte, error)
  • func NewDestinationWithCompressiblePadding(publicKey types.ReceivingPublicKey, signingPublicKey types.SigningPublicKey, ...) (*Destination, error)
  • func ReadDestination(data []byte) (Destination, []byte, error)
  • func (d Destination) Base32Address() (string, error)
  • func (d Destination) Base64() (string, error)
  • func (d Destination) Bytes() ([]byte, error)
  • func (d *Destination) Equals(other *Destination) bool
  • func (d *Destination) Hash() ([32]byte, error)
  • func (d *Destination) IsValid() bool
  • func (d Destination) String() string
  • func (d *Destination) Validate() error

Constants

const I2PBase32Suffix = ".b32.i2p"

I2PBase32Suffix is the standard suffix for I2P base32 addresses. Used in destination address generation to create valid I2P hostnames.

const I2P_BASE32_SUFFIX = I2PBase32Suffix

Deprecated: Use I2PBase32Suffix instead. This name does not follow Go conventions.

Types

type Destination

type Destination struct {
	*keys_and_cert.KeysAndCert
}

Destination is the representation of an I2P Destination. Spec: https://geti2p.net/spec/common-structures#destination

func CanonicalizeDestination

func CanonicalizeDestination(d *Destination) (*Destination, error)

CanonicalizeDestination returns an equivalent Destination in canonical wire form. Per the I2P spec, ElGamal+DSA-SHA1 Destinations must use a NULL certificate (3 bytes) rather than a KEY(0,0) certificate (7 bytes). Using the non-canonical form produces a different SHA256 address hash.

For all other key types the original Destination is returned unchanged. The caller is responsible for updating any cached hashes after canonicalization.

func NewDestination

func NewDestination(keysAndCert *keys_and_cert.KeysAndCert) (*Destination, error)

NewDestination creates a new Destination from KeysAndCert. This is the primary constructor for creating destinations programmatically. Returns an error if the provided KeysAndCert is invalid or uses prohibited key types.

func NewDestinationFromBytes

func NewDestinationFromBytes(data []byte) (*Destination, []byte, error)

NewDestinationFromBytes creates a Destination by parsing bytes. Returns a pointer for consistency with NewDestination. Returns the parsed Destination, remaining bytes, and any errors encountered.

func NewDestinationWithCompressiblePadding

func NewDestinationWithCompressiblePadding(
	publicKey types.ReceivingPublicKey,
	signingPublicKey types.SigningPublicKey,
	cert *certificate.Certificate,
) (*Destination, error)

NewDestinationWithCompressiblePadding creates a new Destination and auto-generates Proposal 161-compliant compressible padding from the key certificate and key sizes. This is the recommended constructor for new Destinations per I2P spec 0.9.57+.

Each 32-byte padding block is derived deterministically from a single random seed, allowing SSU2/I2NP Database Store messages to compress the padding efficiently.

Returns an error if the certificate specifies unknown key types (where CryptoPublicKeySize or SigningPublicKeySizeOrError return 0/error), or if the certificate is not a valid KEY certificate.

func ReadDestination

func ReadDestination(data []byte) (Destination, []byte, error)

ReadDestination returns Destination from a []byte. The remaining bytes after the specified length are also returned. Returns a list of errors that occurred during parsing.

For ElGamal+DSA-SHA1 destinations encoded with a KEY(0,0) certificate, the destination is automatically canonicalized to the NULL certificate form per the I2P specification. This ensures consistent SHA-256 hashing regardless of the wire encoding used by the sender.

func (Destination) Base32Address

func (d Destination) Base32Address() (string, error)

Base32Address returns the I2P base32 address for this Destination. Returns an error if the destination is not properly initialized. Uses a value receiver for API compatibility with callers that receive Destination by value (e.g., from LeaseSet2.Destination()).

func (Destination) Base64

func (d Destination) Base64() (string, error)

Base64 returns the I2P base64 address for this Destination. Returns an error if the destination is not properly initialized. Uses a value receiver for API compatibility with callers that receive Destination by value.

func (Destination) Bytes

func (d Destination) Bytes() ([]byte, error)

Bytes returns the binary representation of the Destination. This serializes the destination back to []byte format for storage or transmission. Returns an error if the destination is not properly initialized. Uses a value receiver because the Destination struct contains only a pointer field, making copies cheap, and this preserves API compatibility.

func (*Destination) Equals

func (d *Destination) Equals(other *Destination) bool

Equals returns true if two Destinations are logically identical. For ElGamal+DSA-SHA1 destinations, both are canonicalized to the NULL certificate form before comparison, so a KEY(0,0) encoded destination and a NULL cert encoded destination will correctly compare as equal. Returns false if either destination is nil or not properly initialized.

func (*Destination) Hash

func (d *Destination) Hash() ([32]byte, error)

Hash returns the SHA-256 hash of the Destination's binary representation. The I2P network database is keyed by SHA256(Destination). Returns an error if the destination is not properly initialized.

func (*Destination) IsValid

func (d *Destination) IsValid() bool

IsValid returns true if the Destination is properly initialized. This is a convenience method that returns false instead of an error.

func (Destination) String

func (d Destination) String() string

String returns the I2P base32 address as the default string representation. Implements the fmt.Stringer interface for convenient logging and debugging. Returns "<nil Destination>" if the destination is not properly initialized, or "<invalid Destination>" if address generation fails.

func (*Destination) Validate

func (d *Destination) Validate() error

Validate checks if the Destination is properly initialized and uses permitted key types. Returns an error if the destination or its components are invalid, or if prohibited key types (MLKEM crypto, RSA/Ed25519ph signing) are present.