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.
- 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.
- 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.
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.
| 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.
- 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
MIT.