From 8bcad4fd6a495ecbc735bd194a14e283a4fff978 Mon Sep 17 00:00:00 2001 From: Jonathon Hall Date: Wed, 17 Aug 2022 14:39:04 -0400 Subject: [PATCH 1/5] Emulating-Heads.md: Add qemu-coreboot-fbwhiptail-tpm1-hotp target Signed-off-by: Jonathon Hall --- Development/Emulating-Heads.md | 86 ++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/Development/Emulating-Heads.md b/Development/Emulating-Heads.md index c3743f59..1f2a0e95 100644 --- a/Development/Emulating-Heads.md +++ b/Development/Emulating-Heads.md @@ -6,6 +6,20 @@ nav_order: 2 parent: Development --- +Available Targets +=== + +Multiple qemu targets are provided for Heads. + +| Target | Interface | Features | +|--|--|--|--| +| `qemu-coreboot` | Text | Basic build/boot test | +| `qemu-coreboot-fbwhiptail` | Graphical | Basic build/boot test | +| `qemu-coreboot-fbwhiptail-tpm1-hotp` | Graphical | TPM, HOTP with USB token, /boot signing and OS booting. | + +Basic build/boot tests +=== + Generate the `qemu.rom` image: ```Makefile @@ -18,6 +32,8 @@ Boot it in qemu: build/make-4.2/make BOARD=qemu-coreboot run ``` +Use `qemu-coreboot-fbwhiptail` as the board instead for the graphical interface. + Issues with emulation: * TPM is not available @@ -25,3 +41,73 @@ Issues with emulation: `initrd.cpio` file was correctly generated * This also lets us test Xen patches for legacy-free systems * SATA controller sometimes takes minutes to timeout? + +Comprehensive test +=== + +The `qemu-coreboot-fbwhiptail-tpm1-hotp` configuration permits testing of most features of Heads. It + requires a supported USB token (which will be reset for use with the VM, do not use a token needed for a + real machine). With KVM acceleration, speed is comparable to a real machine. If KVM is unavailable, + lightweight desktops are still usable. + +Heads is currently unable to reflash firmware within qemu, which means that OEM reset and re-ownership + cannot be fully performed within the VM. Instead, a GPG key can be injected in the Heads image from the + host during the build. + +The TPM and disks for this configuration are persisted in the build/qemu-coreboot-fbwhiptail-tpm1-hotp/ directory. + +To bootstrap a complete working VM from scratch: + +1. Install QEMU and swtpm. (Optionally, KVM.) + * Many distributions already package swtpm, but Debian Bullseye does not. (Bookworm does.) On Bullseye you will have to build and install libtpms and swtpm from source, and you will need to create AppArmor rules manually - see below. + * https://github.com/stefanberger/libtpms + * https://github.com/stefanberger/swtpm +2. Build Heads + * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp` +3. Install OS + * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp INSTALL_IMG= run` + * Lightweight desktops (XFCE, LXDE, etc.) are recommended, especially if KVM acceleration is not available (such nested in Qubes OS) + * When running nested in a qube, disable memory ballooning for the qube, or performance will be very poor. + * Include `QEMU_MEMORY_SIZE=6G` to set the guest's memory (`6G`, `8G`, etc.). The default is 4G to be conservative, but more may be needed depending on the OS. + * Include `QEMU_DISK_SIZE=30G` to set the guest's disk size, the default is `20G`. +4. Shut down and boot Heads with the USB token attached, proceed with OEM reset + * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp USB_TOKEN= run` + * For ``, use one of: + * `NitrokeyPro` - a Nitrokey Pro by VID/PID + * `LibremKey` - a Librem Key by VID/PID + * `hostbus=#,hostport=#` - indicate a host bus and port (see qemu usb-host) + * `vendorid=#,productid=#` - indicate a device by VID/PID (decimal, see qemu usb-host) + * You _do_ need to export the GPG key to a USB disk, otherwise defaults are fine. + * Head will show an error saying it can't flash the firmware, continue + * Then Heads will indicate that there is no TOTP code yet, at this point shut down (Continue to main menu -> Power off) +5. Get the public key that was saved to the virtual USB flash drive + * `sudo mkdir /media/fd_heads_gpg` + * `sudo mount ./build/qemu-coreboot-fbwhiptail-tpm1-hotp/usb_fd.raw /media/fd_heads_gpg` + * Look in `/media/fd_heads_gpg` and copy the most recent public key + * `sudo umount /media/fd_heads_gpg` +6. Inject the GPG key into the Heads image and run again + * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp PUBKEY_ASC= inject_gpg` + * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp USB_TOKEN=LibremKey PUBKEY_ASC= run` +7. Initialize the TPM - select "Reset the TPM" at the TOTP error prompt and follow prompts +8. Select "Default boot" and follow prompts to sign /boot for the first time and set a default boot option + +swtpm on Debian Bullseye +--- + +libtpms and swtpm must be built and installed from source on Debian Bullseye. Upstream provides tooling to build these as Debian packages, which allows things to work seamlessly with default AppArmor configs, etc. + +1. Install dependencies + * `sudo apt install automake autoconf libtool make gcc libc-dev libssl-dev dh-autoreconf libssl-dev libtasn1-6-dev pkg-config net-tools iproute2 libjson-glib-dev libgnutls28-dev expect gawk socat gnutls-bin libseccomp-dev libfuse-dev python3-twisted selinux-policy-dev trousers devscripts equivs` +2. Build libtpms + * `git clone https://github.com/stefanberger/libtpms` + * `cd libtpms; git checkout v0.9.4` (latest release as of this writing) + * `sudo mk-build-deps --install ./debian/control` + * `debuild -us -uc` + * `sudo apt install ../libtpms*.deb` +3. Build swtpm + * `git clone https://github.com/stefanberger/swtpm` + * `cd swtpm; git checkout v0.7.3` (latest release as of this writing) + * `echo "libtpms0 libtpms" > ./debian/shlibs.local` + * `sudo mk-build-deps --install ./debian/control` + * `debuild -us -uc` + * `sudo apt install ../swtpm*.deb` From 155377fbaac6a0d35c1c68828137f4c5c5ce6da8 Mon Sep 17 00:00:00 2001 From: Jonathon Hall Date: Wed, 17 Aug 2022 14:40:19 -0400 Subject: [PATCH 2/5] install-os.md: Document OS compatibility Add OS recommendations and compatibility notes. Live desktop images are recommended. Debian netinst now works in qemu, but it does not work for me on Librem 14 or L1UM (installer is unable to initialize the display after kexec). Minor fixes to formatting. Signed-off-by: Jonathon Hall --- Installing-and-Configuring/install-os.md | 29 +++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/Installing-and-Configuring/install-os.md b/Installing-and-Configuring/install-os.md index b496a859..4a58ab37 100644 --- a/Installing-and-Configuring/install-os.md +++ b/Installing-and-Configuring/install-os.md @@ -20,9 +20,9 @@ parent: Installing and configuring Generic OS Installation === -1. Insert OS installation media into one of the USB3 ports (blue on Thinkpads). -[For certain OSes](https://github.com/osresearch/heads/tree/master/initrd/etc/distro/keys) - , Heads boot process supports standard OS ISO bootable media (where the USB +Insert OS installation media into one of the USB3 ports (blue on Thinkpads). + [For certain OSes](https://github.com/osresearch/heads/tree/master/initrd/etc/distro/keys), + Heads boot process supports standard OS ISO bootable media (where the USB drive contains the ISO installation media alongside of its detached signature). For other OS, you will need to create USB installation media with using `dd` or `unetbootin` etc.). @@ -50,6 +50,29 @@ Each ISO file is verified for integrity and authenticity before booting so that gpg --output .sig --detach-sig ``` +Compatibility +=== + +Heads requires unencrypted `/boot`. Graphical OSes generally have the best support. Debian live installers, + Fedora Workstation (or spins), Qubes, and PureOS all work well. + +* *For Debian*: + 1. Use a live desktop image. The network installer image does not work on all systems. + 2. Ensure `/boot` is unencrypted. Debian 11 defaults to a single encrypted partition, so you must + partition manually. This may not apply to all Debian derivatives. + * Create one 1G ext4 partition mounted at `/boot` + * Create a LUKS container with one ext4 partition mounted at `/`. + * For swap, you can create a swapfile later on the encrypted root, or create a swap partition. +* *For Fedora*: The default partitioning works, but `/` is btrfs by default, which Heads' recovery console does + not support. Use ext4 instead for recovery console support. +* *For Qubes*: Be sure to disconnect USB tokens during configuration on first boot. Otherwise, the Qubes + installer may prevent the creation of a sys-usb qube if they are detected as keyboards (HID devices). If you + are using a USB keyboard, follow the + [Qubes instructions for USB keyboards](https://www.qubes-os.org/doc/usb-qubes/#usb-keyboards). +* *For PureOS*: The default installation works. + +Default Boot and Disk Unlock +=== If you want to set a default option so that you don't have to choose at every boot, you can do so from the menu by selecting 'd' on the confirmation screen. From c59675429008f76492697029fc70e1de7e8d7b70 Mon Sep 17 00:00:00 2001 From: Jonathon Hall Date: Wed, 17 Aug 2022 15:04:47 -0400 Subject: [PATCH 3/5] Emulating-Heads.md: Add NitrokeyStorage option for USB_TOKEN Nitrokey3NFC isn't documented as OTP support is still in development. Signed-off-by: Jonathon Hall --- Development/Emulating-Heads.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Development/Emulating-Heads.md b/Development/Emulating-Heads.md index 1f2a0e95..fd5b664a 100644 --- a/Development/Emulating-Heads.md +++ b/Development/Emulating-Heads.md @@ -74,6 +74,7 @@ To bootstrap a complete working VM from scratch: * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp USB_TOKEN= run` * For ``, use one of: * `NitrokeyPro` - a Nitrokey Pro by VID/PID + * `NitrokeyStorage` - a Nitrokey Storage by VID/PID * `LibremKey` - a Librem Key by VID/PID * `hostbus=#,hostport=#` - indicate a host bus and port (see qemu usb-host) * `vendorid=#,productid=#` - indicate a device by VID/PID (decimal, see qemu usb-host) From 5afa09a7d5f35afdc310a95ea4bd3eb6a1992f5a Mon Sep 17 00:00:00 2001 From: Jonathon Hall Date: Tue, 23 Aug 2022 16:19:20 -0400 Subject: [PATCH 4/5] Emulating-Heads-md: Move qemu-coreboot-fbwhiptail-tpm1-hotp doc in repo Move documentation to board directory in heads repo. Signed-off-by: Jonathon Hall --- Development/Emulating-Heads.md | 68 +--------------------------------- 1 file changed, 2 insertions(+), 66 deletions(-) diff --git a/Development/Emulating-Heads.md b/Development/Emulating-Heads.md index fd5b664a..8f7eeb28 100644 --- a/Development/Emulating-Heads.md +++ b/Development/Emulating-Heads.md @@ -45,70 +45,6 @@ Issues with emulation: Comprehensive test === -The `qemu-coreboot-fbwhiptail-tpm1-hotp` configuration permits testing of most features of Heads. It - requires a supported USB token (which will be reset for use with the VM, do not use a token needed for a - real machine). With KVM acceleration, speed is comparable to a real machine. If KVM is unavailable, - lightweight desktops are still usable. +The `qemu-coreboot-fbwhiptail-tpm1-hotp` configuration permits testing of most features of Heads. -Heads is currently unable to reflash firmware within qemu, which means that OEM reset and re-ownership - cannot be fully performed within the VM. Instead, a GPG key can be injected in the Heads image from the - host during the build. - -The TPM and disks for this configuration are persisted in the build/qemu-coreboot-fbwhiptail-tpm1-hotp/ directory. - -To bootstrap a complete working VM from scratch: - -1. Install QEMU and swtpm. (Optionally, KVM.) - * Many distributions already package swtpm, but Debian Bullseye does not. (Bookworm does.) On Bullseye you will have to build and install libtpms and swtpm from source, and you will need to create AppArmor rules manually - see below. - * https://github.com/stefanberger/libtpms - * https://github.com/stefanberger/swtpm -2. Build Heads - * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp` -3. Install OS - * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp INSTALL_IMG= run` - * Lightweight desktops (XFCE, LXDE, etc.) are recommended, especially if KVM acceleration is not available (such nested in Qubes OS) - * When running nested in a qube, disable memory ballooning for the qube, or performance will be very poor. - * Include `QEMU_MEMORY_SIZE=6G` to set the guest's memory (`6G`, `8G`, etc.). The default is 4G to be conservative, but more may be needed depending on the OS. - * Include `QEMU_DISK_SIZE=30G` to set the guest's disk size, the default is `20G`. -4. Shut down and boot Heads with the USB token attached, proceed with OEM reset - * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp USB_TOKEN= run` - * For ``, use one of: - * `NitrokeyPro` - a Nitrokey Pro by VID/PID - * `NitrokeyStorage` - a Nitrokey Storage by VID/PID - * `LibremKey` - a Librem Key by VID/PID - * `hostbus=#,hostport=#` - indicate a host bus and port (see qemu usb-host) - * `vendorid=#,productid=#` - indicate a device by VID/PID (decimal, see qemu usb-host) - * You _do_ need to export the GPG key to a USB disk, otherwise defaults are fine. - * Head will show an error saying it can't flash the firmware, continue - * Then Heads will indicate that there is no TOTP code yet, at this point shut down (Continue to main menu -> Power off) -5. Get the public key that was saved to the virtual USB flash drive - * `sudo mkdir /media/fd_heads_gpg` - * `sudo mount ./build/qemu-coreboot-fbwhiptail-tpm1-hotp/usb_fd.raw /media/fd_heads_gpg` - * Look in `/media/fd_heads_gpg` and copy the most recent public key - * `sudo umount /media/fd_heads_gpg` -6. Inject the GPG key into the Heads image and run again - * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp PUBKEY_ASC= inject_gpg` - * `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp USB_TOKEN=LibremKey PUBKEY_ASC= run` -7. Initialize the TPM - select "Reset the TPM" at the TOTP error prompt and follow prompts -8. Select "Default boot" and follow prompts to sign /boot for the first time and set a default boot option - -swtpm on Debian Bullseye ---- - -libtpms and swtpm must be built and installed from source on Debian Bullseye. Upstream provides tooling to build these as Debian packages, which allows things to work seamlessly with default AppArmor configs, etc. - -1. Install dependencies - * `sudo apt install automake autoconf libtool make gcc libc-dev libssl-dev dh-autoreconf libssl-dev libtasn1-6-dev pkg-config net-tools iproute2 libjson-glib-dev libgnutls28-dev expect gawk socat gnutls-bin libseccomp-dev libfuse-dev python3-twisted selinux-policy-dev trousers devscripts equivs` -2. Build libtpms - * `git clone https://github.com/stefanberger/libtpms` - * `cd libtpms; git checkout v0.9.4` (latest release as of this writing) - * `sudo mk-build-deps --install ./debian/control` - * `debuild -us -uc` - * `sudo apt install ../libtpms*.deb` -3. Build swtpm - * `git clone https://github.com/stefanberger/swtpm` - * `cd swtpm; git checkout v0.7.3` (latest release as of this writing) - * `echo "libtpms0 libtpms" > ./debian/shlibs.local` - * `sudo mk-build-deps --install ./debian/control` - * `debuild -us -uc` - * `sudo apt install ../swtpm*.deb` +For more information and setup instructions, refer to the [qemu-coreboot-fbwhiptail-tpm1-hotp documentation](https://github.com/osresearch/heads/blob/master/boards/qemu-coreboot-fbwhiptail-tpm1-hotp/qemu-coreboot-fbwhiptail-tpm1-hotp). From 2d7dfdc335c464f12e2942e6b47cf123b1d1ec3b Mon Sep 17 00:00:00 2001 From: Jonathon Hall Date: Tue, 23 Aug 2022 17:07:07 -0400 Subject: [PATCH 5/5] Emulating-Heads.md: Add missing '.md' in link Signed-off-by: Jonathon Hall --- Development/Emulating-Heads.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Development/Emulating-Heads.md b/Development/Emulating-Heads.md index 8f7eeb28..6f930fad 100644 --- a/Development/Emulating-Heads.md +++ b/Development/Emulating-Heads.md @@ -47,4 +47,4 @@ Comprehensive test The `qemu-coreboot-fbwhiptail-tpm1-hotp` configuration permits testing of most features of Heads. -For more information and setup instructions, refer to the [qemu-coreboot-fbwhiptail-tpm1-hotp documentation](https://github.com/osresearch/heads/blob/master/boards/qemu-coreboot-fbwhiptail-tpm1-hotp/qemu-coreboot-fbwhiptail-tpm1-hotp). +For more information and setup instructions, refer to the [qemu-coreboot-fbwhiptail-tpm1-hotp documentation](https://github.com/osresearch/heads/blob/master/boards/qemu-coreboot-fbwhiptail-tpm1-hotp/qemu-coreboot-fbwhiptail-tpm1-hotp.md).