Sealed keys, boot chains and resealing

full disk encryption for Ubuntu Core developers for snapd developers

With a TPM the disk keys are sealed to the measured boot - the shim and GRUB and kernel hashes plus the kernel command line and the model. snapd describes each boot it will accept as a boot chain and reseals the keys whenever a kernel or boot asset or command line or recovery system or model changes.

On the map: ubuntu core full disk encryption

▶ Watch this deck — 8 scenes, ~6 min

01 A key that checks the boot

CORE AND HYBRID · SEALED KEYS shimGRUBkernelcommand line + modelmeasured as it boots sealed keyopens for the boots snapd listedubuntu-datamatch: unlocked TPMmeasurements of this boot new kernelno match: stays sealed so snapd reseals before the reboot
The boot stages shim, GRUB, kernel and the command line with the model are measured into the TPM; the sealed key opens ubuntu-data only when the measurements match, and a new kernel does not match, so snapd reseals before the reboot

A sealed key can be unsealed only when the TPM's measurements of the current boot match a boot it was sealed to. The sealed key itself is a file or a LUKS2 token, not something stored in the TPM. Any change to the boot path needs a reseal first.

A kernel refresh has just landed on your gateway, and it's about to reboot. Will the disk still open? The key for the data partition isn't kept in the clear. It's sealed: wrapped so that the TPM will only unwrap it if the boot it has just measured is one of the boots snapd listed. Shim, GRUB, kernel, command line and model all count. That's exactly what you want against a tampered bootloader. It's also a trap, because a new kernel measures differently, and the key would stay sealed. So before the reboot, snapd rewrites the list. That's called a reseal, and this deck is about getting it right.

02 Three sealed keys and a plain one for Ubuntu Core developers for snapd developers for administrators

CORE AND HYBRID · KEYS AND SLOTS ubuntu-seedubuntu-bootubuntu-save-encubuntu-data-encdefault-fallbackdefaultdefaultdefault-fallback run keyubuntu-data.sealed-keyrun and recover modeskey files as on core24;core26+ and hybrid: LUKS2 tokens fallback keyubuntu-data.recovery.sealed-keyrecover mode only fallback keyubuntu-save.recovery.sealed-keyrecover and factory-reset ubuntu-save.keyplain filesave's key needs no unseal: one unseal per normal boot marker: the same random 32 bytes in both
Four partitions: the run key on ubuntu-boot opens the default keyslot of ubuntu-data; two fallback keys on ubuntu-seed open the default-fallback keyslots of ubuntu-data and ubuntu-save; ubuntu-save's default key is a plain file inside ubuntu-data; a shared marker sits in both

On ubuntu-data, keyslot default is the run key (role run+recover) and default-fallback is a fallback key (role recover); ubuntu-save's default-fallback is the other. ubuntu-save's default key is a plain file inside ubuntu-data, and a shared 32-byte marker pairs the two. On hybrid classic, and on Ubuntu Core from core26, the key data sits in LUKS2 tokens instead of files.

There's more than one key, because there's more than one way to boot. On the gateway, a core24 device, the run key lives on the boot partition and opens data in run and recover modes. Two fallback keys live on the seed partition, one for data and one for save, for the day the run key won't open. And save's everyday key isn't sealed at all. It's a plain file inside encrypted data, so a normal boot asks the TPM only once: unsealing is expensive. Finally, install writes the same random marker into data and save, so that a later boot can tell they came from the same install.

03 What a boot chain holds for Ubuntu Core developers for snapd developers

CORE AND HYBRID · ONE BOOT CHAIN BootChainmodelbrand · modelgradesign key shima1f3…seed grub7c0e…boot grub7c0e…hashes from the boot assets cache kernelpc-kerneland its revision command linessnapd_recovery_mode=run … new 5d20…new 9b42…new 9b42…old and new during a gadget update the chain fans out:old shim → old grub → kernelold shim → new grub → kernelnew shim → new grub → kernelnew shim → old grub → kernelpruned: the new grubis written first
A boot chain: the model identity, then shim, the seed grub and the boot grub named by hashes from the boot assets cache, then the kernel and its revision, then the kernel command lines; during an update an asset has an old and a new hash, the chain fans out, and the new shim then old grub branch is pruned

A BootChain holds the model identity, the asset chain (shim, then the seed GRUB and, on a run chain, the boot GRUB) with one or two hashes per asset, the kernel with its revision, and the kernel command lines. Impossible old and new combinations, such as a new shim loading the old GRUB, are pruned.

How do you write down "a boot I'm willing to accept"? snapd calls it a boot chain. It starts with who the device is: brand, model, grade and the key that signed the model. Then the boot assets in load order, shim, then GRUB, two of them on a run chain, each named by a hash from snapd's asset cache. Then the kernel and its revision. Then the kernel command lines it may use. A gadget update gives an asset two hashes, old and new, and the chain fans out. A new shim can't load the old GRUB, because the new GRUB is written first, so that branch is dropped.

04 The model goes into PCR 12 for Ubuntu Core developers for snapd developers

UBUNTU CORE · THE PCR PROFILE TPMsecure boot policyboot manager code systemd EFI stub · kernel command linesPCR 12 snap model snap-bootstrap1 · snap system epoch2 · the modelthen it tries to unlock a different model or command line measures differently: the key stays sealed registers chosen inside secboot
The legacy PCR profile: the secure boot policy and boot manager code go to registers chosen by secboot; the kernel command lines through the systemd EFI stub and the snap model go to PCR 12; snap-bootstrap measures a system epoch and then the model into PCR 12 before unlocking

On Ubuntu Core, and on hybrid classic before 25.10, the profile combines the secure boot policy, the boot manager code, the EFI stub with the kernel command lines, and the snap model; the last two use PCR 12. snap-bootstrap measures a system epoch and then the model into PCR 12 before unlocking. Hybrid classic 25.10 and later uses secboot's automatic profile instead.

So who does the measuring? The firmware and the bootloaders measure the code as it loads, and on Ubuntu Core, the profile snapd builds covers the secure boot policy and the boot manager code. snapd adds two pieces of its own: the kernel command lines, through the systemd EFI stub, and the model. Both land in one register, PCR 12. At boot, snap-bootstrap measures an epoch and then the model into PCR 12 before it unlocks. So a different model, or a different command line, measures differently, and the key stays sealed. Twelve is the only register snapd names; secboot picks the rest.

05 Two keys, two lists for Ubuntu Core developers for snapd developers

CORE AND HYBRID · WHAT EACH KEY ACCEPTS run keydefaultfallback keydefault-fallback run · current kernelrun · try kernel recover · 20260301recover · 20261112 (being tried)all current recovery systems, including a try model recover · 20260301good recovery systems · current model only the input for all of this is the modeenv, on purpose
The run key accepts the run chains for the current and the try kernel and the recovery chains of every current recovery system; the fallback key accepts only good recovery systems for the current model; both lists come from the modeenv

The run key is sealed to the run boot chains and to the recovery chains of all current recovery systems, including a try model. The fallback key is sealed only to the good recovery systems and the current model. Resealing reads only the modeenv.

The two data keys don't accept the same boots, and that's the point. The run key is the everyday one, so its list is wide: the run chains, including a kernel that's still being tried, plus a recovery chain for every current recovery system, even one that's on trial itself. The fallback key is what you rely on when things have gone wrong, so its list is narrow: only recovery systems that have proven good, and only the current model. All of this is read from one file, the modeenv. That's deliberate: snapd seals to what the boot will actually use, not to something half finished in memory.

06 When snapd reseals for Ubuntu Core developers for snapd developers for administrators

CORE AND HYBRID · RESEAL TRIGGERS resealkernel orbase refreshold and new kernelboth listed;after a good boot,the new one alone resealresealgadget bootasset updatebefore the write,again on cancel resealkernel commandline change resealrecovery systemchangesadded, promotedor dropped resealresealremodelboth models,then the new one a failed reseal fails the task that asked for itand snapd's usual undo runs
A timeline of reseal triggers: a kernel or base refresh with a second reseal after a good boot, a gadget boot asset update with two reseals, a kernel command line change, a recovery system change, and a remodel with two reseals; a failed reseal fails the task that asked for it

Reseals happen on kernel and base boot-state commits (before the try boot, and again after a successful boot to drop the old kernel), gadget boot asset updates (before the write and on cancel), kernel command line changes, recovery system changes, and twice during a remodel. A failed reseal fails the task that triggered it.

Back to that kernel refresh. Before the reboot, snapd reseals so the list holds both kernels: the new one, and the old one in case the try boot fails. After a good boot it reseals again, for the new kernel alone. A gadget update that replaces shim or GRUB reseals before the files are written, and again if the update is cancelled. A kernel command line change reseals. Adding, promoting or dropping a recovery system reseals. A remodel reseals twice: first for both models, then for the new one alone. And if a reseal fails, the task that asked for it fails, and snapd's usual undo runs.

07 Skipped, and rehearsed for snapd developers for Ubuntu Core developers

CORE AND HYBRID · CHEAP AND SAFE predictable boot chainscomputed now, from the modeenv/var/lib/snapd/device/fdeboot-chainsrecovery-boot-chainssealed last time =equal: skip, nothing to dokernel without a revision: the caller's hint decides refresh of snapd, run mode… link-snap snapd check-resealValidate key resealing for snap "snapd" dry-run resealokfails: the snapd refresh fails now found today, not at the next kernel refresh
Left: a reseal is skipped when the newly computed boot chains equal the cached boot-chains and recovery-boot-chains files. Right: after a snapd refresh a check-reseal task runs a dry-run reseal; if it fails, the snapd refresh fails now

A reseal is skipped when the predictable boot chains equal the cached boot-chains and recovery-boot-chains; with an unasserted kernel the caller's hint decides. After each snapd snap refresh in run mode a check-reseal task runs a dry-run reseal, so a regression is caught before it is needed.

Resealing isn't free: it talks to the TPM and rewrites key data, so snapd skips it when it can. It keeps the chains it last sealed to on disk, and if the newly computed ones are identical, there's nothing to do. The other half is about the opposite risk. Imagine a snapd refresh with a bug that breaks resealing. You wouldn't notice until the next kernel update, and by then it's much harder to fix. So after every snapd refresh in run mode, a task called check-reseal does a dry run. If that rehearsal fails, the snapd refresh fails today, while the old snapd can still be put back.

08 Where to go from here

ROADS Sealed keys and resealing Unlocking at bootthe initramfs uses the keys Keys and repairrecovery keys, DBX, factory reset Without a TPMsealing through hooks each trigger has its own deckTry, trying, donethe kernel try bootBootloaderstrusted boot assetsKernel command linepart of every chainRecovery systemswhat the keys are sealed to
Roads from sealed keys and resealing: unlocking at boot, recovery keys and repair, sealing without a TPM, the kernel try boot, bootloaders, the kernel command line and recovery systems

Roads: unlocking at boot, recovery keys and repair, sealing with hooks, the try boot, bootloaders and trusted assets, the kernel command line, recovery systems and the encryption overview.

The keys are sealed. Next, watch the boot use them: the unlocking deck follows the initramfs as it opens data and save. The keys deck covers the reseals this one skipped, a Secure Boot DBX update and a factory-reset, along with recovery keys. On a board without a TPM there are no PCRs and far fewer reseals; that's the hooks deck. And every trigger you saw here has a deck of its own: the kernel try boot, the bootloaders and their trusted assets, the kernel command line, and recovery systems.

Read more

Keys and keyslots created at install

ContainerKeyslotRoleBoot modesKey file when not in tokens
ubuntu-datadefaultrun+recoverrun, recoverubuntu-boot/device/fde/ubuntu-data.sealed-key
ubuntu-datadefault-fallbackrecoverrecoverubuntu-seed/device/fde/ubuntu-data.recovery.sealed-key
ubuntu-savedefault-fallbackrecoverrecover, factory-resetubuntu-seed/device/fde/ubuntu-save.recovery.sealed-key
ubuntu-savedefaultnot sealedrunubuntu-save.key inside ubuntu-data, under var/lib/snapd/device/fde/
  • The initial bootstrap-key keyslot is removed after sealing.
  • A random 32-byte marker is written to both ubuntu-data and ubuntu-save.
  • The data fallback key shares one PCR profile with the save fallback key, so it also accepts factory-reset measurements. The code marks this with a FIXME.

Tokens or files

  • Classic and hybrid: key data goes into LUKS2 tokens when cryptsetup supports replacing tokens.
  • Ubuntu Core: bases core, core18, core20, core22 and core24 use files; later core bases (core26 and on) use tokens. The kernel command line option ubuntu-core.force-experimental-tokens=0|1 overrides the choice.

for snapd developers for Ubuntu Core developers

TPM state

ItemValue
Policy counter NV handlerandom in 0x01880005-0x0188000F
Legacy fixed handles0x01880001-0x01880004
Lockout authubuntu-save/device/fde/tpm-lockout-auth
Primary key, without tokensubuntu-save/device/fde/tpm-policy-auth-key
Saved preinstall check resultubuntu-save/device/fde/preinstall

for snapd developers for Ubuntu Core developers

The PCR profile

Legacy path, combined per model:

  • the secure boot policy profile;
  • the boot manager code profile;
  • the systemd EFI stub profile, with the kernel command lines, on PCR 12;
  • the snap model profile, on PCR 12.

The preinstall-check path (hybrid classic, Ubuntu 25.10 or later) uses an automatic TCG profile plus a kernel configuration profile. PCR 12 is the only register snapd names; the others are chosen inside the secboot library. On Ubuntu Core models missing DMA protection is tolerated in the legacy profile; on classic models it is not.

for snapd developers for Ubuntu Core developers

What a boot chain holds

FieldContent
Model identitybrand, model, grade, model sign key
Asset chainrole, name and one or two hashes per asset (shim, grub)
Kernelkernel snap and revision
Command linesevery kernel command line the chain may boot with

Chains are normalised and stored with a reseal count in /var/lib/snapd/device/fde as boot-chains and recovery-boot-chains. A reseal is skipped when the newly computed chains are equal to the stored ones; when a kernel has no revision, equality is not proof and the caller's hint decides.

When snapd reseals

TriggerDetail
Kernel or base refreshat the boot-state commit: before the try boot, with both kernels, and after a successful boot, with the new one only
Gadget boot asset updatebefore the write and again on cancel
Kernel command line changegadget or system option
Recovery systemadded, promoted or dropped
Remodeltwice: old and new model, then the new model only
snapd refreshno reseal; a check-reseal task runs a dry run

Secure Boot DBX updates and factory reset also reseal; see Recovery keys, passphrases, DBX and repair.

Further reading

The published documentation has no page on boot chains, PCR 12, the run and fallback keys or resealing.

Roads from here

UBUNTU CORE · boot

UBUNTU CORE · bootloaders

UBUNTU CORE · install and recovery

UBUNTU CORE · full disk encryption