Ubuntu Core with Secure Boot and a TPM
ubuntu-core-24+tpm, 26+tpm for users for CI operators
ubuntu-core-24+tpm, 26+tpm and their +dangerous+tpm variants boot on x86_64 with OVMF's Secure Boot firmware and a TPM 2.0 emulated by swtpm; the first boot encrypts ubuntu-data and ubuntu-save and seals the keys to the TPM state in X.tpm/, which belongs with the disk and its UEFI variables.
On the map: ubuntu core
▶ Watch this deck — 7 scenes, ~5 min
Worth seeing first
- Ubuntu Core images — how image-garden makes Ubuntu Core systems
01 Ubuntu Core, encrypted
ubuntu-core-24+tpm, ubuntu-core-24+dangerous+tpm, ubuntu-core-26+tpm and ubuntu-core-26+dangerous+tpm boot on x86_64 with Secure Boot and an emulated TPM 2.0.
Say you work on something that has to keep working under full disk encryption on Ubuntu Core: a snap, a kernel, or snapd itself. Encryption needs two things a plain VM doesn't have, Secure Boot and a TPM. image-garden has four systems with both: ubuntu-core-24+tpm, ubuntu-core-26+tpm, and their +dangerous+tpm twins, all on x86_64. You build one the way you build ubuntu-cloud-24.04.x86_64, with one make command. What's different is the machine it gets, what its first boot does, and three files that from then on belong together.
Details and sources
Details
UBUNTU_CORE_TPM_RELEASES = 24+tpm 24+dangerous+tpm 26+tpm 26+dangerous+tpm, added toGARDEN_SYSTEMSfor x86_64 only (mk/050-ubuntu-core.mk:9-16). make stops+tpm+dangerous(wrong order) and a+tpmgoal that is not x86_64 (mk/050-ubuntu-core.mk:18-21).- The README: "The
+tpmsystems, for x86\_64 only, boot with Secure Boot and a TPM 2.0 emulated by swtpm" (README.md:702-718); the release notes (NEWS:45-48). - They start from the same downloads as ubuntu-core-24 and 26 and their +dangerous twins (mk/050-ubuntu-core.mk:279-289); see Ubuntu Core images.
Read more
02 Secure Boot and a TPM in QEMU
-machine q35,smm=on, the OVMF Secure Boot pair with secure pflash, and -device tpm-crb backed by swtpm over a UNIX socket.
Here's what the machine gets that plain ubuntu-core-24 doesn't. The q35 machine runs with System Management Mode, which Secure Boot firmware needs to guard its variables. The firmware is OVMF's Secure Boot build, with a variable store that has Microsoft's keys enrolled, so the signed shim may boot, and the flash is marked secure. And there's a TPM 2.0 device. QEMU doesn't emulate the TPM itself: it talks over a socket to swtpm, a separate TPM emulator, which keeps everything the TPM knows in a state directory.
Details and sources
Details
QEMU_SYSTEM_X86_64_MACHINE = q35,smm=onfor the +tpm.runand.qcow2; their firmware copies come fromefi-secboot-code.x86_64.imgandefi-secboot-vars.x86_64.img(mk/050-ubuntu-core.mk:55-61), the pairOVMF_CODE_4M.secboot.fdandOVMF_VARS_4M.ms.fd"with the Microsoft keys enrolled, so that the signed shim boots" (mk/010-qemu-x86_64.mk:282-289).QEMU_SECURE_PFLASH_OPTION = -global driver=cfi.pflash01,property=secure,value=onandQEMU_TPM_OPTION_FOR = -chardev socket,id=chrtpm,path=SOCK -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-crb,tpmdev=tpm0(mk/010-qemu-x86_64.mk:132-135); the launcher macro's comment (mk/010-qemu-x86_64.mk:53-58).- In the
.runscript the TPM option isQEMU_TPM_OPTION, which can be overridden like the others (mk/010-qemu-x86_64.mk:71, :80). - The README and the man page document
QEMU_TPM_OPTION: by default atpm-crbdevice connected to the swtpm the.runscript starts (README.md:941-942, image-garden.1:665-669).
Read more
03 The first boot seals the keys
Making ubuntu-core-24+tpm.x86_64.qcow2 creates ubuntu-core-24+tpm.x86_64.tpm/ (mode 700), runs swtpm on it and boots install mode, which encrypts ubuntu-data and ubuntu-save and seals the keys.
The first boot is where it counts. When you make the .qcow2 image, make first creates an empty TPM state directory next to it, readable only by you. It starts swtpm on that directory, then boots the image with its seed. Ubuntu Core comes up in install mode, finds the TPM and Secure Boot, encrypts its ubuntu-data and ubuntu-save partitions and seals their keys to the TPM. The serial log shows the guest's journal while it works. When QEMU powers off, swtpm exits with it. If QEMU was stopped by a signal instead, make fails rather than keep a half-made image.
Details and sources
Details
- The +tpm
.qcow2rule: checks swtpm,rm -rfandmkdir -m 700the state directory, creates the overlay, makes a run directory under$XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX(or$TMPDIR), runsswtpm socket --tpm2 --tpmstate dir=… --ctrl type=unixio,path=…/swtpm.sock --pid file=… --terminate --daemon, then QEMU with the secure flash, the TPM and the seed on a virtio SCSI CD-ROM (mk/050-ubuntu-core.mk:70-98). - After QEMU, "terminating on signal" in the log fails the rule with "QEMU was stopped by a signal before the install finished"; swtpm gets 10 seconds to exit, then is killed, and the run directory is removed (mk/050-ubuntu-core.mk:99-106).
.DELETE_ON_ERRORremoves the failed target (mk/000-garden.mk:7). - The guest names itself after the system with the
+turned into-, as a host name label allows no+:ubuntu-core-24-tpm,ubuntu-core-24-dangerous-tpm, in user-data and meta-data alike (mk/050-ubuntu-core.mk:141, mk/010-qemu.mk:94-104). - The Ubuntu Core template's bootcmd copies the journal to the serial console for that boot (mk/050-ubuntu-core.mk:144-159).
- Install mode, encryption of ubuntu-data and ubuntu-save and sealing are snapd's work, described by the README (README.md:711-714); image-garden's TPM test checks a TPM 2,
SecureBoot= 1 andCRYPT-*devices under/run/mnt/dataand/run/mnt/ubuntu-save(spread-demo/tests/smoke/tpm/task.yaml:15-51).
Read more
- Sealed keys, boot chains and resealing on the snapd map, the provisioning boot.
04 Three things that belong together
X.qcow2, X.efi-vars.qcow2 and X.tpm/ go together. The launcher refuses to run from another directory and stops when X.tpm/ is missing.
From now on, three things belong together: the disk image, its UEFI variables and the TPM state directory. The keys are sealed to that TPM state, together with the disk and the variables the first boot used, so copy or remove the three as one. The .run script guards this. It opens them relative to where it's started, so it has to be run from its own directory, and it says so if you don't: run this launcher from its own directory. And if the state directory has gone missing, it tells you to make the .qcow2 image again.
Details and sources
Details
- The launcher's comment: "The disk keys are sealed to this TPM state, the disk image and the UEFI variables that the boot which made the image used: all three sit next to this launcher, which opens the disk and the variables relative to the current directory." It compares
pwd -Pwith its own directory and checks the state directory (mk/010-qemu-x86_64.mk:159-172). - The two messages: "$0: run this launcher from its own directory, DIR: its disk is sealed to the TPM state there" and "$0: the TPM state, DIR/X.tpm, is missing: make the .qcow2 image again".
/home/you/projectis an example. - The README: the
SYSTEM.x86_64.tpm/directory "belongs with the.qcow2and.efi-vars.qcow2files: copy or remove them together" (README.md:711-716, README.md:836-837).make cleanremoves the.tpmdirectories (mk/050-ubuntu-core.mk:314-318). - That a copy of only the disk will not unlock is derived from sealing, not run.
Read more
05 Every launch starts its own swtpm
The launcher starts swtpm in $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX, or port.PORT.tpm under allocate; with -snapshot swtpm gets a copy of the state.
Each time the .run script starts, it starts its own swtpm first, with a socket in a fresh directory under your runtime directory, and gives QEMU the TPM. When QEMU exits, swtpm follows, and a small watcher removes the directory. With -snapshot, as allocate runs it, QEMU leaves the disk and the variables untouched, and swtpm works on a copy of the TPM state, so the sealed keys still match next time. allocate also names the directory after the machine's port, so discard can clean it up. The runtime deck on swtpm has the rest.
Details and sources
Details
EMIT_SWTPM_START: run directory fromGARDEN_TPM_RUN_DIR, ormktemp -dunder$XDG_RUNTIME_DIR/image-garden(in the snap's runtime directory when run from outside the snap), else under$TMPDIR; with-snapshotamong the arguments it copies the state withcp -a; swtpm runs with--terminate --daemon; a watchertail --pid=… -f /dev/null; rm -rf …removes the directory (mk/010-qemu-x86_64.mk:137-205). If QEMU fails, the launcher kills swtpm (mk/010-qemu-x86_64.mk:207-216).- allocate exports
GARDEN_TPM_RUN_DIR=$XDG_RUNTIME_DIR/image-garden/port.PORT.tpm(image-garden:825-831, image-garden:1108-1112);discard_tpm_run_dirwaits for swtpm, kills it if needed and removes the directory (image-garden:833-859). - The
.runscript of any system passes-snapshoton when you give it (see the .run script).
Read more
06 What your host needs
Outside the snap: the swtpm and ovmf packages. The container has both. The snap: snap install image-garden+swtpm.
These systems need two things on the host that others don't. Outside the snap, that's the swtpm package, and the ovmf package with the Secure Boot firmware. Without swtpm, make stops and says so: swtpm, the TPM emulator, is required. The container has both. The snap carries the firmware in its x86_64 QEMU component, but swtpm is a component of its own, and it isn't installed automatically. Without it, make stops before it downloads anything and prints the snap install command you need. With it, the snap also runs swtpm for a launcher you start from outside the snap.
Details and sources
Details
- Source installs: "The Ubuntu Core systems with a TPM also need
swtpmand the Secure Boot firmware of theovmfpackage" (README.md:122-126). The container installsovmfandswtpm(Dockerfile:78-91). SWTPM_MISSING_MESSAGE = swtpm, the TPM emulator, is required: install the swtpm package, printed by the.qcow2rule and by the launcher (mk/010-qemu-x86_64.mk:115-120, mk/050-ubuntu-core.mk:79).- In the snap,
check-swtpm-componentprints "install the swtpm component to use systems with a TPM: snap install image-garden+swtpm" (mk/010-qemu-x86_64.mk:121-131); the link to the download depends on it first, so nothing is downloaded (mk/050-ubuntu-core.mk:74-76, mk/050-ubuntu-core.mk:279-289). - The snap: the qemu-x86-64 component carries the Secure Boot OVMF; swtpm is a component of its own, "not installed automatically"; the
image-garden.swtpmapp lets a launcher run from a shell outside the snap (README.md:322-334, snap/snapcraft.yaml:109-139). Missing the Secure Boot firmware gives the message in the Secure Boot pair. - Distribution packages may be older than the upstream release (the maintainer's statement), so a packaged image-garden may not have the +tpm systems yet.
Read more
07 Where to go from here
Next: how a TPM system is launched, +dangerous systems, encryption on the snapd map, the snap's swtpm component, Ubuntu Core and the firmware.
So a +tpm system is Ubuntu Core with Secure Boot, a TPM emulated by swtpm, and an encrypted disk whose keys are sealed to a state directory next to it. From here, the runtime deck shows how each launch runs swtpm, step by step. The +dangerous deck shows how to put your own kernel on such a system. The snapd map explains what decides encryption. The snap deck has the swtpm component, the Ubuntu Core deck the other releases, and the firmware deck the Secure Boot pair.
Details and sources
Read more
Read more
Basis of the statements on this page
Read in mk/050-ubuntu-core.mk, mk/010-qemu-x86_64.mk, image-garden, README.md, snap/snapcraft.yaml, the Dockerfile and spread-demo/tests/smoke/tpm/task.yaml of image-garden at the tag in garden.commit ("code"). What snapd does in install mode is from the README and the test; nothing was run for this page.
The four systems
| System | Host name in the guest | Downloaded image | cdimage directory |
|---|---|---|---|
ubuntu-core-24+tpm.x86_64 | ubuntu-core-24-tpm | ubuntu-core-24-amd64.img.xz | ubuntu-core/24/stable |
ubuntu-core-24+dangerous+tpm.x86_64 | ubuntu-core-24-dangerous-tpm | ubuntu-core-24+dangerous-amd64.img.xz | ubuntu-core/24/dangerous-stable |
ubuntu-core-26+tpm.x86_64 | ubuntu-core-26-tpm | ubuntu-core-26-amd64.img.xz | ubuntu-core/26/stable |
ubuntu-core-26+dangerous+tpm.x86_64 | ubuntu-core-26-dangerous-tpm | ubuntu-core-26+dangerous-amd64.img.xz | ubuntu-core/26/dangerous-stable |
In spread they are ubuntu-core-24-plus-tpm and so on (see system names).
Files next to each system
| File | Made by | Holds |
|---|---|---|
X.qcow2 | the provisioning boot | the encrypted disk, an overlay on the shared download |
X.efi-code.qcow2 | $(QEMU_IMG) convert of efi-secboot-code.x86_64.img | OVMF Secure Boot code |
X.efi-vars.qcow2 | $(QEMU_IMG) convert of efi-secboot-vars.x86_64.img | the UEFI variables, Microsoft keys enrolled |
X.tpm/ | mkdir -m 700 in the .qcow2 rule | swtpm's TPM state, to which the keys are sealed |
X.qcow2.log | tee | the serial console of the provisioning boot, with the journal |
X.run | the launcher rule | starts swtpm, then QEMU |
Messages
| Message | When |
|---|---|
swtpm, the TPM emulator, is required: install the swtpm package | no swtpm on PATH, at make or launch |
install the swtpm component to use systems with a TPM: snap install image-garden+swtpm | in the snap, before the download |
please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) - not in … | no Secure Boot pair found |
X.qcow2: QEMU was stopped by a signal before the install finished | the provisioning QEMU was killed |
$0: run this launcher from its own directory, DIR: its disk is sealed to the TPM state there | launcher started from elsewhere |
$0: the TPM state, DIR/X.tpm, is missing: make the .qcow2 image again | the state directory is gone |
X: system modifiers go in alphabetical order: use …+dangerous+tpm… | +tpm+dangerous in a goal |
X: ubuntu-core with +tpm is only available for x86_64 | a +tpm goal on aarch64 |
What each install needs
| Install | swtpm | Secure Boot OVMF |
|---|---|---|
| Distribution or source | the swtpm package | the ovmf package |
| Container | included | included |
| Snap | snap install image-garden+swtpm | in the qemu-x86-64 component |
Roads from here
UBUNTU CORE · all snaps
- Changing a +dangerous Ubuntu Core system — your own kernel or gadget, also on +dangerous+tpm
- Ubuntu Core images — the other Ubuntu Core releases and modifiers
ARCHITECTURES · machines and firmware
- UEFI firmware per system — the Secure Boot firmware pair and where it is found
RUNTIME · make rules and the CLI
- How a TPM system is launched — how each launch runs swtpm, step by step
SNAP · snap-only features
- swtpm and Secure Boot firmware in the snap — the snap's swtpm component and app
Snapd map ↗
- What is encrypted and who decides — what is encrypted and who decides, on the snapd map