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.1.0 in preparation), not externally audited, and not ready for production use. The envelope format is not frozen until 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.