ZFS-FIDO2-ADD-BACKUP(8) System Manager's Manual ZFS-FIDO2-ADD-BACKUP(8)

zfs-fido2-add-backup — allow another FIDO2 device to unlock ZFS dataset

zfs-fido2-add-backup dataset

After zfs-fido2-change-key(8) derives the key for a dataset from a FIDO2 device, zfs-fido2-add-backup may be executed to extend this to any number of additional devices.

First, the wrapping key is extracted as normally during zfs-fido2-load-key(8), then a credential is made as-if during zfs-fido2-change-key(8) (except the "primary" device and all the ones holding backups are excluded from the search); however, the ‘hmac-secret’ is instead used as a symmetric AES-256-GCM (EVP_CIPHER-AES(7ssl)) key to encrypt the wrapping key directly with a random IV.

This turns the xyz.nabijaczleweli:tzpfms.key variable into
salt:credential-ID:credential-public-key[.backup-salt:backup-credential-ID:backup-credential-public-key:IV:encrypted-key]…

tzpfms.key is actually a dot-separated list of device bundles. The first one is as-described in zfs-fido2-change-key(8). Subsequent ones also include (identically-encoded) IVs and encrypted blobs.

zfs-fido2-load-key(8) shops assertions around devices in a device-major order — depending on device numbering, a backup may be loaded even if the primary device is present.

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 element of the TPM hierarchy 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 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.

February 29, 2024 fzifdso 0