#tzpfms

TPM-based encryption keys for ZFS datasets.

See also fzifdso for FIDO2/WebAuthn-based (YubiKey, Somu, &c.) keys.

#Manpages (PDF)

#Why?

T P M
 Z F S

Plus it's a pretty good annoyed sigh onomatopoeia.

#What?

Essentially BitLocker, but for ZFS – a random raw key is generated and sealed to the TPM (both 2 and 1.x supported) with an additional optional password in front of it, tying the dataset to the platform and an additional optional secret (or to the posession of the back-up).

Additionally, 1.x TPMs support PCR binding with and without passwords. 2 TPMs support PCR binding without a password and PCR binding OR a password – both may be set, and any can be used to unseal (exclusive by default to prevent foot-guns).

Both dracut (with/without Plymouth) (with/without hostonly) (only on systemd systems, I don't have a test-bed for the non-systemd path) and initramfs-tools (with/without Plymouth) are supported for ZFS-on-root set-ups.

#Building

You'll need pkgconf, shellcheck, libzfslinux-dev (0.8.x and 2.[012].x work), libtss2-dev, libtspi-dev, libssl-dev, and make should hopefully Just Work™ if you have a C++17-capable compiler. The output binaries are trimmed of extraneous dependencies, so they're all just libc + libzfs and friends + the chosen TPM back-end, if any + libcrypto for TPM2 PCR handling.

mandoc is required for HTML manuals. Set MANDOC=true to forgo this.

The default $TZPFMS_PASSPHRASE_HELPER is the null string. To set a different default, set TZPFMS_PASSPHRASE_HELPER and TZPFMS_PASSPHRASE_HELPER_MAN for make — $s need to be double-escaped and 's need to be full-' escaped (i.e. '\'').

As an example, for a sensible default value of exec systemd-ask-password --id="tzpfms:$2" "$1:" for OOB systemd integration, pass TZPFMS_PASSPHRASE_HELPER='exec systemd-ask-password --id="tzpfms:$$2" "$$1:"' and TZPFMS_PASSPHRASE_HELPER_MAN='Ic exec Nm systemd-ask-password Fl -id Ns Li = Ns Qo Li tzpfms:\& Ns Ar $$2 Qc Qo Ar $$1 Ns Li ":\&" Qc'.

#Installation

Copy the out/zfs-tpm* binaries corresponding to the back-ends you want to /sbin, continue as the manual page instructs.

For initrd support, copy the content of either out/dracut/ or out/initramfs-tools/ over /; these need zfs-tpm-list but will work with any combination of back-end *-load-key binaries (local TPM1.X initrds need to be updated when the system state changes (e.g. the TPM is taken ownership of)).

To integrate with zfs-mount-generator(8) copy out/systemd/ over /.

#From Debian repository

The following line in /etc/apt/sources.list or equivalent:

deb [signed-by=/etc/apt/keyrings/nabijaczleweli.asc] https://debian.nabijaczleweli.xyz sid main

With my PGP key (the two URLs are interchangeable):

sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://debian.nabijaczleweli.xyz/nabijaczleweli.gpg.key
sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://nabijaczleweli.xyz/pgp.txt

(you may need to create /etc/apt/keyrings on apt <2.4.0 (<=bullseye) manually).

Then the usual

sudo apt update
sudo apt install tzpfms-tpm2 tzpfms-dracut

will work on amd64, x32, and i386.

See the repository README for more information.

#From tar-ball

Release tarballs are signed with nabijaczleweli@nabijaczleweli.xyz (pull with WKD, but 7D69 474E 8402 8C5C C0C4 4163 BCFD 0B01 8D26 58F1). аnd stored in git notes as-if via the example program and are thus available on the refs listing/tag page as .tar.gz.asc.

#Testing

#TPM2

Install swtpm, then prepare and run it:

swtpm_setup --tpmstate tpm2-state --tpm2 --createek --display --logfile /dev/tty --overwrite
swtpm socket --server type=tcp,port=2321 --ctrl type=tcp,port=2322 --tpm2 --tpmstate dir=tpm2-state --flags not-need-init --log level=10

If your platform has a TPM, switch to swtpm by default:

ln -s /usr/lib/i386-linux-gnu/libtss2-tcti-{swtpm,default}.so

#TPM1.x

Install swtpm, then prepare and run it and (hopefully) TrouSerS, as root/tpm:

swtpm_setup --tpmstate tpm1x-state --createek --display --logfile /dev/tty --overwrite
swtpm cuse -n tpm --tpmstate dir=tpm1x-state --seccomp action=none --log level=10,file=/dev/fd/4 4>&1
swtpm_ioctl -i /dev/tpm
TPM_DEVICE=/dev/tpm swtpm_bios
tcsd -f

swtpm_ioctl -s /dev/tpm  # to shut down, apparently

If your platform has a TPM, occupy it first by running exec 100<>/dev/tpm0 or equivalent. tcsd looks at /dev/tpm0 before /dev/tpm.

#initrd

Running

swtpm socket --ctrl type=unixio,path=/tmp/swtpm --tpm2 --tpmstate dir=tpm2-state --flags not-need-init --log level=10
# or
swtpm socket --ctrl type=unixio,path=/tmp/swtpm --tpmstate dir=tpm1x-state --log level=10

instead, alongside passing

-chardev socket,id=chrtpm,path=/tmp/swtpm -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0

to QEMU will create a TPM device on the guest which Should® be fully funxional.

#Reporting bugs

There's the tracker, but also see the list below.

#Contributing

Send a patch inline, as an attachment, or a git link and a ref to pull from to the list (~nabijaczleweli/tzpfms@lists.sr.ht) or me directly. I'm not picky, just please include the repo name in the subject prefix.

#"Ecosystem"

Put a line containing the zfs-{...}-load-key program name followed by a list of required services (if any) into /usr/share/tzpfms/${tzpfms.backend} and the zfs-load-key@.service drop-in will understand it and use it to load.

Known compatible backends:

#Discussion

Please use the tracker, the list, or mastussy (formerly Twitter).

#Special thanks

To all who support further development on Patreon, in particular:

• ThePhD
• Embark Studios
• Jasper Bekkers
• EvModder