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
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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶ added in v0.1.5
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 ¶ added in v0.1.0
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 ¶ added in v0.1.0
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 ¶ added in v0.1.5
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 ¶ added in v0.1.5
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 ¶ added in v0.1.5
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 ¶ added in v0.1.0
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 ¶ added in v0.1.5
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 ¶ added in v0.1.0
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.
Source Files