Enrolling and managing devices

A device is a machine that holds its own wrapped copy of the vault's master key, so it can read the vault's encrypted values. The first device is enrolled by custodian init; this page covers listing devices, adding another machine, and revoking one.

Every command here needs an operator credential and reads the vault's devices, so be signed in first.

custodian device list

Lists every device the vault holds, revoked ones included and marked, each with the guarantee its key store gives. The machine you are running on is marked, and its row carries the more specific statement your platform can make about the store it actually found.

custodian device list --vault acme

Vault "acme" at https://custodian.example.com — 2 devices

* dev_3Kp9…  ops-laptop  [secure_enclave · holding]  — (this device)
    Secure Enclave — the device private key is non-exportable and every use is gated by a biometric or passcode prompt
    enrolled 2026-08-20T09:14:00Z by (first device, no approver) · last seen 2026-08-28T08:02:00Z

  dev_7Rt2…  runner  [kms_task_role · holding]
    AWS KMS under a task role — the device key is an AWS KMS key the container's task role may use; unwrapping happens inside KMS and the key itself never enters this tool's memory. The downgrade, stated plainly: AWS can unwrap this copy, so this device is protected by a cloud provider's access control rather than by hardware anyone holds — materially weaker than a hardware module, and the price of running unattended — not yet exercised on real hardware — validate on a machine with this store before relying on it
    enrolled 2026-08-21T10:00:00Z by dev_3Kp9… · last seen 2026-08-28T07:55:00Z

--json emits the same data for scripting.

The store that holds the key

When you enrol a device, its key store is chosen by the platform you are on:

• macOS → the Secure Enclave
• Windows → a Trusted Platform Module, or the Windows Data Protection API
• Linux → a Trusted Platform Module, or the Secret Service (GNOME Keyring or KDE Wallet)

Each store carries a different guarantee, and Custodian states it plainly — at enrolment and afterwards in device list. The two hardware-backed stores never let the key into the tool's memory; the two software stores do, and say so:

• Secure Enclave — the device private key is generated in the enclave, is non-exportable, and every private-key operation happens inside it; the key never enters this tool's memory
• Trusted Platform Module — the device private key is generated in the module, is non-exportable, and the key agreement and signature happen inside it; the key never enters this tool's memory — not yet exercised on real hardware — validate on a machine with this store before relying on it
• Windows Data Protection API — the device private key is generated in software and held encrypted to your Windows user; it is decrypted into this tool's memory each time it is used — not yet exercised on real hardware — validate on a machine with this store before relying on it
• Secret Service (GNOME Keyring or KDE Wallet) — the device private key is protected by your login session and released to this tool's memory on use; it offers little against local compromise — not yet exercised on real hardware — validate on a machine with this store before relying on it

Every store but the Secure Enclave also ends its line with not yet exercised on real hardware — validate on a machine with this store before relying on it. At this release those stores have been proven against the shared key-handling code but not yet against a real module, keyring or KMS key, so Custodian will not claim the store held your key on that strength: validate on your own machine before you depend on the guarantee.

For a server with nobody at the keyboard, there is a separate store backed by AWS KMS — see enrolling an unattended machine.

custodian device enrol — adding a machine

Adding a second machine takes two machines: the new one asks to join, and an already-enrolled one approves. Nothing is re-encrypted, however many devices the vault already has.

On the new machine, signed in with an operator token:

custodian device enrol --label "finance-laptop" --provider secure_enclave

• --label <name> names the new device (required).
• --provider <provider> is the provider tag to enrol this device under (required). It must be one of secure_enclave, tpm, dpapi, secret_service or kms_task_role. For every value but kms_task_role, the key store itself is still chosen by the platform you are on (above); the flag records the tag rather than picking the store. kms_task_role is the headless path.

The command generates this machine's key pair, prints a single approval request line, and a fingerprint of the public key to read aloud:

Enrolling "finance-laptop" with provider secure_enclave.
Device key store: Secure Enclave (holding; presence gate: biometric or passcode)
  Secure Enclave — the device private key is non-exportable and every use is gated by a biometric or passcode prompt

Approval request — copy this whole line to an already-enrolled machine and run
`custodian device approve <request>` there:

  eyJsYWJlbCI6…

Public-key fingerprint — read this aloud to the operator approving, who will
compare it against the value shown on the approving machine before acting:

  a1b2 c3d4 e5f6 …

It then waits for the new device to be approved and appear. If approval takes too long, it stops without changing anything; run custodian device enrol --resume on the new machine once it has been approved to pick the ceremony up.

custodian device approve — authorising the new machine

On an already-enrolled machine, paste the request the new machine printed:

custodian device approve eyJsYWJlbCI6…

It shows you the new device's label, provider and fingerprint, and asks you to type the first part of the fingerprint back. Compare that fingerprint against the one on the new machine's own screen — not against anything else. If they differ, stop: the request was substituted along the way.

Approving a new device:
  Label:       finance-laptop
  Provider:    secure_enclave (holding)
  Fingerprint: a1b2 c3d4 e5f6 …
  Approver:    dev_3Kp9… (this machine)

Compare this fingerprint against the one shown on the NEW machine's screen — not against
anything else. If they differ, stop: the request was substituted in transit.

To confirm they match, type the first part of the fingerprint exactly (a1b2 c3d4):
>

Once confirmed, the approving machine unwraps the master key locally, re-wraps it for the new device, and uploads the approval:

Approved "finance-laptop" (dev_9Xy4…).
  Unwrapped the master key locally, through this device's Secure Enclave.
  Re-wrapped it for the new device — no records were re-encrypted.
  Uploaded the approval, signed by dev_3Kp9…. The new device can now read the vault's records.

An unattended device backed by AWS KMS holds no signing key and cannot approve another device; approve from an operator's own enrolled machine.

custodian device revoke — retiring a machine

custodian device revoke dev_9Xy4… --vault acme

Revoking removes that device's wrapped copy of the master key. To guard against retiring the wrong line of a list, you must type the device's label back to confirm.

Revoke tells you plainly what it did and did not do:

• From its next run, the revoked device can no longer decrypt encrypted values.
• Its API credential still works, and still reads plain, masked and tokenised values. To stop that, revoke the principal with custodian principal revoke.
• Past access is not undone: a machine that already unwrapped the master key still holds it.

Revoking the last live device takes a second confirmation, because what it does depends on whether a recovery envelope was ever written:

────────────────────────────────────────────────────────────────────────
  This is the LAST live device in the vault. Revoking it is irreversible, and
  which of two things it does depends on whether a recovery envelope was ever
  written for this vault:

    - if one was, that envelope and its recovery code become the ONLY route back
      to the master key;
    - if none was, every client-encrypted value in the vault becomes unreadable
      from this point on, with no way back.

  custodian cannot tell which applies before it acts; the result below states
  which one occurred.
────────────────────────────────────────────────────────────────────────

Revoke is idempotent: revoking an already-revoked device changes nothing and reports the original revocation time.