custodian recover

custodian recover is the way back into a vault when every device that could read it has been lost. You paste the twenty-four word recovery code that custodian init printed when the vault was set up, and this machine is enrolled as a live reading device. The command reconstructs the vault's master key on this machine from the code and wraps it to this device's key; it does not print the key.

Before you start, you must be signed in with an operator token. The server returns the recovery envelope only to an operator, and only when the vault has no live device left — recovery is for the all-devices-lost case, not for adding a machine to a working vault. To add a machine to a vault that still has a live device, use custodian device enrol instead.

custodian recover --vault acme

Options:

• --vault <slug> — the vault to recover (required).
• --url <api> — select the deployment when you have more than one credential stored.
• --label <name> — a name for this device; defaults to the machine's hostname.

The recovery code is read from the keyboard

custodian recover never takes the recovery code as an argument — an argument is readable from the process table while the command runs. When you run it in a terminal it prompts for the code and reads one line:

Enter your twenty-four word recovery code:
>

Type or paste the twenty-four words. If you enter nothing, it stops before touching the network:

No recovery code was provided. Re-run `custodian recover` and type or pipe in the twenty-four words printed at `custodian init`.

The code is checked against its checksum before any request is made, so a mistyped, misheard or out-of-order word is caught at once — and a wrong code is refused without a request that could reveal whether the vault holds an envelope at all.

The store that will hold this machine's key

Before this machine is enrolled, custodian recover names the store that will hold its device key and states plainly whether that key ever enters the tool's memory — the same disclosure custodian init makes. See the guarantee for each store.

Device key store: Secure Enclave (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

When it finishes

This machine is now a live device of vault "acme", recovered from its code.
  Device:    dev_7Qm2…
  Vault:     acme
  Key store: Secure Enclave (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

The master key is now wrapped to this device; `custodian records get --reveal` reads the vault. Your recovery code is unchanged and still the only way back if this device is lost too.

On macOS the Key store: line — in both the block above and the pre-enrol disclosure — depends on the build and the machine. The Secure Enclave line is what you see on the signed macOS bundle on a Mac with a Secure Enclave. A Mac with no Secure Enclave enrols with the software Keychain instead, and a build that is not the signed bundle cannot enrol this machine as a reading device at all — recover refuses and tells you to install the signed macOS bundle first. See the store that holds the key for the three lines and what each means.

From here you can read the vault with custodian records get --reveal, add further machines with custodian device enrol, and — if the recovery code itself may have been seen — rotate the master key with custodian key rotate.

When it refuses

The server names each condition, and custodian recover prints its words:

• A live device still exists. Recovery only runs once no device is left.

  This vault still has a live device, so the recovery envelope will not be returned. Recovery is for a vault with no device left: revoke the remaining devices with `custodian device revoke` first, then recover.

• The credential is not an operator.

  The recovery envelope is returned only to an operator principal; this credential is a service. Recover with an operator credential.

• The vault's keys were destroyed. There is no master key left to reconstruct.

  This vault's keys have been destroyed, so no recovery envelope will be returned and nothing can reconstruct its master key. The destruction is final.

• Too many attempts. Every attempt is recorded, and repeated attempts are rate-limited.

  Too many recovery-envelope requests. Wait before trying again; every attempt is recorded.

If the code passes its checksum but does not open the envelope — a wrong code, or a transposition the checksum did not catch — recovery says so, and speaks only of the code:

The recovery code did not open this vault: it is the wrong code, or a word is mistyped, misheard or out of order in a way the checksum did not catch. Check it against exactly what was printed at `custodian init` and run `custodian recover` again.