Encryption without a TPM
full disk encryption for Ubuntu Core developers
On boards without a TPM the kernel snap protects the disk keys. An fde-setup hook wraps each key at install through snapctl and an fde-reveal-key helper in the initramfs unwraps it at boot. snapd binds the keys to the authorized models and boot modes instead of PCRs. An OP-TEE trusted application can take the same place without any hook.
On the map: ubuntu core full disk encryption
01 A board without a TPM
With the hook backend snapd and its encryption library, secboot, generate and manage the keys, and a helper shipped in the kernel snap wraps them at install and unwraps them at boot. The helper is meant to be stateless, which snapd cannot enforce; snapd stores what it returns without interpreting it.
Your controller board has no TPM. Does that mean no encryption? No. Its processor has a hardware key store, but only the vendor's code can talk to it, and snapd can't learn every chip. So the work is split. snapd's encryption library creates the key, and snapd manages it, as it would with a TPM. The kernel snap brings a small helper with one job: take a key, wrap it with the hardware, and hand back something only that hardware can unwrap. snapd keeps the result without looking inside. The helper is meant to keep no state. It wraps at install and unwraps at every boot.
02 First question: can you do this? for Ubuntu Core developers for snapd developers
snapd runs the kernel's fde-setup hook directly, without a task, with {"op":"features"}. The hook reads the request with snapctl fde-setup-request and replies with snapctl fde-setup-result: a features list (possibly empty, or with inline-crypto-engine) or an error.
Before snapd encrypts anything on the controller, it asks a question. The kernel snap has a snap hook called fde-setup. snapd runs it directly, with no task, and a five minute limit. The hook gets no arguments. Instead it runs snapctl fde-setup-request, and the first request is the operation features. It answers by piping JSON into snapctl fde-setup-result. Any list of features, even an empty one, means yes. One feature means something to snapd: inline-crypto-engine, which picks that flavour of LUKS. An error reply means no, and then the model decides whether the install stops or carries on unencrypted.
03 Wrap this key for Ubuntu Core developers for snapd developers
{"op":"initial-setup"} carries key, produced by secboot's hooks platform, and key-name; the hook returns sealed-key and an opaque handle. snapd stores both, once for each of the three keys, and stamps /var/lib/snapd/device/fde/sealed-keys with fde-setup-hook.
The answer was yes. Here comes a key to wrap. For each key a TPM device would seal, snapd runs the hook again with the operation initial-setup. The request carries a key from snapd's encryption library, and its name. The hook wraps the key with the hardware and returns the sealed key and a handle. The handle is whatever the hook needs to find its way back, and snapd stores it unread. That's three calls: the run key for ubuntu-data, then fallbacks for ubuntu-data and ubuntu-save. Then snapd stamps the device as sealed by a hook, so later reseals know who to ask.
04 At boot: a helper in a box for Ubuntu Core developers for snapd developers
fde-reveal-key is a binary in the initramfs, not a snap hook. snap-bootstrap runs it through systemd-run with SystemCallFilter=~@mount and a two-minute limit and sends JSON on stdin: {"op":"reveal"} with sealed-key and handle, and later {"op":"lock"}, whose effect is up to the vendor's helper.
At boot there's no snapd yet. The kernel's initramfs carries a second program, fde-reveal-key. It's a plain binary, not a hook; finding it on the path is how snap-bootstrap knows this device uses hooks. snap-bootstrap starts it in a small box, through systemd-run, with only mount system calls filtered out and a two minute limit. On standard input it gets the operation reveal, the sealed key and the handle. The key comes back on standard output, and ubuntu-data opens. Before leaving the initramfs, one last request, lock, asks the helper to refuse until the next boot; the rest is up to the vendor.
05 Bound to the model, not to the boot for Ubuntu Core developers for snapd developers
Hook keys have no PCR profile and no bootloader lookup. They are bound to the authorized models and boot modes, so kernel, boot asset and command line reseals skip them; a remodel and recovery system changes (try, promote, drop) reseal them, and passphrase and PIN authentication are not available.
Here's the real difference from a TPM. A TPM key is tied to measurements: which shim, which GRUB, which command line. A hook key carries two conditions instead: the models allowed to use it, and the boot modes it's valid in. A kernel refresh, a gadget asset update, a new command line: none of them changes the model, so none of them reseals. Only a change that can alter the set of models does: a remodel, or a recovery system being tried, promoted or dropped. And there's no passphrase or PIN on this path. How strong the protection is comes down to the hardware behind the helper.
06 OP-TEE: the same seat, no hook for Ubuntu Core developers for snapd developers
OP-TEE is checked second, after the fde-setup hook and before the TPM. snapd at install and snap-bootstrap at boot call the trusted application through the same key protector path as hooks; its keys carry the tagged handle {"method":"optee","handle":...}.
There's a second way without a TPM, and it needs no vendor hook. Many Arm boards run OP-TEE, a small trusted operating system in the processor's secure world. If the kernel snap has no fde-setup hook, snapd looks for a particular trusted application there, and if it's present, snapd uses it. It takes the hook's seat: wrap at install, unwrap at boot, lock afterwards. snapd at install, and snap-bootstrap at boot, talk to the trusted application directly, with no hook and no helper binary. Keys wrapped this way carry a handle that says OP-TEE. And the last scene still applies: models and boot modes, no PCRs.
07 Where to go from here
Roads: the encryption overview, unlocking at boot, the TPM path, device hooks, the fde-setup handshake through snapctl, and the model, gadget and kernel.
That's how the keys are protected. The unlock around them is the same on every board, and the unlocking deck walks through it, including why the lock comes last. The overview shows the decision that put the controller on this path: hook first, then OP-TEE, then the TPM. If you also build x86 devices, the sealing deck is the contrast. The device hooks topic covers how snapd runs a hook at all, the snapctl device and system deck shows the fde-setup handshake, and the model deck shows the kernel snap and the model these keys are bound to.
Read more
The fde-setup hook (install time)
A hook of the kernel snap, run by snapd with a 5-minute timeout. It reads its request with snapctl fde-setup-request and answers by passing JSON on stdin to snapctl fde-setup-result. Both commands work only inside the fde-setup hook.
| op | Request fields | Reply |
|---|---|---|
| features | none | {"features":[...]} or {"error":"..."} |
| initial-setup | key (base64), key-name | {"sealed-key":"<base64>","handle":{...}} |
| Feature | Effect |
|---|---|
| inline-crypto-engine | LUKS with the inline crypto engine |
| any other, or an empty list | plain LUKS |
At install snapd calls initial-setup once for each of three keys: the ubuntu-data run key (boot modes run and recover), the ubuntu-data fallback key (recover) and the ubuntu-save fallback key (recover and factory-reset).
The fde-reveal-key helper (boot time)
A binary in the initramfs. Its presence on PATH is how snapd decides that hooks are in use at boot. It is run through systemd-run with DefaultDependencies=no, SystemCallFilter=~@mount and a RuntimeMaxSec of two minutes, with JSON on stdin.
| op | Request fields | Reply |
|---|---|---|
| reveal | sealed-key, handle, key-name (deprecated) | {"key":"<base64>"} |
| lock | none | none |
Hooks compared with the TPM
| TPM | fde-setup hook or OP-TEE | |
|---|---|---|
| Key bound to | PCR profile | authorized models and boot modes |
| Reseal on kernel, gadget asset or command line change | yes | no |
| Reseal on remodel | yes | yes |
| Reseal on recovery system try, promote or drop | yes | yes |
| Passphrase or PIN | on supported systems | no |
| Lock after unlock | PCR 12 | {"op":"lock"} or the OP-TEE lock |
| Stamp in sealed-keys | tpm | fde-setup-hook |
| Primary key file without tokens | tpm-policy-auth-key on ubuntu-save | aux-key on ubuntu-save |
OP-TEE installs are stamped fde-setup-hook too: the stamp records whether a hook-style key protector was used, and OP-TEE goes through the same path.
Messages
cannot use hook: neither "features" nor "error" returnedcannot use hook: it returned error: ...cannot use fde-setup-request outside of the fde-setup hookcannot use fde-setup-result outside of the fde-setup hooknot encrypting device storage as querying kernel fde-setup hook did not succeed: ...
Details
- Installing from the initramfs needs an
fde-setupbinary in the initramfs when the kernel snap has the hook. - A version 1 format is still accepted: the hook may return raw bytes starting with
USK$, and reveal may return a raw 64-byte key instead of JSON. - OP-TEE is used only when the kernel snap has no
fde-setuphook and the trusted application is present. Its keys carry the tagged handle{"method":"optee","handle":...}. - When the
featuresquery fails, a model with grade secured or storage-safety encrypted stops the install; otherwise the device is installed unencrypted with the warning above.
Further reading
- UC20+ FDE hooks: the JSON of both helpers and links to two implementations. It says the features list is always empty and lists an update operation; snapd recognises inline-crypto-engine and has only features and initial-setup.
- Full disk encryption with OP-TEE: prerequisites, how snapd talks to the trusted application, and moving from hooks by remodel.
- Supported snap hooks: the general hook mechanism that fde-setup uses.
- Use snapctl: snapctl inside hooks in general.
Roads from here
SNAPCTL · the snap's API into snapd
- snapctl: device and system — the fde-setup handshake through snapctl
HOOKS · code snapd runs inside a snap
- Hooks: device setup — the other device hooks and how snapd runs hooks
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the kernel snap and the model the keys are bound to
UBUNTU CORE · full disk encryption
- What is encrypted and who decides — the order in which the three backends are checked
- Unlocking at boot — the unlock sequence that calls the reveal helper
- Sealed keys, boot chains and resealing — the TPM path this replaces and its reseals