0002: Native modern cryptography with pluggable identity backends, not GPG
- Status: accepted
- Date: 2026-09-22
Context
The obvious prior art (pass, gopass, blackbox) builds on GPG. The
gopass issue tracker shows the cost: expired keys locking users out of stores
(the single most-upvoted issue), gpg-agent and pinentry failures, Gpg4win
support load on Windows, concurrent pinentry during re-encryption, and a
trust model users do not understand. GPG's CLI is not a stable API and its
library ecosystem is uneven across the platforms we target.
age demonstrated that a small, fixed construction with a recipients model
is sufficient for this class of tool.
Decision
vaultfold implements its own encryption and signing using standard, well-reviewed primitives, and treats identity storage as a pluggable backend.
Default cipher suite (suite: 1):
- Recipient key agreement: X25519 (
x25519recipient type). - Key derivation: HKDF-SHA-256.
- Authenticated encryption: XChaCha20-Poly1305.
- Signatures: Ed25519 for
x25519device keys.p256device keys sign with ECDSA P-256 over SHA-256 (see the crypto-suites spec). - Content hashing: BLAKE3.
- Password-based key wrapping: Argon2id.
Additional recipient types in v1: p256 (ECIES over NIST P-256) so that
hardware-resident keys can be recipients (ADR 0009).
Every wrap file, event header and signature carries a suite identifier.
vault.json carries a format version. Hybrid X25519 + ML-KEM recipients are
planned as a later suite and must be addable without a format break.
Identity backends, in priority order:
- Native keypair generated by vaultfold, protected per ADR 0009.
- Import of an existing
ssh-ed25519(converted to X25519) or RSA SSH key, as onboarding sugar. This requires the private key bytes on disk; keys held only in an agent (1Password SSH agent, Secretive, YubiKey-resident SSH keys) cannot perform X25519 decryption and are rejected with a clear message. Public keys may be fetched from a forge (github.com/<user>.keys) with an explicit note that this is trust-on-first-use in the forge. - Hardware tokens via FIDO2
hmac-secret/PRF or PIV (ADR 0009). - GPG, as a compatibility backend for organisations that mandate it. It is supported, never depended on, and never the default.
Consequences
- No external binary is required for any core operation.
- Two implementations of the format must agree byte-for-byte on what is signed; the signed payload is canonical CBOR (RFC 8949 section 4.2.1).
- Keys have no expiry (ADR 0009); rotation is an explicit, additive event.
- Auditors can review a small, fixed set of constructions rather than a configurable pipeline.
Alternatives considered
- Build on GPG. Rejected for the reasons above.
- Use
agedirectly as a library. Considered; age has no signing and no P-256 recipient type, and wrapping it would still require our own envelope layer. We adopt its construction rather than its implementation. - Allow arbitrary algorithm negotiation. Rejected; agility is a versioned suite id, not a configuration surface.