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

▶ Watch this deck — 7 scenes, ~5 min

01 A board without a TPM

UBUNTU CORE · ENCRYPTION WITHOUT A TPM the controllerno TPMhardware key storeinside the processor snapddisk key kernel snapthe vendor's helperonly the vendor's code talks to the key store wrap this →← wrapped key wrapped keykept by snapd, opaque install: wrapevery boot: unwrap
The controller board has a hardware key store and no TPM. snapd holds a key from its encryption library; a helper in the kernel snap, the only code that talks to the key store, wraps it and hands back a wrapped key that snapd keeps without reading it. Wrapping happens at install and unwrapping at every boot

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

UBUNTU CORE · FDE-SETUP FEATURES snapd (install)run hook →5 minute limitkernel snap: fde-setup hook $ snapctl fde-setup-request{"op":"features"} $ echo '{"features":[]}' |snapctl fde-setup-result ← replysupported: encrypt with LUKS other replies{"features":["inline-crypto-engine"]}→ LUKS with the inline crypto engine {"error":"hardware-unsupported"}→ not supported: the model decides what happens next
snapd runs the kernel snap's fde-setup hook with a five minute limit. The hook reads the request op features with snapctl fde-setup-request and replies through snapctl fde-setup-result. A features list means supported; inline-crypto-engine selects LUKS with the inline crypto engine; an error means not supported

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

UBUNTU CORE · FDE-SETUP INITIAL-SETUP snapdkey for ubuntu-data {"op":"initial-setup","key":"<base64>","key-name":"ubuntu-data"}fde-setup hook (kernel snap)hardware key store {"sealed-key":"<base64>","handle":{...}} wrapped key + handlestored with the key data; the handle is the hook's own business × 3 keysubuntu-data run key · ubuntu-data fallback · ubuntu-save fallback /var/lib/snapd/device/fde/sealed-keysfde-setup-hookread at every later reseal
snapd sends the fde-setup hook an initial-setup request with the key and its name. The hook wraps it with the hardware key store and returns a sealed key and a handle, which snapd stores. This repeats for three keys, and snapd stamps sealed-keys with fde-setup-hook

{"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

UBUNTU CORE · FDE-REVEAL-KEY snap-bootstrap (initramfs)fde-reveal-key on PATH?then hooks are in usefde-reveal-keyhardware key store systemd-runSystemCallFilter=~@mountRuntimeMaxSec=2min {"op":"reveal","sealed-key":"...","handle":{...}}→ stdin {"key":"<base64>"}← stdout ubuntu-data-encunlocked {"op":"lock"}before leaving the initramfs; the helper decides
In the initramfs snap-bootstrap finds fde-reveal-key on PATH and runs it through systemd-run with mount system calls filtered and a two minute limit. It sends op reveal with the sealed key and handle on stdin, the helper asks the hardware key store and returns the key, which unlocks ubuntu-data-enc. A last lock request comes before leaving the initramfs

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

UBUNTU CORE · WHAT THE KEY IS TIED TO TPM keytied tosecure boot policyshim and GRUBkernel command linemodel hook keyauthorized modelsauthorized boot modesrun, recover, factory-reset kernel refreshgadget asset updatecommand line changeresealresealresealnothing to donothing to donothing to do remodelresealreseal: the set of models changedrecovery system changeresealreseal no passphrase, no PIN how strong the protection is comes down to the hardware behind the helper
A TPM key is tied to secure boot policy, shim and GRUB, the kernel command line and the model; a hook key is tied only to the authorized models and boot modes. Kernel refreshes, gadget asset updates and command line changes reseal TPM keys but leave hook keys alone; a remodel or a recovery system change reseals both. Hook keys have no passphrase or PIN

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

UBUNTU CORE · OP-TEE checked in this order1 · fde-setup hook2 · OP-TEE3 · TPMthe kernel snap has no fde-setup hook normal worldsecure worldsnapd · snap-bootstraptrusted application wrap at install · unwrap at boot · lockno hook, no helper binary {"method":"optee","handle":...}how a stored key says who wrapped it same binding as hooksmodels and boot modes, no PCRs
Backends are checked in order: fde-setup hook, OP-TEE, TPM. With no hook in the kernel snap, snapd at install and snap-bootstrap at boot, in the normal world, talk directly to a trusted application in the secure world to wrap at install, unwrap at boot and lock. Its keys carry a handle tagged method optee and keep the same binding to models and boot modes

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 Encryption without a TPM Unlocking at bootthe sequence around reveal What is encryptedand who decides Sealed keysthe TPM path and resealing Device hookshow snapd runs a hook snapctl: device and systemthe fde-setup handshake Model, gadget and kernelwhat the keys are bound to
Roads from encryption without a TPM: unlocking at boot, what is encrypted and who decides, sealed keys and resealing, device hooks, snapctl device and system commands, and model, gadget and kernel

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.

opRequest fieldsReply
featuresnone{"features":[...]} or {"error":"..."}
initial-setupkey (base64), key-name{"sealed-key":"<base64>","handle":{...}}
FeatureEffect
inline-crypto-engineLUKS with the inline crypto engine
any other, or an empty listplain 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.

opRequest fieldsReply
revealsealed-key, handle, key-name (deprecated){"key":"<base64>"}
locknonenone

Hooks compared with the TPM

TPMfde-setup hook or OP-TEE
Key bound toPCR profileauthorized models and boot modes
Reseal on kernel, gadget asset or command line changeyesno
Reseal on remodelyesyes
Reseal on recovery system try, promote or dropyesyes
Passphrase or PINon supported systemsno
Lock after unlockPCR 12{"op":"lock"} or the OP-TEE lock
Stamp in sealed-keystpmfde-setup-hook
Primary key file without tokenstpm-policy-auth-key on ubuntu-saveaux-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" returned
  • cannot use hook: it returned error: ...
  • cannot use fde-setup-request outside of the fde-setup hook
  • cannot use fde-setup-result outside of the fde-setup hook
  • not encrypting device storage as querying kernel fde-setup hook did not succeed: ...

Details

  • Installing from the initramfs needs an fde-setup binary 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-setup hook and the trusted application is present. Its keys carry the tagged handle {"method":"optee","handle":...}.
  • When the features query 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

HOOKS · code snapd runs inside a snap

UBUNTU CORE · install and recovery

UBUNTU CORE · full disk encryption