session

Documentation

Overview

Package session provides secure passphrase caching via OS keyring.

Security Model:

This package uses zalando/go-keyring to store vault passphrases in the OS keyring (macOS Keychain, Linux GNOME Keyring via D-Bus Secret Service, or Windows Credential Manager). The security properties are:

1. Encryption at Rest: All secrets are encrypted at rest by the OS keyring using AES-256 (macOS Keychain) or equivalent mechanisms.

2. Transport Security:

• macOS: Secret passed via stdin to /usr/bin/security CLI (not visible in ps)

• Linux: D-Bus Secret Service API transmits secret as bytes. D-Bus is local IPC; same-user processes can typically access session bus.

• Windows: Credential Manager API

  3. Access Control: OS keyring requires user authentication to unlock. The keyring typically prompts for password on first access per session.

Threat Model Considerations:

• Local user access: OS keyring provides appropriate protection against other local users (file permissions, user-specific keyring).
• Memory exposure: Passphrase exists in process memory during keyring operations - unavoidable with any keyring integration.
• D-Bus interception (Linux): D-Bus is not encrypted by default for local IPC. However, accessing D-Bus secrets requires the same user or specific system configuration. If an attacker can sniff D-Bus messages, they typically already have equivalent access to the user's session.

Application-Level Encryption:

In addition to OS keyring encryption, passphrases are encrypted with AES-256-GCM before keyring storage. The encryption key is derived from the vault directory path using PBKDF2-SHA256 (600,000 iterations). This provides defense-in-depth: even if the keyring blob is extracted, the passphrase remains encrypted without knowledge of the vault path.

Backward Compatibility:

Sessions stored in the legacy plaintext format (with a "passphrase" JSON field) are still readable. On load, old-format sessions are automatically re-encrypted and saved in the new format.

See: https://github.com/zalando/go-keyring for library details.

Index

• Variables
• func ClearSession(vaultDir string) error
• func IsSessionExpired(vaultDir string) bool
• func LoadPassphrase(vaultDir string) (string, error)
• func LoadPassphraseWithTouchID(ctx context.Context, vaultDir string) (string, error)
• func SavePassphrase(vaultDir string, passphrase string, ttl time.Duration) error
• func SetBiometricAuthenticator(a BiometricAuthenticator)
• type BiometricAuthenticator
  • func DefaultBiometricAuthenticator() BiometricAuthenticator

Variables

var ErrBiometricFailed = errors.New("biometric authentication failed")

var ErrBiometricNotAvailable = errors.New("biometric authentication not available")

Functions

func ClearSession

func ClearSession(vaultDir string) error

func IsSessionExpired

func IsSessionExpired(vaultDir string) bool

func LoadPassphrase

func LoadPassphrase(vaultDir string) (string, error)

func LoadPassphraseWithTouchID

func LoadPassphraseWithTouchID(ctx context.Context, vaultDir string) (string, error)

func SavePassphrase

func SavePassphrase(vaultDir string, passphrase string, ttl time.Duration) error

func SetBiometricAuthenticator

func SetBiometricAuthenticator(a BiometricAuthenticator)

Types

type BiometricAuthenticator

type BiometricAuthenticator interface {
	Authenticate(ctx context.Context, reason string) error
	IsAvailable() bool
}

func DefaultBiometricAuthenticator

func DefaultBiometricAuthenticator() BiometricAuthenticator