Skip to content

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 (x25519 recipient type).
  • Key derivation: HKDF-SHA-256.
  • Authenticated encryption: XChaCha20-Poly1305.
  • Signatures: Ed25519 for x25519 device keys. p256 device 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:

  1. Native keypair generated by vaultfold, protected per ADR 0009.
  2. 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.
  3. Hardware tokens via FIDO2 hmac-secret/PRF or PIV (ADR 0009).
  4. 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 age directly 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.