KeyForge

Encryption and signing key lifecycle for Go applications: envelope encryption, automatic rotation without re-encrypting stored data, and controlled retirement and destruction.

Status: pre-release (v0.2.0), not externally audited, and not ready for production use. The envelope format is frozen from v0.1.0. See the threat model for what it defends and where it stops.

What it does

• Envelope encryption. Data is encrypted with a data key (DEK); data keys are wrapped by a key-encryption key (KEK) that a provider holds. Every ciphertext records which key version wrapped it.
• Rotation without re-encryption. Rotating a KEK re-wraps data keys; the stored data is not rewritten. Old key versions stay readable until nothing references them.
• Pluggable providers. A local keyring for development and single-host deployments, and a cloud KMS interface for managed key services.
• Controlled destruction. Retiring or destroying a key is a separate, audited step that a caller-supplied guard can veto, so data under a legal hold or other retention is never made unrecoverable by accident.
• Crypto-shredding. Per-subject keys make erasure a key destruction that also covers backups.

What it is not

• Not a secret store. Use a secret manager such as omnivault to hold secrets and to supply the local provider's root key.
• Not a KMS. keyforge wraps and manages keys through providers; it does not replace a managed key service or a hardware module.
• Not a cryptography library. It composes standard primitives (AES-256-GCM, HKDF-SHA-256) from the Go standard library and golang.org/x/crypto.

Quick start

sys, err := embedded.Open(ctx, embedded.Options{
	Dir:  "/var/lib/myapp/keyforge",
	Root: local.FileSource("/etc/keyforge/root.key"),
	Purposes: map[keyforge.Purpose]embedded.PurposeOptions{"session-secrets": {}},
})
if err != nil {
	return err
}
defer sys.Close()

sealed, err := sys.Client.Encrypt(ctx, "session-secrets", []byte("token-value"), []byte("user:42"))
plaintext, _, err := sys.Client.Decrypt(ctx, "session-secrets", sealed, []byte("user:42"))

Getting started covers the root key, running the lifecycle jobs and the control plane.

Packages

Package	Role
keyforge (root)	The client: Encrypt, EncryptFor, EncryptInline, Decrypt, Reencrypt
embedded	Single-host setup from a directory and a root key
envelope, algorithm	The ciphertext format and the algorithm registry
provider, provider/local	Key holders, and the keyring-file provider
registry, sqlstore	The record of keys, and its SQLite and PostgreSQL store (Ent)
rotate, jobs	Rotation, re-wrapping, retirement, emergencies and erasure, and their scheduler
service, cli, cmd/keyforge	The HTTP control plane and the command line over it

The packages that touch key material import only the standard library and oscompat, a dependency-free module for operating-system differences, and a test enforces it.

Documentation

• Getting started
• Operations: rotation, backup, root-key escrow, retirement, emergencies and erasure
• Envelope format
• Threat model
• Product requirements
• Technical requirements
• Plan and roadmap
• Release notes and changelog
• Security policy

License

MIT.