README
¶
session_tag
-- import "github.com/go-i2p/common/session_tag"
Package session_tag implements the I2P SessionTag common data structure
Package session_tag implements the I2P SessionTag common data structure
Package session_tag implements the I2P SessionTag common data structure
Usage
const SessionTagSize = 32
SessionTagSize is the size of an I2P SessionTag in bytes. According to the I2P specification, a SessionTag is always 32 bytes.
https://geti2p.net/spec/common-structures#session-tag
type SessionTag
type SessionTag struct {
}
SessionTag is the representation of an I2P SessionTag. A SessionTag is a 32-byte random number used in I2P for session identification.
https://geti2p.net/spec/common-structures#session-tag
func NewSessionTag
func NewSessionTag(data []byte) (session_tag *SessionTag, remainder []byte, err error)
NewSessionTag creates a new *SessionTag from []byte using ReadSessionTag. Returns a pointer to SessionTag unlike ReadSessionTag.
func NewSessionTagFromArray
func NewSessionTagFromArray(data [SessionTagSize]byte) SessionTag
NewSessionTagFromArray creates a new SessionTag from a byte array.
func NewSessionTagFromBytes
func NewSessionTagFromBytes(data []byte) (SessionTag, error)
NewSessionTagFromBytes creates a new SessionTag from a byte slice. The input must be exactly SessionTagSize bytes long.
func ReadSessionTag
func ReadSessionTag(bytes []byte) (info SessionTag, remainder []byte, err error)
ReadSessionTag returns SessionTag from a []byte. The remaining bytes after the specified length are also returned. Returns a list of errors that occurred during parsing.
func (SessionTag) Array
func (st SessionTag) Array() [SessionTagSize]byte
Array returns the SessionTag as a byte array. This method provides access to the underlying fixed-size array.
func (SessionTag) Bytes
func (st SessionTag) Bytes() []byte
Bytes returns the SessionTag as a byte slice. This method provides compatibility with code that expects []byte.
func (SessionTag) Equal
func (st SessionTag) Equal(other SessionTag) bool
Equal checks if two SessionTags are equal.
func (*SessionTag) SetBytes
func (st *SessionTag) SetBytes(data []byte) error
SetBytes sets the SessionTag value from a byte slice. The input must be exactly SessionTagSize bytes long.
func (SessionTag) String
func (st SessionTag) String() string
String returns a hex representation of the SessionTag for debugging.
session_tag
github.com/go-i2p/common/session_tag
Documentation
¶
Overview ¶
Package session_tag implements the I2P SessionTag common data structure
Package session_tag implements the I2P SessionTag and ECIESSessionTag common data structures.
A SessionTag is a 32-byte random number used for session identification in I2P's ElGamal/AES+SessionTag encryption layer.
An ECIESSessionTag is an 8-byte session tag that is a fundamental property of the ECIES-X25519-AEAD-Ratchet protocol. All ECIES-X25519 destinations and routers use 8-byte session tags (regardless of I2NP message type), in contrast to the legacy 32-byte ElGamal/AES+SessionTag form.
Both types provide constant-time equality comparison via crypto/subtle to prevent timing side-channel attacks on session tag lookups.
Both types implement the TagIdentifier interface, allowing polymorphic handling in protocol code that operates on either tag type generically.
Design Rationale: Wrapper Struct vs Bare Array ¶
SessionTag and ECIESSessionTag use a wrapper struct (struct{value [N]byte}) rather than a bare array type (type T [N]byte) as used by the sibling session_key package. The wrapper struct approach provides encapsulation — callers cannot directly index into the underlying array, so all access goes through methods (Bytes, SetBytes, Equal, etc.). This prevents accidental mutation and ensures constant-time comparison is always used.
The sibling session_key package uses a bare array type, which allows direct == comparison and use as a map key. Both approaches are valid Go idioms with different tradeoffs: bare arrays are simpler and map-key-friendly; wrapper structs enforce encapsulation and method-based access.
Usage ¶
Create a random session tag:
tag, err := session_tag.NewRandomSessionTag()
Read a session tag from wire data:
tag, remainder, err := session_tag.ReadSessionTag(data)
Use the TagIdentifier interface for polymorphic handling:
func logTag(t session_tag.TagIdentifier) {
fmt.Println(t.String())
}
Specification references:
- https://geti2p.net/spec/common-structures#session-tag
- https://geti2p.net/spec/ecies
- https://geti2p.net/spec/i2np#databaselookup
Package session_tag implements the I2P SessionTag common data structure
Package session_tag implements the I2P SessionTag common data structure
Index ¶
- Constants
- type ECIESSessionTag
- func NewECIESSessionTag(data []byte) (*ECIESSessionTag, []byte, error)
- func NewECIESSessionTagFromArray(data [ECIESSessionTagSize]byte) ECIESSessionTag
- func NewECIESSessionTagFromBytes(data []byte) (ECIESSessionTag, error)
- func NewRandomECIESSessionTag() (ECIESSessionTag, error)
- func ReadECIESSessionTag(data []byte) (info ECIESSessionTag, remainder []byte, err error)
- func (st ECIESSessionTag) Array() [ECIESSessionTagSize]byte
- func (st ECIESSessionTag) Bytes() []byte
- func (st ECIESSessionTag) Equal(other ECIESSessionTag) bool
- func (st ECIESSessionTag) EqualBytes(other []byte) bool
- func (st ECIESSessionTag) IsZero() bool
- func (st *ECIESSessionTag) SetBytes(data []byte) error
- func (st ECIESSessionTag) String() string
- type SessionTag
- func NewRandomSessionTag() (SessionTag, error)
- func NewSessionTag(data []byte) (sessionTag *SessionTag, remainder []byte, err error)
- func NewSessionTagFromArray(data [SessionTagSize]byte) SessionTag
- func NewSessionTagFromBytes(data []byte) (SessionTag, error)
- func ReadSessionTag(bytes []byte) (info SessionTag, remainder []byte, err error)
- func (st SessionTag) Array() [SessionTagSize]byte
- func (st SessionTag) Bytes() []byte
- func (st SessionTag) Equal(other SessionTag) bool
- func (st SessionTag) EqualBytes(other []byte) bool
- func (st SessionTag) IsZero() bool
- func (st *SessionTag) SetBytes(data []byte) error
- func (st SessionTag) String() string
- type TagIdentifier
Constants ¶
const ECIESSessionTagSize = 8
ECIESSessionTagSize is the size of a session tag in the ECIES-X25519-AEAD-Ratchet protocol. 8-byte session tags are a fundamental property of this protocol (used for both new-session-reply and existing-session messages) regardless of I2NP message type. This is distinct from the legacy 32-byte ElGamal/AES+SessionTag form.
https://geti2p.net/spec/common-structures#session-tag https://geti2p.net/spec/ecies
const SessionTagSize = 32
SessionTagSize is the size of an I2P SessionTag in bytes. According to the I2P specification, a SessionTag is always 32 bytes.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ECIESSessionTag ¶ added in v0.1.5
type ECIESSessionTag struct {
// contains filtered or unexported fields
}
ECIESSessionTag is an 8-byte session tag used with the ECIES-X25519-AEAD-Ratchet protocol. 8-byte tags are a fundamental property of this protocol (for all ECIES-X25519 destinations and routers), not limited to any specific I2NP message type.
https://geti2p.net/spec/common-structures#session-tag https://geti2p.net/spec/ecies
func NewECIESSessionTag ¶ added in v0.1.5
func NewECIESSessionTag(data []byte) (*ECIESSessionTag, []byte, error)
NewECIESSessionTag creates a new ECIESSessionTag from a byte slice. Returns a pointer to the ECIESSessionTag, the remaining bytes, and any error.
func NewECIESSessionTagFromArray ¶ added in v0.1.5
func NewECIESSessionTagFromArray(data [ECIESSessionTagSize]byte) ECIESSessionTag
NewECIESSessionTagFromArray creates a new ECIESSessionTag from a byte array.
func NewECIESSessionTagFromBytes ¶ added in v0.1.5
func NewECIESSessionTagFromBytes(data []byte) (ECIESSessionTag, error)
NewECIESSessionTagFromBytes creates a new ECIESSessionTag from a byte slice. The input must be exactly ECIESSessionTagSize bytes long.
func NewRandomECIESSessionTag ¶ added in v0.1.5
func NewRandomECIESSessionTag() (ECIESSessionTag, error)
NewRandomECIESSessionTag creates a new ECIESSessionTag filled with cryptographically secure random bytes from crypto/rand.
Note: In the ECIES-X25519-AEAD-Ratchet protocol, session tags are typically ratchet-derived rather than purely random. This constructor is provided for testing and for protocols that require random 8-byte tags.
func ReadECIESSessionTag ¶ added in v0.1.5
func ReadECIESSessionTag(data []byte) (info ECIESSessionTag, remainder []byte, err error)
ReadECIESSessionTag reads an ECIESSessionTag from a byte slice. Returns the ECIESSessionTag, the remaining bytes, and any error.
func (ECIESSessionTag) Array ¶ added in v0.1.5
func (st ECIESSessionTag) Array() [ECIESSessionTagSize]byte
Array returns the ECIESSessionTag as a byte array. This method provides access to the underlying fixed-size array.
func (ECIESSessionTag) Bytes ¶ added in v0.1.5
func (st ECIESSessionTag) Bytes() []byte
Bytes returns the ECIESSessionTag as a byte slice. This method provides compatibility with code that expects []byte.
func (ECIESSessionTag) Equal ¶ added in v0.1.5
func (st ECIESSessionTag) Equal(other ECIESSessionTag) bool
Equal checks if two ECIESSessionTags are equal using constant-time comparison to prevent timing side-channel attacks on session tag lookups.
func (ECIESSessionTag) EqualBytes ¶ added in v0.1.5
func (st ECIESSessionTag) EqualBytes(other []byte) bool
EqualBytes performs a constant-time equality check against a raw byte slice. Returns false if the lengths differ, avoiding out-of-bounds panics.
func (ECIESSessionTag) IsZero ¶ added in v0.1.5
func (st ECIESSessionTag) IsZero() bool
IsZero returns true if the ECIESSessionTag is the zero value (all bytes are 0x00). This is useful for detecting uninitialized tags when stored in maps or used as sentinels.
func (*ECIESSessionTag) SetBytes ¶ added in v0.1.5
func (st *ECIESSessionTag) SetBytes(data []byte) error
SetBytes sets the ECIESSessionTag value from a byte slice. The input must be exactly ECIESSessionTagSize bytes long.
func (ECIESSessionTag) String ¶ added in v0.1.5
func (st ECIESSessionTag) String() string
String returns a hex representation of the ECIESSessionTag for debugging.
type SessionTag ¶
type SessionTag struct {
// contains filtered or unexported fields
}
SessionTag is the representation of an I2P SessionTag. A SessionTag is a 32-byte random number used in I2P for session identification.
https://geti2p.net/spec/common-structures#session-tag
func NewRandomSessionTag ¶ added in v0.1.5
func NewRandomSessionTag() (SessionTag, error)
NewRandomSessionTag creates a new SessionTag filled with cryptographically secure random bytes from crypto/rand. Per the I2P specification, a SessionTag is "a random number."
func NewSessionTag ¶
func NewSessionTag(data []byte) (sessionTag *SessionTag, remainder []byte, err error)
NewSessionTag creates a new *SessionTag from []byte using ReadSessionTag. Returns a pointer to SessionTag unlike ReadSessionTag.
func NewSessionTagFromArray ¶
func NewSessionTagFromArray(data [SessionTagSize]byte) SessionTag
NewSessionTagFromArray creates a new SessionTag from a byte array.
func NewSessionTagFromBytes ¶
func NewSessionTagFromBytes(data []byte) (SessionTag, error)
NewSessionTagFromBytes creates a new SessionTag from a byte slice. The input must be exactly SessionTagSize bytes long.
func ReadSessionTag ¶
func ReadSessionTag(bytes []byte) (info SessionTag, remainder []byte, err error)
ReadSessionTag returns SessionTag from a []byte. The remaining bytes after the specified length are also returned. Returns a list of errors that occurred during parsing.
func (SessionTag) Array ¶
func (st SessionTag) Array() [SessionTagSize]byte
Array returns the SessionTag as a byte array. This method provides access to the underlying fixed-size array.
func (SessionTag) Bytes ¶
func (st SessionTag) Bytes() []byte
Bytes returns the SessionTag as a byte slice. This method provides compatibility with code that expects []byte.
func (SessionTag) Equal ¶
func (st SessionTag) Equal(other SessionTag) bool
Equal checks if two SessionTags are equal using constant-time comparison to prevent timing side-channel attacks on session tag lookups.
func (SessionTag) EqualBytes ¶ added in v0.1.5
func (st SessionTag) EqualBytes(other []byte) bool
EqualBytes performs a constant-time equality check against a raw byte slice. Returns false if the lengths differ, avoiding out-of-bounds panics.
func (SessionTag) IsZero ¶ added in v0.1.5
func (st SessionTag) IsZero() bool
IsZero returns true if the SessionTag is the zero value (all bytes are 0x00). This is useful for detecting uninitialized tags when stored in maps or used as sentinels.
func (*SessionTag) SetBytes ¶
func (st *SessionTag) SetBytes(data []byte) error
SetBytes sets the SessionTag value from a byte slice. The input must be exactly SessionTagSize bytes long.
func (SessionTag) String ¶
func (st SessionTag) String() string
String returns a hex representation of the SessionTag for debugging.
type TagIdentifier ¶ added in v0.1.5
type TagIdentifier interface {
// Bytes returns the tag as a byte slice.
Bytes() []byte
// String returns a hex representation of the tag.
String() string
// IsZero returns true if the tag is the zero value.
IsZero() bool
// EqualBytes performs a constant-time equality check against a raw
// byte slice. Returns false if lengths differ. This allows polymorphic
// comparison through the interface without unsafe type assertions.
EqualBytes(other []byte) bool
}
TagIdentifier is a common interface implemented by both SessionTag and ECIESSessionTag, enabling polymorphic handling of either tag type in protocol code that operates on session tags generically.
Both SessionTag (32-byte ElGamal/AES) and ECIESSessionTag (8-byte ECIES-X25519-AEAD-Ratchet) satisfy this interface.
Source Files