Recovery keys, passphrases, DBX and repair
full disk encryption for administrators for snapd developers
What happens to disk keys after install. On Ubuntu Core snap recovery --show-keys creates a recovery key on first request. On hybrid classic Ubuntu 25.10 and later the system-volumes API manages recovery keys and passphrases and PINs as keyslots. A Secure Boot DBX update is a two-step reseal and a factory reset rotates the keys of ubuntu-save and snapd repairs its keyslots once each time it starts when it can.
On the map: ubuntu core full disk encryption
01 The day the disk asks for a key
Each encrypted partition holds a few keyslots, and snapd adds at most eight: platform keys that unlock automatically, and recovery keys that a person types. This deck covers how those slots are created, kept valid and repaired after install.
One morning your gateway doesn't come back after a firmware update. On its console there's a prompt asking for a recovery key. Do you have one? That's the question this deck is for. Every encrypted partition has a few keyslots; snapd adds at most eight. Some open by themselves when the boot is the one that was expected; those are the platform keys from the sealing deck. A recovery key is a different kind of slot: a long number that a person types. So after install, how do you get one, how do the automatic slots stay valid, and what does snapd repair on its own?
02 On Ubuntu Core: ask before you need it
On Ubuntu Core, sudo snap recovery --show-keys creates the recovery key on the first request and shows the same key afterwards. Until it has been run, no recovery key exists.
Here's the detail that catches people out: a freshly installed Ubuntu Core device has no recovery key at all. Nothing was hidden from you; it doesn't exist yet. The first time root runs snap recovery --show-keys, snapd generates one, adds it to both encrypted partitions and prints it. Run it again and you get the same key back. So the command that looks like it only displays something is the one that creates your way back in. Run it while the gateway is healthy, write the number down, and keep it away from the gateway. If nobody ran it, there's nothing to type at that prompt.
03 On hybrid classic: keys by API for administrators for snapd developers for Ubuntu Core developers
POST /v2/system-volumes with generate-recovery-key returns a key and a key-id; the key is single-use and held in memory for five minutes, outside the state file (in memfd-secret where the kernel offers it). add-recovery-key or replace-recovery-key then commits it. Replace runs fde-add-recovery-keys, fde-remove-keys and fde-rename-keys. Hybrid classic 25.10 and later only.
On your laptop, installed as hybrid classic on Ubuntu 25.10 or later, recovery keys work differently. One API manages them, /v2/system-volumes, reached by installers and settings tools through the snap-fde-control interface or polkit. The flow has two halves. First you generate: snapd returns a key and a key id, and holds the key only in memory, not in the state file, for five minutes and one use. You show it to the person. Then you commit with that id. A replace is three tasks: add the new key in a temporary slot, remove the old slot, rename the temporary one. A recovery slot exists at every step.
04 Adding something you know for administrators for snapd developers for Ubuntu Core developers
replace-platform-key re-creates the TPM keys with auth mode none, passphrase or PIN and refuses gadget, kernel and base refreshes with a conflict while it runs. change-passphrase and change-pin use one fde-change-auth task, limited to 16 tries. Minimum entropy is 42 bits for a passphrase and 13 for a PIN.
Unattended unlock suits a gateway in a cabinet. On a laptop you might want something you know as well. That's a passphrase or a PIN, and it isn't an extra slot. replace-platform-key re-creates the TPM-protected keys with an auth mode: none, passphrase or PIN. Meanwhile gadget, kernel and base refreshes are refused with a conflict, since they'd reseal the same keys. Changing a passphrase later is one task, in place. It's rate limited, because wrong guesses count against the TPM's lockout: snapd allows sixteen tries, well under the TPM's limit. And quality is checked: forty two bits of entropy for a passphrase, thirteen for a PIN.
05 A firmware update that would lock you out for administrators for snapd developers for Ubuntu Core developers
fwupd calls /v2/system-secureboot. efi-secureboot-update-db-prepare creates the change fde-efi-secureboot-db-update: a forced reseal that accepts both the old and the proposed database, then a wait. efi-secureboot-update-db-cleanup reseals with the old keys revoked; efi-secureboot-update-startup aborts and reseals to the current variables. Gadget, kernel and base changes conflict while the change waits; with no call at all it is eventually pruned and undone.
The DBX is the firmware's list of revoked boot code, and the TPM measures it. Write a new one and the next boot measures differently, so the disk stays shut. So fwupd asks first. On prepare, snapd reseals for both lists, current and proposed, before the call returns. Meanwhile kernel, gadget and base changes are refused. On cleanup, snapd reseals for the new list alone and revokes the old keys. If fwupd restarts instead, the update was abandoned: snapd reseals to what the firmware holds now. With no call at all, the change is pruned and undone the same way.
06 Factory reset: new keys for the one room you keep for administrators for snapd developers for Ubuntu Core developers
Factory reset must match the original install's encryption. It keeps ubuntu-save, renames its old keyslots to reprovision-default and reprovision-default-fallback, seals new ones and writes the new fallback key as ubuntu-save.recovery.sealed-key.factory-reset. The first run boot verifies a marker, rotates the file and removes the old slots. The old data fallback key and recovery key are removed. Key files only: on token-based systems (core26 and later) the marker step fails in snapd 13075b6544.
A factory-reset wipes your data and keeps one room: ubuntu-save. What happens to its keys? It must match the original install's encryption. The old slots are renamed, new ones added and sealed, the TPM is partially reprovisioned, and the new fallback key is written under a temporary name. On the first run boot, snapd checks the marker, promotes the new file, deletes the old slots and frees the old TPM counters. The old recovery key is gone: ask for a new one. This assumes key files, as on the gateway's core24. On core26 and later, with keys in tokens, snapd currently fails at the marker step.
07 After a bad boot: status and repair for administrators for snapd developers for Ubuntu Core developers
GET /v2/system-info/storage-encrypted reports active, inactive, recovery, degraded or indeterminate, the auto-repair result and recommendations. Auto-repair runs once each time snapd starts in run mode: a partial TPM reprovision and a forced reseal, or only the forced reseal on the hook path. When it is skipped it records require-reprovision, permit-manual or require-platform-reset.
You typed the recovery key and your gateway is up. Now what? First, ask snapd how this boot was unlocked. The storage-encrypted status says active when the platform keys worked, recovery when a recovery key was needed, degraded when some slot it tried was invalid. Second, snapd has already tried to fix it. Once each time it starts in run mode, it looks at how the disks were opened and, if a repair is safe, partially reprovisions the TPM and forces a reseal, so the next boot opens by itself. If the keys that opened the two partitions don't belong together, it holds back and records a recommendation.
08 Where to go from here
Roads: unlocking, sealing, factory reset, recovery systems, changes and tasks, and the encryption overview.
To see where that recovery key prompt comes from, take the unlocking deck. Sealing explains what a reseal actually rewrites, and this deck leaned on it several times. The factory-reset deck has the rest of that story: what's wiped and what ubuntu-save keeps. Recovery systems covers the other half of the snap recovery command. If the task names here were new to you, the town hall explains changes, tasks and conflicts. And the encryption overview takes you back to where this district starts.
Read more
Which mechanism applies where
| Ubuntu Core | Hybrid classic, Ubuntu 25.10 or later | |
|---|---|---|
| Recovery key | snap recovery --show-keys, created on first request | /v2/system-volumes: generate, then add or replace |
/v2/system-recovery-keys | supported, root only | refused |
/v2/system-volumes | "this action is not supported on this system" | supported |
| Passphrase or PIN | not through this API | replace-platform-key, change-passphrase, change-pin (TPM only) |
| Secure Boot DBX updates | /v2/system-secureboot | /v2/system-secureboot |
| Status | /v2/system-info/storage-encrypted | /v2/system-info/storage-encrypted |
Keyslot names
| Name | Kind | Notes |
|---|---|---|
| default | platform | the run key |
| default-fallback | platform | the fallback key |
| default-recovery | recovery | the system recovery key |
| snapd-tmp* | temporary | used while replacing keys |
| reprovision-default, reprovision-default-fallback | temporary | the old slots during a factory reset |
| snapd-reprovision-* | temporary | used by the reprovision task |
- snapd allows at most 8 keyslots per container when it adds slots through
/v2/system-volumes; LUKS2 itself allows more. - Key data sits in files on Ubuntu Core with base core, core18, core20, core22 or core24, and in LUKS2 tokens with later core bases and on hybrid classic (when cryptsetup supports replacing tokens).
- Names chosen by a user may not start with
snapordefault.
for snapd developers for administrators
/v2/system-volumes
GET lists structures and their keyslots by container role (system-data, system-save).
| POST action | What it does |
|---|---|
| generate-recovery-key | returns recovery-key and key-id; single use, held 5 minutes outside the state file |
| check-recovery-key | checks a recovery key against the containers |
| add-recovery-key | adds the generated key as a new slot (fde-add-recovery-keys) |
| replace-recovery-key | fde-add-recovery-keys, fde-remove-keys, fde-rename-keys |
| replace-platform-key | re-creates the TPM keys with auth mode none, passphrase or PIN (fde-add-platform-keys, fde-remove-keys, fde-rename-keys) |
| check-passphrase-quality, check-pin-quality | entropy check; minimum 42 bits and 13 bits |
| change-passphrase, change-pin | fde-change-auth, in place; limited to 16 tries |
While replace-platform-key runs, gadget, kernel and base refreshes are refused with a change conflict.
Request fields: action, keyslots, key-id, recovery-key, container-roles, auth-mode, passphrase, old-passphrase, new-passphrase.
Access is through the snap-fde-control interface or polkit; the recovery key actions and replace-platform-key need root or polkit authorisation. check-recovery-key is also open to firmware-updater-support, so a user can check the recovery key before a firmware update. snap-fde-control has an implicit slot, does not auto-connect and is denied installation by default.
Passphrase and PIN need snapd and the kernel's snap-bootstrap at 2.74 or later, and are not available with the fde-setup hook. A PIN cannot use a custom KDF type.
for snapd developers for administrators
/v2/system-recovery-keys (Ubuntu Core)
- GET, root only: returns the recovery key, creating it on first use. Stored in
/var/lib/snapd/device/fde/recovery.key; a later request reads that file back, so it returns the same key. - The handler calls
EnsureRecoveryKeys, which works in run and install modes only ("cannot ensure recovery keys from system mode"), and fails with "system does not use disk encryption" without the encryption marker. - Older systems also return a
reinstallkey. - POST
removedeletes the keys. - Refused on hybrid classic 25.10 and later.
for snapd developers for administrators
/v2/system-secureboot
For snaps on the slot side of the fwupd interface.
| Action | Meaning | What snapd does |
|---|---|---|
| efi-secureboot-update-db-prepare | an update to PK, KEK, DB or DBX is about to be written; carries key-database and base64 payloads | creates the change fde-efi-secureboot-db-update with tasks efi-secureboot-db-update-prepare and efi-secureboot-db-update; reseals for old and new; blocks until done |
| efi-secureboot-update-db-cleanup | the update succeeded | reseals with the old keys revoked, which advances the policy counter |
| efi-secureboot-update-startup | the updater has started; any pending operation is aborted | undo: reseals to the current EFI variables |
While an update is pending, gadget, kernel and base changes conflict with it. If no callback arrives the change is eventually pruned and undone. With no sealed keys all three actions do nothing.
Status
| status | Meaning |
|---|---|
| active | the disks were activated and no recovery key was used |
| inactive | no encrypted disk was activated |
| recovery | some disk was activated with a recovery key |
| degraded | active, but some keyslots that were tried were invalid |
| indeterminate | the status could not be detected, for example with a kernel snap that is too old |
| auto-repair-result |
|---|
| not-initialized |
| not-attempted |
| failed-platform-init |
| failed-keyslots |
| failed-encryption-support |
| success |
| Recommendation |
|---|
| require-reprovision |
| permit-manual |
| require-platform-reset |
A failed repair also records require-reprovision. Auto-repair is attempted once each time snapd starts in run mode. On the TPM path it is a partial reprovision plus a forced reseal; on the hook path, a forced reseal only.
POST /v2/systems with the actions generate-recovery-key and reprovision drives the fde-reprovision task: "Reprovision security device and encrypted disks".
Factory reset, key by key
1. Refused when the encryption state differs from the original install: "cannot perform factory reset using different encryption, the original system was encrypted" (or "unencrypted"). 2. ubuntu-save is kept. Its old slots become reprovision-default and reprovision-default-fallback; new slots are added and sealed. 3. The TPM is partially reprovisioned with the lockout authorisation stored on ubuntu-save. 4. The new fallback key is written as ubuntu-save.recovery.sealed-key.factory-reset. This step and the marker in step 5 assume key files; with LUKS2 tokens (core26 and later) snapd 13075b6544 fails at step 5. 5. A marker records the new key's digest. 6. On the next run boot snapd verifies the marker, renames the key file, deletes the old slots and releases the old TPM counter handles.
The old data fallback key and the recovery key are removed. Re-running an interrupted factory reset is an open TODO in the code. See Factory reset, ubuntu-save and remodel.
Further reading
- Use a recovery mode:
snap recovery --show-keyswith sample output and how the key is entered at boot. - Integrate TPM-FDE into a custom installer: PIN and passphrase quality checks and generating a recovery key over the API.
- snap-fde-control interface: the interface that grants access to these endpoints.
- snapd REST API: the published API reference. It has no entry for /v2/system-volumes or /v2/system-secureboot and gives the recovery keys path as /v2/system/system-recovery-keys; snapd serves /v2/system-recovery-keys.
- Troubleshooting: the recovery key prompt and TPM lockout.
The published documentation has no page on DBX updates, keyslot names or auto-repair.
Roads from here
RUNNING SNAPS
- The overlord — changes and tasks and conflicts between them
UBUNTU CORE · install and recovery
- Factory reset, ubuntu-save and remodel — the rest of a factory reset and what ubuntu-save keeps
- Recovery systems — the other half of the snap recovery command
UBUNTU CORE · full disk encryption
- Unlocking at boot — where the recovery key is asked for at boot
- Sealed keys, boot chains and resealing — the platform keys and the reseals this deck builds on
- What is encrypted and who decides — back to full disk encryption