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 as
/bin/sh -c "$TZPFMS_PASSPHRASE_HELPER" "$TZPFMS_PASSPHRASE_HELPER" "prepared prompt" "target" "[new]" "[again]"
to provide a passphrase, instead of reading from the standard input.

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 second argument contains either the dataset name or the element of the TPM hierarchy. The third argument is new if this is for a new passphrase, and the fourth is again if it's the second prompt for that passphrase. The first argument already contains all of this information, as a pre-formatted noun phrase.

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.

An example value would be: 'systemd-ask-password --id="tzpfms:$2" "$1: "'.

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 15, 2021 tzpfms 0.1-14