logicsrc/docs/opencreds/crypto.md

OpenCreds cryptography

The normative rules are spec.md §4. This page explains why the construction is shaped the way it is, and what an implementer will get wrong if they skip a step.

The shape

master password
      │  PBKDF2-HMAC-SHA256(salt, iterations)      ← the only expensive step
      ▼
 master key (32 bytes)         never encrypts anything itself
      │
      ├─ HKDF("<ns>:vault:wrap:v1")     → wrap key      → AES-GCM → protected user key
      ├─ HKDF("<ns>:vault:auth:v1")     → auth hash     → server (hashed again there)
      └─ HKDF("<ns>:vault:recovery:v1") → recovery wrap → recovery blob

 user key (32 random bytes)    ← what every item is actually encrypted under
      │
      └─ AES-256-GCM(iv, item JSON, AAD = "<ns>:vault:item:<v>:<id>")

Why the user key is random, not derived

Because a master password change must not be a re-encryption of the vault. The user key is generated once and wrapped; changing the password re-wraps 32 bytes. Derive item keys from the password instead and every password change rewrites every item — which, on a vault of any size, is a long window in which a partial failure leaves half the vault openable by the old password and half by the new.

It also means the recovery path costs nothing extra: a second wrapping of the same 32 bytes under a random recovery key, and a forgotten password is survivable without the server learning anything it did not already hold.

Why the auth hash cannot decrypt

The wrap key and the auth hash come out of the same master key through HKDF with different labels. HKDF's guarantee is exactly this: outputs under distinct info strings are computationally independent. A server holding every auth hash it has ever seen holds nothing that helps it derive a wrap key.

That is what allows the auth hash to be sent at all. A scheme that sent the wrapping key, or anything from which it could be recovered, would be a scheme where "the server cannot read the vault" is a promise rather than a property.

Why the item id is in the AAD

Without it, a ciphertext is portable between rows. Anyone with write access to the storage — a compromised server, an operator, a leaked backup restored somewhere writable — could copy the ciphertext of a low-value login into the row of a high-value one and watch what the user does next. The user unlocks, sees the credential they expected to see under a name they trust, and uses it.

With the id bound in, that swap fails to decrypt. The tag covers the id, and the id is not in the ciphertext's control.

The version is in the AAD for the same reason at a different scale: it stops a v2 record from being replayed as a v1 record once v2 exists.

Why the KDF floor is a client-side check

KDF parameters are stored with the vault and, in a hosted deployment, are served to the client at unlock time. That makes them attacker-controlled the moment the server is compromised. A client that trusts {"iterations": 1} performs one round of PBKDF2, derives an auth hash almost free, and hands an attacker who has been capturing auth hashes an offline guessing exercise with no work factor at all.

So the floor is enforced where it matters — in the client, before deriving — and, in a database-backed deployment, again as a constraint on the column. Defence in depth on the one value the user cannot see.

Namespaces

Every label above is prefixed by the vault's declared namespace. This is not decoration. A label is compiled into the additional authenticated data of every ciphertext a vault has ever written, and into the HKDF derivation of its keys. Change a label string and every vault in the world that used it becomes undecryptable — not corrupted, not recoverable, undecryptable.

So labels are append-only in the strongest sense available: superseded by a new :v2 label, never edited. And because MarkSyncr's vault shipped with marksyncr:vault:* labels before this specification existed, the prefix is carried as a per-vault property rather than fixed by the spec. A deployed vault declares "namespace": "marksyncr" and is conformant; a new one uses opencreds.

Registered: opencreds, marksyncr. Pattern: ^[a-z][a-z0-9-]{1,31}$.

An implementation MUST reject an unregistered namespace on import unless the operator opts in, because accepting an arbitrary prefix is accepting an arbitrary derivation.

Profiles

user

Everything above. One person, one master password.

team

The vault key is random and is wrapped to each member with crypto_box_seal (X25519 anonymous sealed box) against that member's public key. The server holds one wrapped key per member and never the key. Granting access is an existing member unwrapping with their secret key and re-sealing to the new member's public key — the plaintext key exists only in memory, on a machine that was already authorized.

logicsrc credentials implements this today for .env secrets and SSH keys; see credential-sharing.md. OpenCreds adds nothing to it except the observation that the thing being wrapped can be a vault of items rather than a bag of strings.

The item envelope is identical under both profiles. That is the whole point: an item exported from a personal vault imports into a team vault without re-encoding, because only the key management differed.

Threat model difference, stated plainly. In the team profile, every member who holds the vault key can read every item in it. Revoking a member means rotating the key and re-encrypting, because the key they held is a key they may have kept. Partial sharing is not a feature of a shared key; it is a second vault.

Randomness

Every IV, salt, user key and recovery key MUST come from a cryptographic RNG (crypto.getRandomValues, crypto.randomBytes). An IV MUST NOT be reused under one key — with GCM, a repeated IV under the same key is not a weakness, it is a break, and it leaks the XOR of two plaintexts along with the authentication subkey.

Because the user key is per vault and IVs are per write, the safe construction is simply: generate a fresh 12-byte IV on every single encryption, never derive it, never count with it.

What is not covered

• Key stretching for the export passphrase uses the same PBKDF2 parameters as a vault. An export passphrase is typed once and often weaker than a master password; an implementation SHOULD say so rather than silently accepting four characters.
• Memory hygiene. Zeroing key material after use is out of scope for the format and worth doing anyway where the runtime allows it. In a browser it mostly does not.
• Side channels. Comparisons of secret-derived values (auth hashes, tags) MUST be constant-time. Everything else in the format compares public data.