What is encrypted and who decides
full disk encryption for administrators for Ubuntu Core developers
Ubuntu Core encrypts ubuntu-data and ubuntu-save with LUKS2 and leaves ubuntu-seed and ubuntu-boot readable. The model's grade and storage-safety decide whether encryption is required or preferred or avoided and the install picks one of three backends - the kernel's fde-setup hook or an OP-TEE trusted application or the TPM.
On the map: ubuntu core full disk encryption
01 A gateway in the wrong hands
Ubuntu Core encrypts ubuntu-data and ubuntu-save and leaves ubuntu-seed and ubuntu-boot readable. On a TPM device the key is tied to the hardware and to the boot, not to a person.
Picture your gateway leaving the building in somebody's backpack. What can they read off its disk? Ubuntu Core splits that disk into four partitions. Two are encrypted: ubuntu-data, which holds the system and your data, and ubuntu-save, which holds the device's identity. The other two, ubuntu-seed and ubuntu-boot, stay readable, because the device has to start from something. And nobody stands next to a gateway to type a password, so the key is tied to the hardware; on a TPM device it's released only to the boot it expects. That leaves three questions: who decides, who protects the key, and who checks.
02 Two locked, two open for administrators for Ubuntu Core developers for snapd developers
Roles system-data and system-save are encrypted with LUKS2 and labelled ubuntu-data-enc and ubuntu-save-enc. On core24 and earlier the sealed key files live on the unencrypted ubuntu-boot and ubuntu-seed, which are mounted before any unlock. On core26 and later, and on hybrid classic, the key data sits in LUKS2 tokens instead.
Which two are locked? It goes by-gadget role. The roles system-data and system-save are encrypted. Each one becomes a LUKS2 container, its label gains -enc, and the filesystem sits inside. Seed and boot stay clear, and on a core24 device like the gateway, that's where the sealed keys live: the run key on ubuntu-boot, the fallback keys on ubuntu-seed. The initramfs mounts both before it unlocks anything. A sealed key is safe to leave in the open; it's useless without this TPM and the boot it expects. And that -enc label is also how firmware update tools spot an encrypted system.
03 The model decides for administrators for Ubuntu Core developers for snapd developers
secured means storage-safety: encrypted, and a secured model with any other value is rejected at decode. signed and dangerous default to prefer-encrypted and may set encrypted or prefer-unencrypted.
Here's the part that surprises people: you don't get asked. Whoever signed the model chose for you, in two headers. Grade is secured, signed or dangerous. storage-safety is encrypted, prefer-encrypted or prefer-unencrypted. The gateway's model is secured, so storage-safety defaults to encrypted: encryption is required. It can't be anything else: a secured model that says otherwise is rejected when the assertion is read. A signed or dangerous model defaults to prefer-encrypted, which encrypts if the hardware can. It may also ask for prefer-unencrypted, which skips encryption even when it's available, or for encrypted. And the grade is for life: a remodel can't change it.
04 When the hardware cannot for administrators for Ubuntu Core developers for snapd developers
Unavailable encryption is a hard error for secured grade or storage-safety: encrypted, and a warning followed by an unencrypted install otherwise. prefer-unencrypted and, on dangerous models, a .force-unencrypted file on ubuntu-seed turn encryption off deliberately.
Now break something: the TPM on your bench unit is switched off in the firmware. Both builds run the same encryption check during install, and both fail it. The gateway's secured model demands encryption, so the install stops with an error. A secured device doesn't leave the factory unencrypted by accident. The budget build has a signed model that only prefers encryption. It logs a warning and installs unencrypted, and the device works, so check the log. If you want encryption off on purpose, there are two ways: prefer-unencrypted in the model, or, on a dangerous model only, a .force-unencrypted file on the seed partition.
05 Three ways to protect a key for administrators for Ubuntu Core developers for snapd developers
The order is the kernel's fde-setup hook, then an OP-TEE trusted application, then the TPM. The legacy TPM check wants Secure Boot enabled, the TPM enabled and the lockout authorisation unset; hybrid classic on Ubuntu 25.10 or later uses the secboot preinstall check.
Something has to protect the key so that you don't have to. snapd knows three ways and asks in a fixed order. First: does the kernel snap ship an fde-setup hook? Then the kernel's own helper protects the key. Second: is an OP-TEE trusted application present? Third, if neither: the TPM. The gateway has neither of the first two, so it lands on the TPM. snapd then checks that Secure Boot is on, the TPM is enabled, and its lockout authorisation hasn't already been set. Hybrid classic systems on Ubuntu 25.10 or later run the more thorough preinstall check instead.
06 What install leaves behind for Ubuntu Core developers for snapd developers for administrators
Each container is LUKS2 with an initial bootstrap-key keyslot that is removed after sealing. The stamp /var/lib/snapd/device/fde/sealed-keys records tpm, fde-setup-hook, or nothing for legacy TPM installs.
Let's watch the install do it. It formats ubuntu-data and ubuntu-save as LUKS2 and opens each with a throwaway key in a slot called bootstrap-key. Then it adds the real keys in slots named default and default-fallback. Once that works, it deletes the bootstrap slot, so the only ways in are the new keys. Last, snapd writes a one-word stamp saying which method sealed the keys, so every later step knows whether it's talking to a TPM or to a hook. The sealing deck says what each slot is for.
07 Where to go from here
Roads: sealing, unlocking, recovery keys and repair, encryption without a TPM, install mode, the model, and the Ubuntu Core overview.
From here, follow the key. Sealing shows how it's tied to the boot chain, and what snapd does after every kernel refresh so that it still opens. Unlocking shows what the initramfs does with it at each boot. Recovery keys and repair is the deck for the day that goes wrong. If your board has no TPM, take the road to encryption without a TPM, where the hooks live. Install mode and the model deck fill in where the partitions and the grade come from. And the Ubuntu Core overview is one step back.
Read more
Partitions and labels
| Role | Label when encrypted | Encrypted | Holds |
|---|---|---|---|
| system-seed | ubuntu-seed | no | recovery systems, fallback sealed key files (core24 and earlier) |
| system-boot | ubuntu-boot | no | run bootloader and kernels, run sealed key file (core24 and earlier) |
| system-save | ubuntu-save-enc | yes | device identity, FDE auth files |
| system-data | ubuntu-data-enc | yes | system and user data, the everyday key for ubuntu-save |
LUKS2 is formatted with a 2 MiB metadata area and a 2.5 MiB keyslot area.
Sealed key files exist only where key data is not kept in LUKS2 tokens. Ubuntu Core with base core, core18, core20, core22 or core24 uses files; later core bases use tokens. Hybrid classic uses tokens when cryptsetup supports replacing them.
An encrypted install requires a partition with the system-save role in the gadget.
Grade and storage-safety
| grade | storage-safety unset means | other values allowed |
|---|---|---|
| secured | encrypted | none; the model is rejected |
| signed | prefer-encrypted | encrypted, prefer-unencrypted |
| dangerous | prefer-encrypted | encrypted, prefer-unencrypted |
| Effective storage-safety | Encryption available | Encryption unavailable |
|---|---|---|
| encrypted | encrypted | install fails |
| prefer-encrypted | encrypted | warning, unencrypted install |
| prefer-unencrypted | unencrypted | unencrypted |
Remodel cannot change the grade.
for Ubuntu Core developers for snapd developers
Messages
secured grade model must not have storage-safety overridden, only "encrypted" is validcannot encrypt device storage as mandated by model grade secured: ...cannot encrypt device storage as mandated by encrypted storage-safety model option: ...not encrypting device storage as checking TPM gave: ...not encrypting device storage as querying kernel fde-setup hook did not succeed: ...required partition with system-save role is missing
Backends, in the order checked
| Order | Backend | Chosen when | Stamp in sealed-keys |
|---|---|---|---|
| 1 | fde-setup hook | the kernel snap has the hook | fde-setup-hook |
| 2 | OP-TEE | the trusted application is present | fde-setup-hook |
| 3 | TPM | otherwise | tpm (empty for legacy installs) |
Legacy TPM check: EFI SecureBoot is 1, the TPM is enabled and, for full provisioning, the lockout authorisation is not already set. See Encryption without a TPM.
for snapd developers for Ubuntu Core developers
The preinstall check (hybrid classic, Ubuntu 25.10 or later)
- GET
/v2/systems/{label}reports storage encryption support as available, unavailable, defective or disabled, with availability-check errors, suggested actions and features. - POST action
fix-encryption-supportwithfix-actionandargsre-runs the check. - The "no hardware root of trust" error kind becomes a
volumes-authrequirement. - The result is saved to
ubuntu-save/device/fde/preinstalland loaded again at reseal.
Further reading
- Full disk encryption: the official explanation of requirements, grade and storage-safety. Its outcome tables list a secured model with prefer-encrypted; snapd rejects that model.
- System requirements: the hardware list for TPM-backed encryption.
- model assertion: the definitions of grade and storage-safety.
- Full disk encryption with OP-TEE: the backend selection order from the Arm side.
- Test on QEMU: trying encryption with a software TPM.
Roads from here
UBUNTU CORE · boot
- Ubuntu Core: how a device boots and recovers — back to the Ubuntu Core overview
UBUNTU CORE · install and recovery
- Install mode — the install mode that creates and encrypts the partitions
- Model, gadget and kernel — grade and storage-safety in the model assertion
UBUNTU CORE · full disk encryption
- Sealed keys, boot chains and resealing — how the keys are sealed to the boot chain and resealed after updates
- Unlocking at boot — how the initramfs unlocks the disks at every boot
- Encryption without a TPM — encryption on boards without a TPM
- Recovery keys, passphrases, DBX and repair — recovery keys and passphrases and repair