README
¶
session_key
-- import "github.com/go-i2p/common/session_key"
Package session_key implements the I2P SessionKey common data structure.
A SessionKey is a 32-byte value used for symmetric AES-256 encryption and
decryption in the I2P network. SessionKey is defined as a bare fixed-size array
type ([32]byte) rather than a wrapper struct, which means values are directly
comparable with == and can be used as map keys. The sibling session_tag
package uses a wrapper struct instead; both are valid Go idioms with different
tradeoffs.
Spec: https://geti2p.net/spec/common-structures#sessionkey
Usage
const SESSION_KEY_SIZE = 32
SESSION_KEY_SIZE defines the size of an I2P SessionKey in bytes (32).
type SessionKey
type SessionKey [SESSION_KEY_SIZE]byte
SessionKey is the representation of an I2P SessionKey.
func GenerateSessionKey
func GenerateSessionKey() (SessionKey, error)
GenerateSessionKey creates a new SessionKey filled with cryptographically
secure random bytes from crypto/rand.
func NewSessionKey
func NewSessionKey(data []byte) (sessionKey *SessionKey, remainder []byte, err error)
NewSessionKey creates a new *SessionKey from []byte using ReadSessionKey.
Returns a pointer to SessionKey unlike ReadSessionKey.
func NewSessionKeyFromArray
func NewSessionKeyFromArray(data [SESSION_KEY_SIZE]byte) SessionKey
NewSessionKeyFromArray creates a SessionKey from a fixed-size byte array.
This provides zero-copy construction when a [SESSION_KEY_SIZE]byte is already
available.
func ReadSessionKey
func ReadSessionKey(bytes []byte) (sessionKey SessionKey, remainder []byte, err error)
ReadSessionKey returns SessionKey from a []byte. The remaining bytes after
the 32-byte key are also returned. Returns an error if the data is too short.
func (SessionKey) Bytes
func (sk SessionKey) Bytes() []byte
Bytes returns the SessionKey as a byte slice.
func (SessionKey) Equal
func (sk SessionKey) Equal(other SessionKey) bool
Equal checks if two SessionKeys are equal using constant-time comparison to prevent timing side-channel attacks.
func (SessionKey) IsZero
func (sk SessionKey) IsZero() bool
IsZero returns true if the SessionKey is all zeros (uninitialized).
func (SessionKey) MarshalBinary
func (sk SessionKey) MarshalBinary() ([]byte, error)
MarshalBinary implements encoding.BinaryMarshaler. Returns a defensive copy.
func (SessionKey) String
func (sk SessionKey) String() string
String returns a hex representation of the SessionKey for debugging.
func (*SessionKey) SetBytes
func (sk *SessionKey) SetBytes(data []byte) error
SetBytes sets the SessionKey value from a byte slice. The input must be exactly SESSION_KEY_SIZE bytes long.
func (*SessionKey) UnmarshalBinary
func (sk *SessionKey) UnmarshalBinary(data []byte) error
UnmarshalBinary implements encoding.BinaryUnmarshaler. The input must be
exactly SESSION_KEY_SIZE (32) bytes.
func (*SessionKey) Zeroize
func (sk *SessionKey) Zeroize()
Zeroize overwrites the SessionKey with zeros, erasing key material from memory. Call this when the key is no longer needed.
session_key
github.com/go-i2p/common/session_key
Documentation
¶
Overview ¶
Package session_key implements the I2P SessionKey common data structure
Package session_key implements the I2P SessionKey common data structure.
A SessionKey is a 32-byte value used for symmetric AES-256 encryption and decryption in the I2P network. SessionKeys are used to encrypt tunnel messages and garlic cloves.
Specification ¶
From the I2P Common Structures specification:
SessionKey :: 32 bytes
See https://geti2p.net/spec/common-structures#sessionkey
Design ¶
SessionKey is defined as a bare fixed-size array type ([32]byte) rather than a wrapper struct. This means SessionKey values are directly comparable with == and can be used as map keys, which is convenient for session management.
Because Bytes() uses a value receiver, the returned slice is backed by a copy of the array, NOT the original SessionKey. Mutations to the returned slice do NOT affect the original key, and zeroing the returned slice does NOT erase the key material. To securely erase key material, call sk.Zeroize() on the original SessionKey value.
The sibling session_tag package uses a wrapper struct instead; both approaches are valid Go idioms with different tradeoffs.
Usage ¶
// Generate a random session key
sk, err := session_key.GenerateSessionKey()
if err != nil {
log.Fatal(err)
}
// Parse a session key from wire format
sk, remainder, err := session_key.ReadSessionKey(data)
// Constant-time comparison (safe for cryptographic use)
if sk.Equal(other) { ... }
// Secure zeroing when done
sk.Zeroize()
Index ¶
- Constants
- type SessionKey
- func FromBase64(s string) (SessionKey, error)
- func FromHex(s string) (SessionKey, error)
- func GenerateSessionKey() (SessionKey, error)
- func NewSessionKey(data []byte) (sessionKey *SessionKey, remainder []byte, err error)
- func NewSessionKeyFromArray(data [SESSION_KEY_SIZE]byte) SessionKey
- func ReadSessionKey(bytes []byte) (sessionKey SessionKey, remainder []byte, err error)
- func (sk SessionKey) Bytes() []byte
- func (sk SessionKey) Equal(other SessionKey) bool
- func (sk SessionKey) IsValid() bool
- func (sk SessionKey) IsZero() bool
- func (sk SessionKey) MarshalBinary() ([]byte, error)
- func (sk *SessionKey) ReadFrom(r io.Reader) (int64, error)
- func (sk *SessionKey) SetBytes(data []byte) error
- func (sk SessionKey) String() string
- func (sk *SessionKey) UnmarshalBinary(data []byte) error
- func (sk SessionKey) Validate() error
- func (sk SessionKey) WriteTo(w io.Writer) (int64, error)
- func (sk *SessionKey) Zeroize()
Constants ¶
const SESSION_KEY_SIZE = 32
SESSION_KEY_SIZE defines the size of an I2P SessionKey in bytes. As specified in the I2P common structures specification.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type SessionKey ¶
type SessionKey [SESSION_KEY_SIZE]byte
SessionKey is the representation of an I2P SessionKey.
https://geti2p.net/spec/common-structures#sessionkey
func FromBase64 ¶ added in v0.1.5
func FromBase64(s string) (SessionKey, error)
FromBase64 parses a standard base64-encoded string (with or without padding) into a SessionKey. The decoded bytes must be exactly SESSION_KEY_SIZE.
func FromHex ¶ added in v0.1.5
func FromHex(s string) (SessionKey, error)
FromHex parses a lowercase or uppercase hex-encoded string into a SessionKey. The string must encode exactly SESSION_KEY_SIZE bytes (64 hex characters). This is the symmetric counterpart to String().
func GenerateSessionKey ¶ added in v0.1.5
func GenerateSessionKey() (SessionKey, error)
GenerateSessionKey creates a new SessionKey filled with cryptographically secure random bytes from crypto/rand. This is the recommended way to create new session keys for AES-256 encryption.
func NewSessionKey ¶
func NewSessionKey(data []byte) (sessionKey *SessionKey, remainder []byte, err error)
NewSessionKey creates a new *SessionKey from []byte using ReadSessionKey. Returns a pointer to SessionKey unlike ReadSessionKey.
func NewSessionKeyFromArray ¶ added in v0.1.5
func NewSessionKeyFromArray(data [SESSION_KEY_SIZE]byte) SessionKey
NewSessionKeyFromArray creates a SessionKey from a fixed-size byte array. This provides zero-copy construction when a [SESSION_KEY_SIZE]byte is already available.
func ReadSessionKey ¶
func ReadSessionKey(bytes []byte) (sessionKey SessionKey, remainder []byte, err error)
ReadSessionKey returns SessionKey from a []byte. The remaining bytes after the specified length are also returned. Returns an error if the data is too short to contain a valid SessionKey.
func (SessionKey) Bytes ¶ added in v0.1.5
func (sk SessionKey) Bytes() []byte
Bytes returns the SessionKey as a byte slice.
Because Bytes uses a value receiver, the returned slice is backed by a copy of the key array. Mutations to the returned slice do NOT affect this SessionKey, and zeroing the returned slice does NOT erase this key's material. To securely erase key material, call Zeroize() on the original SessionKey pointer.
func (SessionKey) Equal ¶ added in v0.1.5
func (sk SessionKey) Equal(other SessionKey) bool
Equal checks if two SessionKeys are equal using constant-time comparison to prevent timing side-channel attacks.
func (SessionKey) IsValid ¶ added in v0.1.6
func (sk SessionKey) IsValid() bool
IsValid returns true if the SessionKey is properly initialized (not all zeros). This is a convenience method equivalent to Validate() == nil.
func (SessionKey) IsZero ¶ added in v0.1.5
func (sk SessionKey) IsZero() bool
IsZero returns true if the SessionKey is all zeros (uninitialized).
func (SessionKey) MarshalBinary ¶ added in v0.1.5
func (sk SessionKey) MarshalBinary() ([]byte, error)
MarshalBinary implements encoding.BinaryMarshaler. It returns a copy of the SessionKey's bytes.
func (*SessionKey) ReadFrom ¶ added in v0.1.5
func (sk *SessionKey) ReadFrom(r io.Reader) (int64, error)
ReadFrom reads exactly SESSION_KEY_SIZE bytes from r into the SessionKey. Implements io.ReaderFrom. Returns the number of bytes read and any error. Use this to avoid allocating an intermediate buffer when reading from a net.Conn or bytes.Reader in protocol-level code.
func (*SessionKey) SetBytes ¶ added in v0.1.5
func (sk *SessionKey) SetBytes(data []byte) error
SetBytes sets the SessionKey value from a byte slice. The input must be exactly SESSION_KEY_SIZE bytes long.
If the input slice may contain trailing bytes (e.g. when parsing from a network buffer), use ReadSessionKey instead — it accepts len >= SESSION_KEY_SIZE and returns the remaining bytes as the second return value.
func (SessionKey) String ¶ added in v0.1.5
func (sk SessionKey) String() string
String returns a hex representation of the SessionKey for debugging.
func (*SessionKey) UnmarshalBinary ¶ added in v0.1.5
func (sk *SessionKey) UnmarshalBinary(data []byte) error
UnmarshalBinary implements encoding.BinaryUnmarshaler. The input must be exactly SESSION_KEY_SIZE (32) bytes.
func (SessionKey) Validate ¶ added in v0.1.6
func (sk SessionKey) Validate() error
Validate returns an error if the SessionKey is uninitialized (all zeros). Per the project convention, a zero session key is invalid and cannot be used for cryptographic operations.
func (SessionKey) WriteTo ¶ added in v0.1.5
func (sk SessionKey) WriteTo(w io.Writer) (int64, error)
WriteTo writes the SESSION_KEY_SIZE bytes of the SessionKey to w. Implements io.WriterTo. Returns the number of bytes written and any error.
func (*SessionKey) Zeroize ¶ added in v0.1.5
func (sk *SessionKey) Zeroize()
Zeroize overwrites the SessionKey with zeros, erasing key material from memory. Call this when the key is no longer needed to limit exposure of sensitive material. Note: Go's garbage collector may have already copied the value elsewhere; this is a best-effort defense-in-depth measure.
Source Files