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