lease_set

package
v0.1.59999 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 15 Imported by: 2

README

lease_set

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

lease_set.svg

Package lease_set implements the I2P LeaseSet (v1) common data structure.

A LeaseSet contains all currently authorized Leases for a particular Destination, the ElGamal public key to which garlic messages can be encrypted, a signing public key that can be used to revoke this version of the structure, and a cryptographic signature. The LeaseSet is one of the two structures stored in the network database (the other being RouterInfo), keyed under the SHA256 of the contained Destination.

Spec: https://geti2p.net/spec/common-structures#leaseset

Usage

const (
// LEASE_SET_PUBKEY_SIZE is the size of the ElGamal encryption public key (256 bytes).
LEASE_SET_PUBKEY_SIZE = 256

// LEASE_SET_DEFAULT_SIGNING_KEY_SIZE is the default signing public key size (128 bytes for DSA-SHA1).
LEASE_SET_DEFAULT_SIGNING_KEY_SIZE = 128

// LEASE_SET_DEFAULT_SIG_SIZE is the default signature size (40 bytes for DSA-SHA1).
LEASE_SET_DEFAULT_SIG_SIZE = 40

// LEASE_SET_MAX_LEASES is the maximum number of leases in a LeaseSet per spec.
LEASE_SET_MAX_LEASES = 16
)
func NewLeaseSet
func NewLeaseSet(
dest destination.Destination,
encryptionKey types.ReceivingPublicKey,
signingKey types.SigningPublicKey,
leases []lease.Lease,
signingPrivateKey types.SigningPrivateKey,
) (*LeaseSet, error)

NewLeaseSet creates a new LeaseSet from the provided components. Returns a pointer to LeaseSet for consistency with other constructors. The encryption key must be an ElGamal public key (256 bytes); non-ElGamal types are only valid in LeaseSet2. The signing key type must match the destination's signing key type.

func ReadLeaseSet
func ReadLeaseSet(data []byte) (LeaseSet, error)

ReadLeaseSet reads a lease set from byte data. The cryptographic signature is NOT verified during parsing; call Verify() on the returned LeaseSet to validate the signature. Trailing data after the signature is rejected per spec.

func ReadDestinationFromLeaseSet
func ReadDestinationFromLeaseSet(data []byte) (dest destination.Destination, remainder []byte, err error)

ReadDestinationFromLeaseSet reads the destination from lease set data.

type LeaseSet
type LeaseSet struct {
// unexported fields
}

LeaseSet is the representation of an I2P LeaseSet.

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

func (LeaseSet) Bytes
func (lease_set LeaseSet) Bytes() ([]byte, error)

Bytes returns the LeaseSet as a byte array.

func (LeaseSet) Destination
func (lease_set LeaseSet) Destination() destination.Destination

Destination returns the Destination from the LeaseSet.

func (LeaseSet) PublicKey
func (lease_set LeaseSet) PublicKey() (elgamal.ElgPublicKey, error)

PublicKey returns the public key as crypto.ElgPublicKey. Returns errors encountered during parsing.

func (LeaseSet) SigningKey
func (lease_set LeaseSet) SigningKey() (types.SigningPublicKey, error)

SigningKey returns the signing public key as crypto.SigningPublicKey.

func (LeaseSet) LeaseCount
func (lease_set LeaseSet) LeaseCount() int

LeaseCount returns the number of leases specified by the LeaseCount value.

func (LeaseSet) Leases
func (lease_set LeaseSet) Leases() []lease.Lease

Leases returns the leases as []Lease.

func (LeaseSet) Signature
func (lease_set LeaseSet) Signature() sig.Signature

Signature returns the signature as Signature.

func (LeaseSet) Verify
func (lease_set LeaseSet) Verify() error

Verify verifies the cryptographic signature of the LeaseSet. The signature is computed over all serialized bytes excluding the trailing Signature, and is verified against the signing public key from the Destination. Returns nil if the signature is valid, or an error describing the verification failure.

func (LeaseSet) Validate
func (ls *LeaseSet) Validate() error

Validate checks if the LeaseSet is properly initialized and valid. Returns an error if the lease set is nil, has invalid field values, or has an all-zero encryption key.

func (LeaseSet) IsValid
func (ls *LeaseSet) IsValid() bool

IsValid returns true if the LeaseSet is properly initialized and valid.

func (LeaseSet) NewestExpiration
func (lease_set LeaseSet) NewestExpiration() (newest data.Date, err error)

NewestExpiration returns the newest lease expiration as an I2P Date. If there are no leases, returns epoch zero and ErrNoLeases.

func (LeaseSet) OldestExpiration
func (lease_set LeaseSet) OldestExpiration() (earliest data.Date, err error)

OldestExpiration returns the oldest lease expiration as an I2P Date. If there are no leases, returns epoch zero and ErrNoLeases.

lease_set

github.com/go-i2p/common/lease_set

go-i2p template file

Documentation

Overview

Package lease_set constants

Package lease_set implements the I2P LeaseSet v1 common data structure.

Overview

A LeaseSet is one of two structures stored in the I2P network database (the other being RouterInfo). It bundles all currently authorized Leases for a particular Destination together with the ElGamal encryption public key for that Destination and is signed by the Destination's private signing key.

The LeaseSet is keyed in the netdb under the SHA-256 hash of the Destination; call LeaseSet.Hash to obtain this key.

LeaseSet v1 vs. LeaseSet2

This package implements LeaseSet v1 only. LeaseSet v1 mandates an ElGamal encryption key (256 bytes) and supports up to 16 leases. Destinations using non-ElGamal crypto (X25519, etc.) and the extended features introduced in I2P 0.9.38+ must use LeaseSet2 (see the lease_set2 package).

Versioning

Floodfill routers use the earliest expiration of all contained [Lease] entries as the LeaseSet version. Call LeaseSet.OldestExpiration to obtain this value and compare it with a cached LeaseSet when deciding whether a received LeaseSet is newer.

Thread Safety

LeaseSet values are immutable after construction. Concurrent reads are safe; no locking is required.

Spec reference

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

Package lease_set implements the I2P LeaseSet methods and constructor

Package lease_set implements the I2P LeaseSet struct definition

Package lease_set utility functions

Index

Constants

View Source 
const (
	// LEASE_SET_PUBKEY_SIZE is the size of the ElGamal encryption public key (256 bytes).
	LEASE_SET_PUBKEY_SIZE = 256

	// LEASE_SET_DEFAULT_SIGNING_KEY_SIZE is the default signing public key size (128 bytes for DSA-SHA1).
	// For key certificate destinations, the actual size is determined by the certificate.
	LEASE_SET_DEFAULT_SIGNING_KEY_SIZE = 128

	// LEASE_SET_DEFAULT_SIG_SIZE is the default signature size (40 bytes for DSA-SHA1).
	// For key certificate destinations, the actual size is determined by the certificate.
	LEASE_SET_DEFAULT_SIG_SIZE = 40

	// LEASE_SET_SPK_SIZE is the legacy name for LEASE_SET_DEFAULT_SIGNING_KEY_SIZE.
	// Deprecated: Use LEASE_SET_DEFAULT_SIGNING_KEY_SIZE instead.
	LEASE_SET_SPK_SIZE = LEASE_SET_DEFAULT_SIGNING_KEY_SIZE

	// LEASE_SET_SIG_SIZE is the legacy name for LEASE_SET_DEFAULT_SIG_SIZE.
	// Deprecated: Use LEASE_SET_DEFAULT_SIG_SIZE instead.
	LEASE_SET_SIG_SIZE = LEASE_SET_DEFAULT_SIG_SIZE

	// LEASE_SET_MAX_LEASES is the maximum number of leases in a LeaseSet per spec.
	LEASE_SET_MAX_LEASES = 16
)

Sizes of various structures in an I2P LeaseSet

Variables

View Source 
var (
	// ErrNoLeases is returned when a LeaseSet has no leases and an
	// expiration-related operation is called.
	ErrNoLeases = oops.Errorf("lease set has no leases")

	// ErrTrailingData is returned when a LeaseSet has trailing bytes after the
	// signature. The I2P spec prohibits excess data in structures.
	ErrTrailingData = oops.Errorf("LeaseSet has trailing data after signature")

	// ErrNonElGamalEncryptionKey is returned when a LeaseSet v1 is constructed
	// with an encryption key that is not an ElGamal public key. LeaseSet v1
	// mandates ElGamal encryption; non-ElGamal crypto types are only valid in
	// LeaseSet2.
	ErrNonElGamalEncryptionKey = oops.Errorf("LeaseSet v1 requires ElGamal encryption key")

	// ErrAllZeroEncryptionKey is returned when a LeaseSet's encryption key is
	// all zero bytes, which is cryptographically invalid.
	ErrAllZeroEncryptionKey = oops.Errorf("encryption key is all zeros (cryptographically invalid)")

	// ErrLegacyCryptoNotSupported is returned when a LeaseSet uses a NULL
	// certificate (implying DSA-SHA1 signing), which is legacy crypto that
	// this implementation does not support. Use KEY certificates with
	// modern algorithms (Ed25519, etc.) instead.
	ErrLegacyCryptoNotSupported = oops.Errorf("NULL certificate (DSA-SHA1) is legacy crypto and not supported; use KEY certificate with modern algorithms")

	// ErrSigningKeySizeMismatch is returned when a LeaseSet's signing key
	// size does not match the size expected by the destination's certificate.
	ErrSigningKeySizeMismatch = oops.Errorf("signing key size does not match destination certificate")

	// ErrLeaseCountInvariant is returned when the leaseCount field
	// disagrees with the actual number of leases stored in the struct.
	ErrLeaseCountInvariant = oops.Errorf("leaseCount field does not match len(leases)")
)

Errors

Functions

func ReadDestinationFromLeaseSet 

func ReadDestinationFromLeaseSet(data []byte) (dest destination.Destination, remainder []byte, err error)

ReadDestinationFromLeaseSet reads the destination from lease set data.

Types

type LeaseSet 

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

LeaseSet is the representation of an I2P LeaseSet.

The signingKey field "can be used to revoke this particular version of the structure" per the I2P spec. However, the revocation protocol was never fully specified or implemented in the reference Java router and has been superseded by LeaseSet2 (spec 0.9.38+). This implementation stores the signing key for structural completeness and signature verification, but does not implement revocation.

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

func NewLeaseSet 

func NewLeaseSet(
	dest destination.Destination,
	encryptionKey types.ReceivingPublicKey,
	signingKey types.SigningPublicKey,
	leases []lease.Lease,
	signingPrivateKey types.SigningPrivateKey,
) (*LeaseSet, error)

NewLeaseSet creates a new LeaseSet from the provided components. Returns a pointer to LeaseSet for consistency with other constructors.

func ReadLeaseSet 

func ReadLeaseSet(data []byte) (LeaseSet, error)

ReadLeaseSet reads a lease set from byte data. The cryptographic signature is NOT verified during parsing; call Verify() on the returned LeaseSet to validate the signature against the Destination's signing public key.

Unlike sibling Read functions (ReadCertificate, ReadLease), ReadLeaseSet does not return remainder bytes. The I2P spec prohibits excess data after the signature, so any trailing bytes are rejected as an error. LeaseSets are stored as complete structures in the network database and are not embedded within larger wire messages.

func (LeaseSet) Bytes 

func (lease_set LeaseSet) Bytes() ([]byte, error)

Bytes returns the LeaseSet as a byte array. The lease count byte is derived from len(leases) to guarantee consistency between the count byte and the actual lease entries in the output.

func (LeaseSet) Destination 

func (lease_set LeaseSet) Destination() destination.Destination

Destination returns the Destination from the LeaseSet.

func (LeaseSet) Hash added in v0.1.5 

func (lease_set LeaseSet) Hash() ([32]byte, error)

Hash returns the SHA-256 hash of the Destination bytes. Per the I2P spec, the LeaseSet "is keyed under the SHA256 of the contained Destination". This is the netdb lookup key used by floodfill routers.

func (*LeaseSet) IsValid added in v0.1.0 

func (ls *LeaseSet) IsValid() bool

IsValid returns true if the LeaseSet is properly initialized and valid. This is a convenience method that calls Validate() and returns false if there's an error.

func (LeaseSet) LeaseCount 

func (lease_set LeaseSet) LeaseCount() int

LeaseCount returns the number of leases specified by the LeaseCount value as int.

func (LeaseSet) Leases 

func (lease_set LeaseSet) Leases() []lease.Lease

Leases returns the leases as []Lease.

func (LeaseSet) NewestExpiration 

func (lease_set LeaseSet) NewestExpiration() (data.Date, error)

NewestExpiration returns the newest lease expiration as an I2P Date. If there are no leases, returns epoch zero and ErrNoLeases.

func (LeaseSet) OldestExpiration 

func (lease_set LeaseSet) OldestExpiration() (data.Date, error)

OldestExpiration returns the oldest lease expiration as an I2P Date. If there are no leases, returns epoch zero and ErrNoLeases.

Per the I2P spec, the earliest expiration of all Leases is treated as the timestamp or version of the LeaseSet. Floodfill routers will generally not accept a store of a LeaseSet unless it is 'newer' (i.e. has a later OldestExpiration) than the currently cached entry. Use OldestExpiration, not NewestExpiration, when comparing LeaseSet versions for netdb purposes.

func (LeaseSet) PublicKey 

func (lease_set LeaseSet) PublicKey() (public_key elgamal.ElgPublicKey, err error)

PublicKey returns the public key as crypto.ElgPublicKey. Returns errors encountered during parsing.

func (LeaseSet) Signature 

func (lease_set LeaseSet) Signature() sig.Signature

Signature returns the signature as Signature.

func (LeaseSet) SigningKey 

func (lease_set LeaseSet) SigningKey() (signing_public_key types.SigningPublicKey, err error)

SigningKey returns the signing public key as crypto.SigningPublicKey. returns errors encountered during parsing.

func (*LeaseSet) Validate added in v0.1.0 

func (ls *LeaseSet) Validate() error

Validate performs structural validation of the LeaseSet. It checks that all fields are present, correctly sized, and internally consistent. It does NOT verify the cryptographic signature (use LeaseSet.Verify for that) or check temporal validity of individual leases (e.g., expiration). Returns an error if the lease set is nil or has invalid field values.

func (LeaseSet) Verify 

func (lease_set LeaseSet) Verify() error

Verify verifies the cryptographic signature of the LeaseSet. The signature is computed over all serialised bytes excluding the trailing Signature, and is verified against the signing public key from the Destination. Returns nil if the signature is valid, or an error describing the verification failure.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.