ZFS-TPM1X-CHANGE-KEY(8) System Manager's Manual ZFS-TPM1X-CHANGE-KEY(8)

zfs-tpm1x-change-keychange ZFS dataset key to one stored on the TPM

zfs-tpm1x-change-key [-b backup-file] dataset

To normalise the dataset, zfs-tpm1x-change-key will open its encryption root in its stead. zfs-tpm1x-change-key will create or destroy encryption roots; use zfs-change-key(8) for that.

First, a connection is made to the TPM, which must be TPM-1.X-compatible.

If dataset was previously encrypted with tzpfms and the TPM1.X back-end was used, the metadata will be silently cleared. Otherwise, or in case of an error, data required for manual intervention will be printed to the standard error stream.

Next, a new wrapping key is generated on the TPM, optionally backed up (see OPTIONS), and sealed on the TPM; the user is prompted for an optional passphrase to protect the key with, and for the SRK passphrase, set when taking ownership, if not "well-known" (all zeroes).

The following properties are set on dataset:

tzpfms.backend identifies this dataset for work with TPM1.X-back-ended tzpfms tools (namely zfs-tpm1x-change-key(8), zfs-tpm1x-load-key(8), and zfs-tpm1x-clear-key(8)).

tzpfms.key is a colon-separated pair of hexadecimal-string (i.e. "4F7730" for "Ow0") blobs; the first one represents the RSA key protecting the blob, and it is protected with either the password, if provided, or the SHA1 constant CE4CF677875B5EB8993591D5A9AF1ED24A3A8736; the second represents the sealed object containing the wrapping key, and is protected with the SHA1 constant B9EE715DBE4B243FAA81EA04306E063710383E35. There exists no other user-land tool for decrypting this; perhaps there should be.

Finally, the equivalent of zfs change-key -o keylocation=prompt -o keyformat=raw dataset is performed with the new key. If an error occurred, best effort is made to clean up the properties, or to issue a note for manual intervention into the standard error stream.

A final verification should be made by running zfs-tpm1x-load-key -n dataset. If that command succeeds, all is well, but otherwise the dataset can be manually rolled back to a password with zfs-tpm1x-clear-key dataset (or, if that fails to work, zfs change-key -o keyformat=passphrase dataset), and you are hereby asked to report a bug, please.

zfs-tpm1x-clear-key dataset can be used to clear the properties and go back to using a password.

backup-file
Save a back-up of the key to backup-file, which must not exist beforehand. This back-up must be stored securely, off-site. In case of a catastrophic event, the key can be loaded by running
zfs load-key dataset < backup-file

If set and nonempty, will be run via /bin/sh -c to provide a passphrase, instead of reading from the standard input stream.

The standard output stream of the helper is tied to an anonymous file and used in its entirety as the passphrase, except for a trailing new-line, if any. The arguments are:

Pre-formatted noun phrase with all the information below, like "Passphrase for tarta-zoot" or "New passphrase for tarta-zoot (again)"
Either the dataset name or the element of the TPM hierarchy
"new" if this is for a new passphrase
"again" if it's the second prompt for that passphrase

If the helper doesn't exist (the shell exits with ), a diagnostic is issued and the normal prompt is used as fall-back. If it fails for any other reason, the prompting is aborted.

The tzpfms suite connects to a local tcsd(8) process (at localhost:30003) by default. Use the environment variable TZPFMS_TPM1X to specify a remote TCS hostname.

The TrouSerS tcsd(8) daemon will try /dev/tpm0, then /udev/tpm0, then /dev/tpm; by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.

The TrouSerS project page at https://sourceforge.net/projects/trousers.

The TPM 1.2 main specification index at https://trustedcomputinggroup.org/resource/tpm-main-specification.

To all who support further development, in particular:

https://todo.sr.ht/~nabijaczleweli/tzpfms

~nabijaczleweli/tzpfms@lists.sr.ht, archived at https://lists.sr.ht/~nabijaczleweli/tzpfms.

https://git.sr.ht/~nabijaczleweli/tzpfms

November 20, 2021 tzpfms 0.1-18