NAME

zfs-tpm2-change-key — change ZFS dataset key to one stored on the TPM

SYNOPSIS

zfs-tpm2-change-key [-b backup-file] [-P algorithm:PCR[,PCR]…[+algorithm:PCR[,PCR]…]… [-A]] dataset

DESCRIPTION

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

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

If dataset was previously encrypted with tzpfms and the TPM2 back-end was used, the previous key will be freed from the TPM. Otherwise, or in case of an error, data required for manual intervention will be written to the standard error stream.

Next, a new wrapping key is generated on the TPM, optionally backed up (see OPTIONS), and sealed to a persistent object on the TPM under the owner hierarchy; if there is a passphrase set on the owner hierarchy, the user is prompted for it; the user is always prompted for an optional passphrase to protect the sealed object with.

The following properties are set on dataset:

xyz.nabijaczleweli:tzpfms.backend=TPM2
xyz.nabijaczleweli:tzpfms.key=persistent-object-ID[;algorithm:PCR[,PCR]…[+algorithm:PCR[,PCR]…]…]

tzpfms.backend identifies this dataset for work with TPM2-back-ended tzpfms programs (namely zfs-tpm2-change-key(8), zfs-tpm2-load-key(8), and zfs-tpm2-clear-key(8)).

tzpfms.key is an integer representing the sealed object, optionally followed by a semicolon and PCR list as specified with -P, normalised to be tpm-tools-toolchain-compatible; if needed, it can be passed to tpm2_unseal -c ${tzpfms.key%%;*} with -p "str:${passphrase}" or -p "pcr:${tzpfms.key#*;}", as the case may be, or equivalent, for back-up (see OPTIONS). If you have a sealed key you can access with that or equivalent tool and set both of these properties, it will funxion seamlessly.

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 persistent object and properties, or to issue a note for manual intervention into the standard error stream.

A final verification should be made by running zfs-tpm2-load-key -n dataset. If that command succeeds, all is well, but otherwise the dataset can be manually rolled back to a passphrase with zfs-tpm2-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-tpm2-clear-key dataset can be used to free the TPM persistent object and go back to using a passphrase.

OPTIONS

-b 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

-P algorithm:PCR[,PCR]…[+algorithm:PCR[,PCR]…]…

Bind the key to space- or comma-separated PCRs within their corresponding hashing algorithm — if they change, the wrapping key will not be able to be unsealed. There are 24 PCRs, numbered [0, 23].

algorithm may be any of case-insensitive "sha1", "sha256", "sha384", "sha512", "sm3_256", "sm3-256", "sha3_256", "sha3-256", "sha3_384", "sha3-384", "sha3_512", or "sha3-512", and must be supported by the TPM.

-A

With -P, also prompt for a passphrase. This is skipped by default because the passphrase is ORed with the PCR policy — the wrapping key can be unsealed either passphraseless with the right PCRs or with the passphrase, and this is usually not the intent.

ENVIRONMENT VARIABLES

TZPFMS_PASSPHRASE_HELPER

By default, passphrases are prompted for and read in on the standard output and input streams. If TZPFMS_PASSPHRASE_HELPER is set and nonempty, it will be run via /bin/sh -c to provide each passphrase, instead.

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:

$1: Pre-formatted noun phrase with all the information below, for use as a prompt
$2: Either the dataset name or the element of the TPM hierarchy being prompted for
$3: "new" if this is for a new passphrase, otherwise blank
$4: "again" if it's the second prompt for that passphrase, otherwise blank

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

TPM2 back-end configuration

Environment variables

TSS2_LOG: Any of: NONE, ERROR, WARNING, INFO, DEBUG, TRACE. Default: WARNING.

TPM selection

The library libtss2-tcti-default.so can be linked to any of the libtss2-tcti-*.so libraries to select the default, otherwise /dev/tpmrm0, then /dev/tpm0, then localhost:2321 will be tried, in order (see ESYS_CONTEXT(3)).