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

▶ Watch this deck — 8 scenes, ~6 min

01 The day the disk asks for a key

CORE AND HYBRID · KEYS AFTER INSTALL enter recovery keythe automatic unlock did not work_____-_____-_____-… an encrypted partitionsnapd: at most 8 slots unlocks by itself recovery key: a person types it after installget a recovery key before you need itkeep the automatic slots validrepair after a bad boot
A console asking for a recovery key; an encrypted partition with up to eight keyslots added by snapd, two platform keys that unlock by themselves and one recovery key that a person types; three jobs after install: get a recovery key, keep the automatic slots valid, repair after a bad boot

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

UBUNTU CORE ubuntu-dataubuntu-saveafter install: no recovery key yet $ sudo snap recovery --show-keys created now recovery: 61665-00531-54469-09783-47273-19035-40077-28287run it again: the same key write it down and keep it away from the device not asked yet? then there is nothing to type at that prompt
Ubuntu Core: ubuntu-data and ubuntu-save have no recovery key after install; sudo snap recovery --show-keys creates one in both and prints it; running it again prints the same key; if nobody ran it there is nothing to type at the prompt

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

HYBRID CLASSIC 25.10+ · /v2/system-volumes installer or settings appsnap-fde-control, or polkitsnapdthe laptop's system-datadefaultdefault-fallbackdefault-recovery → {"action":"generate-recovery-key"}← {"recovery-key":"…","key-id":"…"}held in protected memory · 5 minutes · single use → {"action":"replace-recovery-key","key-id":"…"} fde-add-recovery-keysfde-remove-keysfde-rename-keys snapd-tmp…renamed to default-recovery Ubuntu Core: this action is not supported on this system
Hybrid classic: an installer or settings app calls /v2/system-volumes; generate-recovery-key returns a key and key-id held in memory for five minutes and one use; replace-recovery-key runs three tasks that add a temporary slot, remove default-recovery and rename the temporary slot; on Ubuntu Core the action is not supported

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

HYBRID CLASSIC 25.10+ · PASSPHRASE AND PIN the laptop's system-datadefaultauth-mode: nonedefault-fallbackauth-mode: noneTPM {"action":"replace-platform-key","auth-mode":"passphrase"}defaultauth-mode: passphrasedefault-fallbackauth-mode: passphraseTPM keys re-created: temporary slots, remove, rename refreshgadget, kernel and base refreshes conflict {"action":"change-passphrase"}fde-change-authin place, no new slots 16 triessnapd's limiter, below the TPM's own limit passphrase: at least 42 bits of entropyPIN: at least 13 bits
Hybrid classic: replace-platform-key re-creates the TPM keys default and default-fallback with auth-mode passphrase while gadget, kernel and base refreshes conflict; change-passphrase is one fde-change-auth task in place, limited to 16 tries, below the TPM's own limit; a passphrase needs 42 bits of entropy and a PIN 13

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

CORE AND HYBRID · SECURE BOOT DBX UPDATE fwupdsnapdsealed keysacceptold DBX efi-secureboot-update-db-prepareDBX + payloadfde-efi-secureboot-db-update1 · reseal for old and newnew DBXthe prepare call returns when the reseal is done writes the DBX2 · waitingold + new DBXwhile it waits: gadget, kernel and base changes conflict efi-secureboot-update-db-cleanupreseal, revoke old keysnew DBX only abandoned:efi-secureboot-update-startupundo: reseal to the firmware's current variables no callback at all: the change is pruned and undone the same way
Three lanes over time: fwupd, snapd and what the sealed keys accept. Prepare makes snapd reseal for the old and new DBX before the call returns; while fwupd writes the DBX, gadget, kernel and base changes conflict; cleanup reseals for the new DBX and revokes old keys; startup instead undoes the reseal to the firmware's current variables; with no callback the change is pruned and undone

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

UBUNTU CORE · FACTORY RESET encryption must match the original installotherwise: cannot perform factory reset using different encryptionbeforeubuntu-savedefaultdefault-fallback during factory resetubuntu-savereprovision-defaultreprovision-default-fallbackdefaultdefault-fallback TPMpartial reprovision, with thelockout auth kept on ubuntu-saveubuntu-save.recovery.sealed-key.factory-resetbeside the old file, on ubuntu-seed first run bootsnapdchecks the factory-reset marker:the digest of the new keyubuntu-savereprovision-defaultreprovision-default-fallbackdefaultdefault-fallbackubuntu-save.recovery.sealed-keyold TPM counter handles released ubuntu-data is new:its old fallback key andrecovery key are gone key files only: with LUKS2 tokens(core26 and later) snapd 13075b6544fails the reset at the marker step
ubuntu-save across a factory reset: before, slots default and default-fallback; during, they are renamed reprovision-default and reprovision-default-fallback, new default slots are sealed, the TPM is partially reprovisioned and the new fallback key file gets a .factory-reset suffix; on the first run boot snapd checks the factory-reset marker, deletes the old slots, renames the file and releases old TPM counter handles; with LUKS2 tokens on core26 and later the marker step fails

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

CORE AND HYBRID · STATUS AND AUTO-REPAIR GET /v2/system-info/storage-encrypted"status": "recovery"activeinactiverecoverydegradedindeterminate snapd · once per startsafe to repair? yespartial TPM reprovisionforced reseal"auto-repair-result": "success" activenext boot: active nounlocked primary keys differ"recommendations": ["require-reprovision"] the other two: permit-manual · require-platform-reset
GET /v2/system-info/storage-encrypted reports status recovery, one of active, inactive, recovery, degraded and indeterminate; snapd once each time it starts asks whether a repair is safe; if yes, a partial TPM reprovision and a forced reseal give auto-repair-result success and the next boot is active; if the unlocked primary keys differ it records the recommendation require-reprovision; the other recommendations are permit-manual and require-platform-reset

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 keys after installUnlocking at bootwhere the prompt comes from Sealed keys and resealingwhat a reseal rewrites Factory reset, ubuntu-savewhat is wiped, what is kept Recovery systemsthe rest of snap recovery Changes and tasksthe town hall Encryption overviewback to the start
Roads from keys after install: unlocking at boot, sealed keys and resealing, factory reset and ubuntu-save, recovery systems, changes and tasks, and the encryption overview

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 CoreHybrid classic, Ubuntu 25.10 or later
Recovery keysnap recovery --show-keys, created on first request/v2/system-volumes: generate, then add or replace
/v2/system-recovery-keyssupported, root onlyrefused
/v2/system-volumes"this action is not supported on this system"supported
Passphrase or PINnot through this APIreplace-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

NameKindNotes
defaultplatformthe run key
default-fallbackplatformthe fallback key
default-recoveryrecoverythe system recovery key
snapd-tmp*temporaryused while replacing keys
reprovision-default, reprovision-default-fallbacktemporarythe old slots during a factory reset
snapd-reprovision-*temporaryused 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 snap or default.

for snapd developers for administrators

/v2/system-volumes

GET lists structures and their keyslots by container role (system-data, system-save).

POST actionWhat it does
generate-recovery-keyreturns recovery-key and key-id; single use, held 5 minutes outside the state file
check-recovery-keychecks a recovery key against the containers
add-recovery-keyadds the generated key as a new slot (fde-add-recovery-keys)
replace-recovery-keyfde-add-recovery-keys, fde-remove-keys, fde-rename-keys
replace-platform-keyre-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-qualityentropy check; minimum 42 bits and 13 bits
change-passphrase, change-pinfde-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 reinstall key.
  • POST remove deletes 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.

ActionMeaningWhat snapd does
efi-secureboot-update-db-preparean update to PK, KEK, DB or DBX is about to be written; carries key-database and base64 payloadscreates 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-cleanupthe update succeededreseals with the old keys revoked, which advances the policy counter
efi-secureboot-update-startupthe updater has started; any pending operation is abortedundo: 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

statusMeaning
activethe disks were activated and no recovery key was used
inactiveno encrypted disk was activated
recoverysome disk was activated with a recovery key
degradedactive, but some keyslots that were tried were invalid
indeterminatethe 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

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

UBUNTU CORE · full disk encryption