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
01 A key that checks the boot
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
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
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
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
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
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
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: 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
| Container | Keyslot | Role | Boot modes | Key file when not in tokens |
|---|---|---|---|---|
| ubuntu-data | default | run+recover | run, recover | ubuntu-boot/device/fde/ubuntu-data.sealed-key |
| ubuntu-data | default-fallback | recover | recover | ubuntu-seed/device/fde/ubuntu-data.recovery.sealed-key |
| ubuntu-save | default-fallback | recover | recover, factory-reset | ubuntu-seed/device/fde/ubuntu-save.recovery.sealed-key |
| ubuntu-save | default | not sealed | run | ubuntu-save.key inside ubuntu-data, under var/lib/snapd/device/fde/ |
- The initial
bootstrap-keykeyslot 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|1overrides the choice.
for snapd developers for Ubuntu Core developers
TPM state
| Item | Value |
|---|---|
| Policy counter NV handle | random in 0x01880005-0x0188000F |
| Legacy fixed handles | 0x01880001-0x01880004 |
| Lockout auth | ubuntu-save/device/fde/tpm-lockout-auth |
| Primary key, without tokens | ubuntu-save/device/fde/tpm-policy-auth-key |
| Saved preinstall check result | ubuntu-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
| Field | Content |
|---|---|
| Model identity | brand, model, grade, model sign key |
| Asset chain | role, name and one or two hashes per asset (shim, grub) |
| Kernel | kernel snap and revision |
| Command lines | every 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
| Trigger | Detail |
|---|---|
| Kernel or base refresh | at the boot-state commit: before the try boot, with both kernels, and after a successful boot, with the new one only |
| Gadget boot asset update | before the write and again on cancel |
| Kernel command line change | gadget or system option |
| Recovery system | added, promoted or dropped |
| Remodel | twice: old and new model, then the new model only |
| snapd refresh | no 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
- Full disk encryption: the official summary of sealing to the EFI state and the kernel command line.
- Inside Ubuntu Core: the measurement order in four bullets.
- Modify kernel options: command line changes that keep the sealed keys valid.
- Updating gadget boot assets: the asset updates that trigger a reseal.
The published documentation has no page on boot chains, PCR 12, the run and fallback keys or resealing.
Roads from here
UBUNTU CORE · boot
- Try, trying, done — the kernel try boot that a reseal must allow for
- The kernel command line — the kernel command line that is part of every chain
UBUNTU CORE · bootloaders
- Bootloaders: one interface, six implementations — trusted boot assets and the asset cache
UBUNTU CORE · install and recovery
- Recovery systems — the recovery systems the keys are sealed to
UBUNTU CORE · full disk encryption
- Unlocking at boot — what the initramfs does with these keys at boot
- Recovery keys, passphrases, DBX and repair — recovery keys and DBX updates and factory reset
- Encryption without a TPM — sealing without PCRs on boards without a TPM
- What is encrypted and who decides — back to full disk encryption