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

▶ Watch this deck — 7 scenes, ~5 min

01 A gateway in the wrong hands

CORE AND HYBRID · FULL DISK ENCRYPTION the gatewayubuntu-seedubuntu-bootubuntu-saveubuntu-data ubuntu-saveubuntu-dataencryptedencrypted readablereadable TPMopens them only forthe boot it expects who decides: the modelwho protects the key: the hardwarewho checks: every boot
The gateway's disk has four partitions: ubuntu-seed and ubuntu-boot are readable, ubuntu-save and ubuntu-data are encrypted, and the TPM opens them only for the boot it expects

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

CORE AND HYBRID · THE DISK system-seedubuntu-seedsystem-bootubuntu-bootsystem-saveubuntu-savesystem-dataubuntu-data system-saveubuntu-save-encLUKS2 → ubuntu-savesystem-dataubuntu-data-encLUKS2 → ubuntu-data run sealed keyfallback sealed keyskey files on core24 and earlier; core26+ and hybrid keep the key data in LUKS2 tokens mounted first,before any unlock the -enc label is also how fwupd detects an encrypted system
The disk by gadget role: system-save and system-data become LUKS2 containers labelled ubuntu-save-enc and ubuntu-data-enc; on core24 ubuntu-boot holds the run sealed key and ubuntu-seed the fallback sealed keys, and both are mounted before any unlock

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

CORE AND HYBRID · THE MODEL grade: securedstorage-safety: (unset) encryptedrequired secured + any other storage-safety: the model is rejected grade: signedor dangerousstorage-safety: (unset)prefer-encryptedencrypt if the hardware can prefer-unencrypteddo not encrypt, even if it couldmay also ask for it remodel cannot change the grade
A secured model's storage-safety defaults to encrypted and any other value is rejected; a signed or dangerous model defaults to prefer-encrypted and may also set prefer-unencrypted or encrypted; remodel cannot change the grade

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

CORE AND HYBRID · INSTALL the gateway · securedencryption checkthe budget build · signedencryption check TPM not usableTPM not usable cannot encrypt device storage as mandated bymodel grade secured: ...install stops not encrypting device storage aschecking TPM gave: ...seedbootsavedatainstalled, unencrypted prefer-unencrypted: off even when availabledangerous only: .force-unencrypted on ubuntu-seed
With the TPM unusable, the secured gateway's install stops with an error, while the signed budget build logs a warning and installs unencrypted

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

CORE AND HYBRID · THE BACKEND 1 · does the kernel snap have an fde-setup hook?yeshook backendthe kernel's hook protects the key no2 · is an OP-TEE trusted application present?yesOP-TEE backend no3 · otherwise: the TPMTPM backend EFI SecureBoot = 1TPM enabledlockout auth not already set hybrid classic, Ubuntu 25.10 or later:the secboot preinstall check instead
The install checks three backends in order: the kernel's fde-setup hook, an OP-TEE trusted application, then the TPM, whose legacy check wants Secure Boot, an enabled TPM and an unset lockout authorisation

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

CORE AND HYBRID · AT INSTALL ubuntu-data-encbootstrap-keyubuntu-save-encbootstrap-key defaultdefault-fallbackdefaultdefault-fallback removedremoved /var/lib/snapd/device/fde/sealed-keystpmor fde-setup-hookor empty for older TPM installs what each slot is for: the sealing deck
Each LUKS2 container starts with a bootstrap-key keyslot; the install adds default and default-fallback, removes bootstrap-key, and stamps the sealing method in sealed-keys

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 What is encrypted and who decidesSealed keysboot chains and resealing Unlocking at bootwhat the initramfs does Recovery keys and repairthe day it goes wrong Encryption without a TPMthe fde-setup hooks Install modewhere the partitions come fromThe modelwhere the grade comes from Ubuntu Core overview
Roads from full disk encryption: sealed keys, unlocking at boot, recovery keys and repair, encryption without a TPM, install mode, the model, and the Ubuntu Core overview

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

RoleLabel when encryptedEncryptedHolds
system-seedubuntu-seednorecovery systems, fallback sealed key files (core24 and earlier)
system-bootubuntu-bootnorun bootloader and kernels, run sealed key file (core24 and earlier)
system-saveubuntu-save-encyesdevice identity, FDE auth files
system-dataubuntu-data-encyessystem 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

gradestorage-safety unset meansother values allowed
securedencryptednone; the model is rejected
signedprefer-encryptedencrypted, prefer-unencrypted
dangerousprefer-encryptedencrypted, prefer-unencrypted
Effective storage-safetyEncryption availableEncryption unavailable
encryptedencryptedinstall fails
prefer-encryptedencryptedwarning, unencrypted install
prefer-unencryptedunencryptedunencrypted

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 valid
  • cannot 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

OrderBackendChosen whenStamp in sealed-keys
1fde-setup hookthe kernel snap has the hookfde-setup-hook
2OP-TEEthe trusted application is presentfde-setup-hook
3TPMotherwisetpm (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-support with fix-action and args re-runs the check.
  • The "no hardware root of trust" error kind becomes a volumes-auth requirement.
  • The result is saved to ubuntu-save/device/fde/preinstall and loaded again at reseal.

Further reading

Roads from here

UBUNTU CORE · boot

UBUNTU CORE · install and recovery

UBUNTU CORE · full disk encryption