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

zfs-fido2-change-key — change ZFS dataset key to one authenticated by a FIDO2 device

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

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

First, a connection is made to the FIDO2 device, which must support the ‘hmac-secret’ extension.

If dataset was previously encrypted with fzifdso and the FIDO2 back-end was used, previous credentials will be deleted from their devices (as-if via zfs-fido2-clear-key(8)), if available. Otherwise, or in case of an error, data required for manual intervention will be written to the standard error stream.

Next, a new credential of type ES256 is generated on the device (with relying party ID fzifdso and name equal to the dataset name) with the ‘hmac-secret’ extension requested; the device PIN, if any, is prompted for here. This mimicks a WebAuthn registration step.

Then, the credential is asserted with a 32-byte random salt, which hashes it with device-private data, and thus generates the wrapping key (which is optionally backed up (see OPTIONS)). This mimicks a WebAuthn login step.

The following properties are set on dataset:

tzpfms.backend identifies this dataset for work with FIDO2-back-ended tzpfms tools (i.e. fzifdso zfs-fido2-change-key(8), zfs-fido2-load-key(8), zfs-fido2-add-backup(8), and zfs-fido2-clear-key(8)).

tzpfms.key is a colon-separated tuple of unpadded URL-safe base64 blobs; the first one is the random salt; the second represents the ID of created credential, and the third – its public key. There exists no other user-land tool for deciphering 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-fido2-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-fido2-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-fido2-clear-key dataset can be used to clear the properties and go back to using a passphrase.

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

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:

Pre-formatted noun phrase with all the information below, for use as a prompt
Either the dataset name or the device feature being prompted for
"new" if this is for a new passphrase, otherwise blank
"again" if it's the second prompt for that passphrase, otherwise blank

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.

If set, enables libfido2 debug logging to the standard error stream.

When creating, the first device which supports the ‘hmac-secret’ extension is used. When loading, the assertion yielding the key is shopped around to every such device.

The libfido2 documentation at https://developers.yubico.com/libfido2/.

To all who support further development, in particular:

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

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

March 4, 2024 fzifdso 0.4.1