session

Documentation

Overview

Package session implements Hush session key exchange, authentication, and session lifecycle management.

Package session provides session negotiation, key exchange, and session management for Hush.

Index

• Constants
• func Decrypt(key []byte, data []byte) ([]byte, error)
• func DeriveSessionKey(sharedSecret, apiKeySecret []byte) ([]byte, error)
• func Encrypt(key []byte, plaintext []byte) ([]byte, error)
• func GenerateKeyPair() (*ecdh.PrivateKey, error)
• func RandomBytes(n int) ([]byte, error)
• func SharedSecret(priv *ecdh.PrivateKey, pub *ecdh.PublicKey) ([]byte, error)
• type APIKey
  • func GenerateAPIKey() (*APIKey, error)
• type APIKeyStore
• type MapKeyStore
  • func (m MapKeyStore) Get(id string) []byte
• type Session
  • func NegotiateClient(ctx context.Context, stream io.ReadWriter, key *APIKey, ...) (*Session, error)
  • func NegotiateServer(ctx context.Context, stream io.ReadWriter, serverPriv *ecdh.PrivateKey, ...) (*Session, error)
  • func NewSession(id uint64, apiKeyID string, key []byte) *Session
  • func (s *Session) Touch()
• type SessionConfig
• type SessionStore
  • func NewSessionStore(config SessionConfig) *SessionStore
  • func (ss *SessionStore) Config() SessionConfig
  • func (ss *SessionStore) Delete(id uint64)
  • func (ss *SessionStore) GC()
  • func (ss *SessionStore) Get(id uint64) (*Session, bool)
  • func (ss *SessionStore) IsExpired(s *Session) bool
  • func (ss *SessionStore) IsIdleDead(s *Session) bool
  • func (ss *SessionStore) Len() int
  • func (ss *SessionStore) Set(s *Session)

Constants

const (
	KeySize    = 32
	NonceSize  = 12
	TagSize    = 16
	PubKeySize = 32
)

const (
	DefaultIdleTimeout = 5 * time.Minute
	DefaultMaxLifetime = 24 * time.Hour
	DefaultGCInterval  = 1 * time.Minute
)

Default timeouts (match the original hardcoded values).

Functions

func Decrypt

func Decrypt(key []byte, data []byte) ([]byte, error)

Decrypt decrypts data produced by Encrypt.

func DeriveSessionKey

func DeriveSessionKey(sharedSecret, apiKeySecret []byte) ([]byte, error)

DeriveSessionKey derives a 256-bit AES key from the ECDH shared secret and the pre-shared API key secret (PSK) using HKDF-SHA256.

func Encrypt

func Encrypt(key []byte, plaintext []byte) ([]byte, error)

Encrypt encrypts plaintext with AES-256-GCM using a random nonce. Returns nonce || ciphertext (ciphertext includes the auth tag).

func GenerateKeyPair

func GenerateKeyPair() (*ecdh.PrivateKey, error)

GenerateKeyPair creates a new X25519 key pair for session key exchange.

func RandomBytes

func RandomBytes(n int) ([]byte, error)

RandomBytes generates n cryptographically random bytes.

func SharedSecret

func SharedSecret(priv *ecdh.PrivateKey, pub *ecdh.PublicKey) ([]byte, error)

SharedSecret computes the ECDH shared secret from a private key and a public key.

Types

type APIKey

type APIKey struct {
	ID     string // public identifier
	Secret []byte // 32-byte secret key
}

APIKey represents a pre-shared API key used for authentication.

func GenerateAPIKey

func GenerateAPIKey() (*APIKey, error)

GenerateAPIKey creates a new random API key (32 bytes hex-encoded).

type APIKeyStore

type APIKeyStore interface {
	Get(id string) []byte
}

APIKeyStore is an interface for looking up API keys by ID.

type MapKeyStore

type MapKeyStore map[string][]byte

MapKeyStore is a simple in-memory API key store backed by a map.

func (MapKeyStore) Get

func (m MapKeyStore) Get(id string) []byte

type Session

type Session struct {
	ID        uint64
	APIKeyID  string
	Key       []byte // AES-256 session key (32 bytes), nil = no encryption
	CreatedAt time.Time
	LastUsed  time.Time
}

Session represents an authenticated Hush session.

func NegotiateClient

func NegotiateClient(ctx context.Context, stream io.ReadWriter, key *APIKey, clientPriv *ecdh.PrivateKey) (*Session, error)

NegotiateClient performs the client side of the session handshake over a QUIC stream. If key is nil, performs an anonymous handshake (no API key).

func NegotiateServer

func NegotiateServer(ctx context.Context, stream io.ReadWriter, serverPriv *ecdh.PrivateKey, keyStore APIKeyStore, nextSessionID func() uint64) (*Session, error)

NegotiateServer performs the server side of the session handshake over a QUIC stream.

func NewSession

func NewSession(id uint64, apiKeyID string, key []byte) *Session

NewSession creates a new session.

func (*Session) Touch

func (s *Session) Touch()

Touch updates the last-used timestamp.

type SessionConfig

type SessionConfig struct {
	IdleTimeout time.Duration
	MaxLifetime time.Duration
	GCInterval  time.Duration
}

SessionConfig controls session lifecycle and is used by SessionStore. Zero values use the defaults above.

type SessionStore

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

SessionStore is a thread-safe store for sessions with configurable timeouts.

func NewSessionStore

func NewSessionStore(config SessionConfig) *SessionStore

NewSessionStore creates a new session store with the given config. Pass SessionConfig{} for defaults.

func (*SessionStore) Config

func (ss *SessionStore) Config() SessionConfig

Config returns a copy of the store's config.

func (*SessionStore) Delete

func (ss *SessionStore) Delete(id uint64)

func (*SessionStore) GC

func (ss *SessionStore) GC()

GC removes expired sessions.

func (*SessionStore) Get

func (ss *SessionStore) Get(id uint64) (*Session, bool)

func (*SessionStore) IsExpired

func (ss *SessionStore) IsExpired(s *Session) bool

IsExpired checks if a session has exceeded its max lifetime.

func (*SessionStore) IsIdleDead

func (ss *SessionStore) IsIdleDead(s *Session) bool

IsIdleDead checks if a session has been idle long enough.

func (*SessionStore) Len

func (ss *SessionStore) Len() int

Len returns the number of active sessions.

func (*SessionStore) Set

func (ss *SessionStore) Set(s *Session)