crypto

Documentation

Overview

Package crypto provides credential encryption/decryption for DirIO.

Encrypted values use the format "enc:v1:<base64(nonce||ciphertext)>" so they are self-describing and backward-compatible — plaintext values (no prefix) pass through Decrypt unchanged.

Key format

All keys are expressed as "base64:<standard-base64-encoded-32-bytes>", e.g. DIRIO_ENCRYPTION_KEY="base64:AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA="

Key management (priority order)

1. DIRIO_ENCRYPTION_KEY env var. Recommended for production / container deployments.

2. Keyring file at <dataDir>/.dirio/keyring — auto-created on first run with a randomly generated key (permissions 0o600). Back this file up separately from the data directory; losing it means encrypted credentials cannot be recovered without key rotation.

Key rotation

Zero-downtime rotation — new writes use the new key while old encrypted values remain readable via ordered fallback through previous keys:

1. Generate a new key (`dirio key generate`).
2. Move the current key to DIRIO_PREVIOUS_ENCRYPTION_KEYS (comma-separated) or to subsequent lines in the keyring file.
3. Set the new key as DIRIO_ENCRYPTION_KEY / the first line of the keyring.
4. Restart — new writes use the new key, old values decrypt via fallback.
5. Optionally run `dirio rekey` to re-encrypt all values, then drop old keys.

Call Init(dataDir) once at process startup before any encrypt/decrypt operations.

Index

• Constants
• func Decrypt(s string) (string, error)
• func Enabled() bool
• func Encrypt(plaintext string) (string, error)
• func GenerateDirIOKey(prefix KeyPrefix) (accessKey, secretKey string, err error)
• func GenerateKey() (string, error)
• func Init(dataDir string) error
• func IsEncrypted(s string) bool
• func RotateKeyring(dataDir string) (string, error)
• type KeyPrefix
• type Manager
  • func (m *Manager) Decrypt(s string) (string, error)
  • func (m *Manager) Enabled() bool
  • func (m *Manager) Encrypt(plaintext string) (string, error)

Constants

const (
	// EnvKey is the environment variable name for the current 32-byte master key.
	EnvKey = "DIRIO_ENCRYPTION_KEY"

	// EnvPreviousKeys is a comma-separated list of previous keys used as
	// decryption fallbacks during key rotation.
	EnvPreviousKeys = "DIRIO_PREVIOUS_ENCRYPTION_KEYS"
)

Functions

func Decrypt

func Decrypt(s string) (string, error)

Decrypt decrypts s using the package-level manager.

func Enabled

func Enabled() bool

Enabled reports whether the package-level manager has an active key.

func Encrypt

func Encrypt(plaintext string) (string, error)

Encrypt encrypts plaintext using the package-level manager.

func GenerateDirIOKey

func GenerateDirIOKey(prefix KeyPrefix) (accessKey, secretKey string, err error)

GenerateDirIOKey creates a formatted Access Key and Secret Key pair

func GenerateKey

func GenerateKey() (string, error)

GenerateKey generates a new random 32-byte key and returns it in "base64:<encoded>" format, ready to paste into a keyring file or env var.

func Init

func Init(dataDir string) error

Init initialises the package-level encryption manager.

Key selection priority:

1. DIRIO_ENCRYPTION_KEY env var (+ optional DIRIO_PREVIOUS_ENCRYPTION_KEYS)
2. <dataDir>/.dirio/keyring file — loaded if present, auto-generated if not

Call this once at startup, before any data config or metadata operations.

func IsEncrypted

func IsEncrypted(s string) bool

IsEncrypted reports whether s carries the enc:v1: prefix.

func RotateKeyring

func RotateKeyring(dataDir string) (string, error)

RotateKeyring generates a new key and prepends it to the keyring file, shifting the current key down as the first previous-key fallback. Returns the new key string so callers can display it. Safe to call even if no keyring file exists yet.

Types

type KeyPrefix

type KeyPrefix string

KeyPrefix defines our custom enum type for different access levels

const (
	// PrefixUser represents standard robotic entity access
	PrefixUser KeyPrefix = "DIOA"
	// PrefixSystem represents internal system/root access
	PrefixSystem KeyPrefix = "DIOR"
	// PrefixService represents automated service-to-service access
	PrefixService KeyPrefix = "DIOS"
)

type Manager

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

Manager handles AES-256-GCM encryption and decryption of credential strings. A zero-value Manager (nil key) is a safe no-op.

func (*Manager) Decrypt

func (m *Manager) Decrypt(s string) (string, error)

Decrypt decrypts an "enc:v1:<base64>" value. Tries the current key first, then each previous key in order — allowing seamless key rotation without re-encrypting existing values immediately. Values without the prefix are returned as-is (plaintext passthrough).

func (*Manager) Enabled

func (m *Manager) Enabled() bool

Enabled reports whether the manager has an active encryption key.

func (*Manager) Encrypt

func (m *Manager) Encrypt(plaintext string) (string, error)

Encrypt encrypts plaintext with AES-256-GCM and returns "enc:v1:<base64>". Always uses the current key. Returns plaintext unchanged when not enabled.