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, but only on the signed macOS bundle; a Mac without a Secure Enclave falls back to the Keychain, and a build that is not the signed bundle is refused. See On macOS below.
• 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.

On macOS

On macOS, which store holds the key — and whether a device key can be created at all — depends on the build you are running and the machine you run it on. Creating a key in the Secure Enclave needs the keychain-access-groups entitlement, and only the signed macOS bundle carries it. See verifying a release download for how to get that bundle and check its signature.

There are three outcomes. custodian init, custodian recover and custodian device enrol each name the one you have hit before they enrol anything:

• The signed bundle, on a Mac with a Secure Enclave — the key is created in the enclave:

  Secure Enclave — the device private key is non-exportable and every use is gated by a biometric or passcode prompt

• A Mac with no Secure Enclave (an older Intel Mac) — the key is held by the system in software instead, which is weaker, and the command says so:

  Keychain (this machine has no Secure Enclave) — the device private key is held by the system in software, and every use is gated by a biometric or passcode prompt

• A build that is not the signed bundle (a bare binary, or one without the entitlement) — no device key is created, and the command refuses:

  Secure Enclave present, but this build is not admitted to it (missing keychain-access-groups entitlement) — install the signed macOS bundle; no device key can be created until then

  This is not the same as "no Secure Enclave": the machine has one, but this build is not admitted to it. Install the signed bundle and run the command again.

The provider recorded on the enrolled device is secure_enclave only when the enclave actually held the key; on the Keychain fallback no provider is recorded.

If a macOS device-key operation fails, the message names the status the system returned — for a build that lacks the entitlement, errSecMissingEntitlement — rather than reporting that a call returned nothing.

Every use of a Secure Enclave key is gated by a biometric or passcode prompt. If you decline that prompt, the key agreement or signature the command needed fails, and any command that uses the device key reports it with this message, ending with the status the system returned:

the presence prompt was declined, so this device unwrapped no key (SecKeyCopyKeyExchangeResult failed: …)

the presence prompt was declined, so this device unwrapped no key (SecKeyCreateSignature failed: …)

Nothing was unwrapped. Run the command again and approve the prompt. custodian file get reports the same case in its own words.

The SecKeyCopyKeyExchangeResult form appears whenever the key agreement fails. The SecKeyCreateSignature form appears only when the system reports that the prompt was cancelled or that authentication failed.

Signing is used only by custodian device approve. If signing fails for any other reason, custodian device approve stops with this message instead:

error: SecKeyCreateSignature failed signing with the device key (<domain> <code>)

The part in brackets is the error domain and code the system returned, and it names what the system refused. If the system returned no error, the message ends after device key. This is not a declined prompt, so running the command again and approving the prompt will not fix it.

Approve the new machine from another already-enrolled machine instead. Run custodian device approve there with the same request line. Any live device in the vault can approve, except an unattended device backed by AWS KMS. The new machine's request does not expire. If you no longer have the request line, run the same custodian device enrol --label <name> --provider <provider> command on the new machine again. It reuses the key it already generated and prints the same request.

If your Mac is the only enrolled machine in the vault, there is no other machine to approve from:

• Your Mac is still enrolled. custodian device approve unwraps the master key through your Mac's device key before it signs, and it uploads nothing when signing fails. No other command signs with the device key, so this failure changes nothing else on your Mac.
• There is no other way to add the new machine at this release. Every new device, including an unattended one, joins only through custodian device approve on an already-enrolled machine. Keep the new machine's request line; it does not expire. Once what the part in brackets names has been dealt with, run custodian device approve on your Mac again with the same request line.
• Do not revoke your Mac so that you can use custodian recover. Recovery runs only once the vault has no live device left. Revoking the last live device is irreversible: if no recovery envelope was ever written for the vault, every client-encrypted value in it becomes unreadable, with no way back. See custodian device revoke.

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 …

On macOS the Secure Enclave line above is the outcome on the signed macOS bundle on a Mac with a Secure Enclave; on other macOS builds and machines the store line differs, and a build that is not the signed bundle cannot enrol at all — see On macOS.

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.