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

01 Ubuntu Core, encrypted

SECURE BOOT AND A TPM test a snap, a kernel or snapd under full disk encryption Secure Boot a TPM 2.0 ubuntu-core-24+tpm.x86_64 ubuntu-core-26+tpm.x86_64 ubuntu-core-24+dangerous+tpm.x86_64 ubuntu-core-26+dangerous+tpm.x86_64 x86_64 only $ image-garden make ubuntu-core-24+tpm.x86_64.run the machine it gets what its first boot does three files that go together
Testing under full disk encryption needs Secure Boot and a TPM 2.0. Four x86_64 systems have both: ubuntu-core-24+tpm, ubuntu-core-26+tpm, ubuntu-core-24+dangerous+tpm and ubuntu-core-26+dangerous+tpm. You build one with image-garden make ubuntu-core-24+tpm.x86_64.run; what differs is the machine, the first boot and three files that belong together

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

02 Secure Boot and a TPM in QEMU

THE MACHINE -machine q35,smm=on SMM guards the variables OVMF_CODE_4M.secboot.fd OVMF_VARS_4M.ms.fd Microsoft's keys enrolled -global driver=cfi.pflash01,property=secure,value=on the flash is secure QEMU, with tpm-crb socket swtpm -chardev socket,id=chrtpm,path=…/swtpm.sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-crb,tpmdev=tpm0 the TPM state directory
The +tpm machine: -machine q35,smm=on, because Secure Boot firmware guards its variables with SMM; the OVMF Secure Boot code and the variables with Microsoft's keys, so the signed shim may boot; the flash marked secure; and a TPM 2.0 device, tpm-crb, which QEMU backs by talking over a UNIX socket to swtpm, a separate emulator that keeps the TPM's state in a directory

-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=on for the +tpm .run and .qcow2; their firmware copies come from efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img (mk/050-ubuntu-core.mk:55-61), the pair OVMF_CODE_4M.secboot.fd and OVMF_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=on and QEMU_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 .run script the TPM option is QEMU_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 a tpm-crb device connected to the swtpm the .run script starts (README.md:941-942, image-garden.1:665-669).

03 The first boot seals the keys

THE FIRST BOOT $ image-garden make ubuntu-core-24+tpm.x86_64.qcow2 ubuntu-core-24+tpm.x86_64.tpm/ new and empty, mode 700 swtpm QEMU, install mode, seed ubuntu-data, encrypted ubuntu-save, encrypted keys sealed to the TPM state the serial log, ubuntu-core-24+tpm.x86_64.qcow2.log, shows the guest's journal QEMU powers off, swtpm exits with it ubuntu-core-24+tpm.x86_64.qcow2: QEMU was stopped by a signal before the install finished
Making ubuntu-core-24+tpm.x86_64.qcow2 creates the empty state directory ubuntu-core-24+tpm.x86_64.tpm with mode 700, starts swtpm on it and boots QEMU in install mode with the seed. Ubuntu Core encrypts ubuntu-data and ubuntu-save and seals the keys to the TPM state. The serial log shows the guest's journal; swtpm exits with QEMU; a QEMU stopped by a signal fails the make

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 .qcow2 rule: checks swtpm, rm -rf and mkdir -m 700 the state directory, creates the overlay, makes a run directory under $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX (or $TMPDIR), runs swtpm 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_ERROR removes 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 and CRYPT-* devices under /run/mnt/data and /run/mnt/ubuntu-save (spread-demo/tests/smoke/tpm/task.yaml:15-51).

04 Three things that belong together

THREE THINGS TOGETHER ubuntu-core-24+tpm.x86_64.qcow2 ubuntu-core-24+tpm.x86_64.efi-vars.qcow2 ubuntu-core-24+tpm.x86_64.tpm/ the keys are sealed to the TPM state, with the disk and variables of the first boot copy or remove the three as one $ ../ubuntu-core-24+tpm.x86_64.run ../ubuntu-core-24+tpm.x86_64.run: run this launcher from its own directory, /home/you/project: its disk is sealed to the TPM state there ./ubuntu-core-24+tpm.x86_64.run: the TPM state, /home/you/project/ubuntu-core-24+tpm.x86_64.tpm, is missing: make the .qcow2 image again
ubuntu-core-24+tpm.x86_64.qcow2, its .efi-vars.qcow2 and the .tpm directory belong together: the keys are sealed to the TPM state with the disk and variables of the first boot, so copy or remove them as one. Run from another directory, the launcher says run this launcher from its own directory; without the state directory it says the TPM state is missing: make the .qcow2 image again

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 -P with 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/project is an example.
  • The README: the SYSTEM.x86_64.tpm/ directory "belongs with the .qcow2 and .efi-vars.qcow2 files: copy or remove them together" (README.md:711-716, README.md:836-837). make clean removes the .tpm directories (mk/050-ubuntu-core.mk:314-318).
  • That a copy of only the disk will not unlock is derived from sealing, not run.

05 Every launch starts its own swtpm

EVERY LAUNCH .run starts swtpm $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX/ swtpm.sock swtpm.pid QEMU QEMU exits, swtpm follows, a watcher removes the directory ./ubuntu-core-24+tpm.x86_64.run -snapshot … cp -a "$tpm_state_dir" "$tpm_run_dir/state" swtpm gets a copy disk, UEFI variables and TPM state stay as the first boot left them allocate: GARDEN_TPM_RUN_DIR=$XDG_RUNTIME_DIR/image-garden/port.PORT.tpm discard: stops swtpm if needed, removes the directory
Each start of the .run script first starts swtpm with its socket in a fresh $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX directory and gives QEMU the TPM; when QEMU exits swtpm follows and a watcher removes the directory. With -snapshot, as allocate runs it, the disk and variables stay unchanged and swtpm works on a copy of the TPM state. allocate names the directory port.PORT.tpm so that discard can remove it

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 from GARDEN_TPM_RUN_DIR, or mktemp -d under $XDG_RUNTIME_DIR/image-garden (in the snap's runtime directory when run from outside the snap), else under $TMPDIR; with -snapshot among the arguments it copies the state with cp -a; swtpm runs with --terminate --daemon; a watcher tail --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_dir waits for swtpm, kills it if needed and removes the directory (image-garden:833-859).
  • The .run script of any system passes -snapshot on when you give it (see the .run script).

06 What your host needs

WHAT YOUR HOST NEEDS outside the snap swtpm ovmf Secure Boot firmware swtpm, the TPM emulator, is required: install the swtpm package the container swtpm ovmf both installed the snap +qemu-x86-64 the firmware +swtpm not automatic install the swtpm component to use systems with a TPM: snap install image-garden+swtpm before any download with it, the image-garden.swtpm app runs swtpm for a launcher started outside the snap
Outside the snap the host needs the swtpm and ovmf packages, and make stops with swtpm, the TPM emulator, is required: install the swtpm package. The container has both. The snap has the Secure Boot firmware in its qemu-x86-64 component and swtpm in a component of its own, not installed automatically; without it make stops before the download with install the swtpm component to use systems with a TPM: snap install image-garden+swtpm. The image-garden.swtpm app serves launchers started outside the snap

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

07 Where to go from here

ROADS Secure Boot and TPM Launching with swtpm each launch, step by step +dangerous systems your own kernel snapd map: encryption what decides it The snap's swtpm component and app Ubuntu Core images the other releases UEFI firmware the Secure Boot pair
Roads from Secure Boot and TPM: how a TPM system is launched, +dangerous systems, encryption on the snapd map, the snap's swtpm component, Ubuntu Core images and UEFI firmware

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

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

SystemHost name in the guestDownloaded imagecdimage directory
ubuntu-core-24+tpm.x86_64ubuntu-core-24-tpmubuntu-core-24-amd64.img.xzubuntu-core/24/stable
ubuntu-core-24+dangerous+tpm.x86_64ubuntu-core-24-dangerous-tpmubuntu-core-24+dangerous-amd64.img.xzubuntu-core/24/dangerous-stable
ubuntu-core-26+tpm.x86_64ubuntu-core-26-tpmubuntu-core-26-amd64.img.xzubuntu-core/26/stable
ubuntu-core-26+dangerous+tpm.x86_64ubuntu-core-26-dangerous-tpmubuntu-core-26+dangerous-amd64.img.xzubuntu-core/26/dangerous-stable

In spread they are ubuntu-core-24-plus-tpm and so on (see system names).

Files next to each system

FileMade byHolds
X.qcow2the provisioning bootthe encrypted disk, an overlay on the shared download
X.efi-code.qcow2$(QEMU_IMG) convert of efi-secboot-code.x86_64.imgOVMF Secure Boot code
X.efi-vars.qcow2$(QEMU_IMG) convert of efi-secboot-vars.x86_64.imgthe UEFI variables, Microsoft keys enrolled
X.tpm/mkdir -m 700 in the .qcow2 ruleswtpm's TPM state, to which the keys are sealed
X.qcow2.logteethe serial console of the provisioning boot, with the journal
X.runthe launcher rulestarts swtpm, then QEMU

Messages

MessageWhen
swtpm, the TPM emulator, is required: install the swtpm packageno swtpm on PATH, at make or launch
install the swtpm component to use systems with a TPM: snap install image-garden+swtpmin 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 finishedthe provisioning QEMU was killed
$0: run this launcher from its own directory, DIR: its disk is sealed to the TPM state therelauncher started from elsewhere
$0: the TPM state, DIR/X.tpm, is missing: make the .qcow2 image againthe 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_64a +tpm goal on aarch64

What each install needs

InstallswtpmSecure Boot OVMF
Distribution or sourcethe swtpm packagethe ovmf package
Containerincludedincluded
Snapsnap install image-garden+swtpmin the qemu-x86-64 component

Roads from here

UBUNTU CORE · all snaps

ARCHITECTURES · machines and firmware

RUNTIME · make rules and the CLI

SNAP · snap-only features

Snapd map ↗