Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

OS support #99

Merged
merged 5 commits into from
Aug 24, 2022
Merged

OS support #99

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8bcad4f
Emulating-Heads.md: Add qemu-coreboot-fbwhiptail-tpm1-hotp target
JonathonHall-Purism Aug 17, 2022
155377f
install-os.md: Document OS compatibility
JonathonHall-Purism Aug 17, 2022
c596754
Emulating-Heads.md: Add NitrokeyStorage option for USB_TOKEN
JonathonHall-Purism Aug 17, 2022
5afa09a
Emulating-Heads-md: Move qemu-coreboot-fbwhiptail-tpm1-hotp doc in repo
JonathonHall-Purism Aug 23, 2022
2d7dfdc
Emulating-Heads.md: Add missing '.md' in link
JonathonHall-Purism Aug 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions Development/Emulating-Heads.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -18,10 +32,82 @@ 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
* Xen won't start dom0 correctly, but it is sufficient to test that the
`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=<path_to_installer.iso> 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=<token> run`
* For `<token>`, use one of:
* `NitrokeyPro` - a Nitrokey Pro by VID/PID
* `LibremKey` - a Librem Key by VID/PID
JonathonHall-Purism marked this conversation as resolved.
Show resolved Hide resolved
* `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=<path_to_key.asc> inject_gpg`
* `make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp USB_TOKEN=LibremKey PUBKEY_ASC=<path_to_key.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`
29 changes: 26 additions & 3 deletions Installing-and-Configuring/install-os.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.).
Expand Down Expand Up @@ -50,6 +50,29 @@ Each ISO file is verified for integrity and authenticity before booting so that
gpg --output <iso_name>.sig --detach-sig <iso_name>
```

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.
Expand Down