Stash Zerokms

ZeroKMS: keysets, clients, and key management

ZeroKMS is the key service behind every CipherStash Stack operation. This skill is the canonical description of its access model. Other skills (stash-edge, stash-deployment, stash-cli, stash-postgres, stash-supabase) touch credentials and keysets in passing; where their wording and this skill disagree, this skill wins.

Authentication and regions (see stash-auth)

ZeroKMS accepts exactly one credential: a CipherStash service token — a short-lived signed JWT minted by CTS, the CipherStash token service. Access keys and IdP JWTs are never sent to ZeroKMS directly; they are exchanged at CTS for a service token first. The auth strategies do this for you — stash-auth is the canonical skill for that whole surface (strategies, CS_* variables, token contents, failure codes).

ZeroKMS runs in a number of regions (the current list: stash auth regions, or the table in stash-auth). Your workspace's region is part of its CRN (crn:<region>.<provider>:<workspace-id>), and CTS resolves the matching ZeroKMS endpoint and stamps it into the service token — the client discovers where ZeroKMS is from the token itself. You never configure a ZeroKMS URL, which is also why the CS_*_HOST override variables are debug-only and must not appear in CI or examples.

The model in one paragraph

Every value is encrypted under a keyset. A client (an application credential with its own client key) is bound to one keyset — the one named in its config (config.keyset) or, when omitted, its default keyset, the one it was created against — and can additionally be granted access to others. The routing is asymmetric, and everything below follows from it:

• Encrypt and query always use the client's bound keyset. Search terms are produced with a per-keyset index key the client loads from ZeroKMS at initialization. A client whose bound keyset is unreachable (no grant, revoked, disabled) fails loudly right there — construction, encrypt, and query alike.
• Decrypt follows each payload's own keyset, whichever client wrote it, and succeeds for any keyset the decrypting client is granted. A payload under a keyset the client has no grant for fails loudly at the ZeroKMS round trip (404).

Two corollaries that follow directly, and that agents get wrong most often:

1. "Same credentials everywhere" is stronger than what's required. Two different clients — each with its own client key — interoperate completely, search included, as long as both are bound to the same keyset. A backfill job and the deployed app may use different access keys; what must match is the keyset the operations run under, not the credential strings. Be precise about how that keyset is chosen: when an operation names one (config.keyset), it's that keyset; when it doesn't, ZeroKMS uses that client's default keyset — the keyset the client was bound to when it was created. So two clients that both omit config.keyset only interoperate if their default keysets are the same keyset.
2. One silent failure mode exists, and it is exactly the asymmetry above. A reader that is granted the writer's keyset but bound to a different one decrypts the writer's rows fine — while its query terms derive under its own bound keyset and match nothing: zero rows, no error. So "decrypt works but search returns zero rows" has three suspects, in order: the reader's bound keyset vs the writer's (this skill), the extractor index (stash-indexing), the operand cast / predicate form (stash-postgres). What can not cause it is the credential string — every client bound to the same keyset derives the same index key. The same-keyset rule therefore binds writers and query readers; decrypt-only readers need just a grant.

The key hierarchy

Four levels, each narrowing scope; no single component holds enough material to derive a data key alone.

ZeroKMS uses proxy symmetric re-encryption: it sends key seeds, never usable keys, and the client combines a seed with its own client key to derive each per-value data key. Because the data key requires both halves:

• ZeroKMS never possesses a usable data key (zero-knowledge).
• Revoking one client blocks all of its future key operations, instantly and without re-encryption. ZeroKMS stops issuing seeds to that client; its client key cannot derive data keys from seeds issued to other clients. No effect on other clients. Like any key service, revocation is not retroactive — plaintext or per-value data keys the client already held in memory are beyond recall — but because keys are per value, the blast radius is exactly the values that client already accessed, never the keyspace.

Keysets

A keyset is the isolation unit: data encrypted under one keyset can never be decrypted or queried with another keyset's keys. Every operation runs under the data's own keyset, and only clients granted that keyset can perform it. Keysets belong to a workspace.

• Naming: 1–64 characters, ASCII letters/digits plus _, -, /. The name default is reserved (case-insensitively) for the workspace default keyset. Descriptions are 1–256 characters.
• The workspace default keyset: every workspace has exactly one, named default, created automatically the first time it's needed. It cannot be renamed or disabled. A client created without naming a keyset is bound to it.
• Every client also has its own default keyset: the keyset it was bound to at creation (default unless another was named). An operation that doesn't specify a keyset resolves to the client's default keyset — not automatically the workspace's. The two coincide when the client was created without naming a keyset — as with the profile credentials in a dev environment — which is why single-tenant apps that never mention keysets still work. But a client created against tenant-a defaults to tenant-a, and a client with no default at all (possible via the API) gets 404 — "Client (…) has no default keyset" on any keyset-less operation.
• Disabled keysets: a keyset (other than the default) can be disabled as a reversible kill-switch. While disabled, every operation under it fails for every client with 403 — "Keyset disabled: request could not be processed because the keyset has been disabled". Re-enabling restores access; no data is touched.

Clients and grants

A client is a credential identity in ZeroKMS: it has an id, a client key (generated at creation, returned once, held only by the application), and a set of keyset grants.

• Creating a client binds it to one keyset immediately (the default keyset unless another is named at creation).
• Grant adds access to a further keyset. Revoke removes one grant. Deleting a client removes the client and all of its grants.
• Grants are per (client, keyset) pair. There is no wildcard and no transitive access.

The device client is a special case worth knowing about: after stash auth login, the CLI generates a device identity (a device identifier and name, stored in the profile), provisions a client in ZeroKMS named after the device — bound to the workspace default keyset, at most one device client per device per workspace — and persists the resulting key to ~/.cipherstash/secretkey.json. That key is a standard client key; only its encapsulation differs (a JSON profile file holding the client id and key material, rather than the hex CS_CLIENT_KEY form a deployed app uses). It is what makes local dev work with no environment variables: everything this skill says about clients — the default keyset, grants, revocation — applies to the device client like any other. The profile files are read only by the CLI and the auth strategies; agents never read them directly (see stash-auth).

Manage all of this in the dashboard (the _ resolves to your selected workspace). The underlying ZeroKMS API, for automation:

/list-clients is the check an agent can run to answer "does this client have a grant for that keyset?" — it returns each client with the keyset ids it can reach.

Scope strings in existing tokens may use the legacy dataset: prefix (dataset:create, dataset:grant, …) — it is the same permission family as keyset:; ZeroKMS accepts both spellings. Scopes are assigned by CTS when the service token is minted, based on the credential's role — see stash-auth.