Merge pull request #667 from gibmat/add-swtpm-support

Add swtpm fallback for systems without physical TPM

Author: stgraber

.gitignore

@@ -19,6 +19,7 @@ incus-osd/generate-manifests
 incus-osd/image-customizer
 incus-osd/image-publisher
 incus-osd/incus-osd
+incus-osd/measure-pcrs
 
 mkosi.packages/initrd-tmpfs-root*
 

Makefile

@@ -25,9 +25,15 @@ generate-manifests:
 	(cd incus-osd && go build ./cmd/generate-manifests)
 	strip incus-osd/generate-manifests
 
+.PHONY: measure-pcrs
+measure-pcrs:
+	(cd incus-osd && go build ./cmd/measure-pcrs)
+	strip incus-osd/measure-pcrs
+
 .PHONY: initrd-deb-package
-initrd-deb-package:
+initrd-deb-package: measure-pcrs
 	$(eval OSNAME := $(shell grep "ImageId=" mkosi.conf | cut -d '=' -f 2))
+	cp incus-osd/measure-pcrs mkosi.packages/initrd-tmpfs-root/
 	(cd mkosi.packages/initrd-tmpfs-root && cp initrd-boot-message.service.in initrd-boot-message.service && sed -i -e "s/@OSNAME@/${OSNAME}/" initrd-boot-message.service && debuild)
 	rm -rf mkosi.packages/initrd-tmpfs-root/debian/.debhelper/  mkosi.packages/initrd-tmpfs-root/debian/debhelper-build-stamp \
           mkosi.packages/initrd-tmpfs-root/debian/files \mkosi.packages/initrd-tmpfs-root/debian/initrd-tmpfs-root.postrm.debhelper \

doc/.wordlist.txt

@@ -24,6 +24,7 @@ Furo
 FuturFusion
 GiB
 Github
+homelab
 HTTPS
 Incus
 IncusOS
@@ -69,6 +70,7 @@ proxied
 Proxmox
 Proxmox's
 raidz
+RaspberryPi
 resilver
 RSA
 SLAAC

doc/getting-started/requirements.md

@@ -12,3 +12,9 @@ Minimum system requirements:
 - At least 4GiB of RAM (for system use only)
 - At least 50GiB of storage
 - At least one wired network port
+
+```{note}
+For homelab and evaluation use, it is possible for IncusOS to rely on a software-backed TPM implementation. This is useful in scenarios such as running IncusOS on most consumer-grade ARM systems that may lack physical TPM chips.
+
+Be aware that this will weaken the overall security of the IncusOS server, and is not supported in enterprise deployments. For further details, see [Installing without a TPM](../reference/installing-without-tpm.md).
+```

doc/reference.md

@@ -11,8 +11,9 @@ Applications </reference/applications>
 Services </reference/services>
 System configuration </reference/system>
 API </reference/api>
+Installing without a TPM </reference/installing-without-tpm>
 Partitioning scheme </reference/partitioning-scheme>
 Recovery </reference/recovery>
-Seed </reference/seed>
 Security </reference/security>
+Seed </reference/seed>
 ```

doc/reference/installing-without-tpm.md

@@ -0,0 +1,29 @@
+# Installing without a TPM
+
+IncusOS depends on the TPM in conjunction with Secure Boot to provide trusted measurements of the system state when applying updates and automatically unlocking encrypted storage pools at boot. However, not all hardware systems come with a TPM, and for those that don't it may be cost prohibitive to purchase a TPM. A common example are consumer-grade ARM systems, such as the RaspberryPi.
+
+To support homelab users and others who wish to run IncusOS on physical machines without a TPM, a [`swtpm`-backed](https://github.com/stefanberger/swtpm) TPM can be configured. Please be aware that this will **WEAKEN THE OVERALL SECURITY OF THE INCUSOS SERVER**:
+
+* Unlike a physical TPM, it is trivial to inspect and change the software TPM state.
+
+* A physical TPM has already measured several critical PCR values before the kernel starts booting. IncusOS performs these same measurements early in the boot process, but from user-space. This opens some avenues of attack, but is at least partially mitigated by the Secure Boot configuration.
+
+Running IncusOS in an enterprise environment without a physical TPM is **UNSUPPORTED**.
+
+IncusOS will display a prominent warning on its status screen when running with a software-backed TPM.
+
+```{warning}
+Here Be Dragons!
+
+It must be reiterated that running IncusOS without a physical TPM weakens the overall security of the system and is not intended for use in enterprise deployments.
+
+Any IncusOS system that has ever booted with a software-backed TPM will permanently record this fact and report it via the Security API `system_state_is_trusted` field. IncusOS systems that are not fully trusted may be treated differently by Operations Center or other products that interact with IncusOS via its API.
+```
+
+## Install seed
+
+When configuring the IncusOS [install seed](./seed.md), set the `use_swtpm` field to `true`. This will cause IncusOS to configure a software TPM during installation. This option will only take affect if no physical TPM is detected.
+
+## Running off a live USB drive
+
+If booting IncusOS off of a live USB drive, IncusOS will automatically configure a software TPM on first boot if no physical TPM is detected and then automatically restart. This restart is necessary to properly initialize the software TPM and setting up the encrypted disk partitions for use.