.\" SPDX-License-Identifier: MIT
.
.Dd February 29, 2024
.ds doc-volume-operating-system
.Dt ZFS-FIDO2-CHANGE-KEY 8
.Os fzifdso 0
.
.Sh NAME
.Nm zfs-fido2-change-key
.Nd change ZFS dataset key to one authenticated by a FIDO2 device
.Sh SYNOPSIS
.Nm
.Op Fl b Ar backup-file
.Ar dataset
.
.Sh DESCRIPTION
To normalise the
.Ar dataset ,
.Nm
will open its encryption root in its stead.
.Nm
will
.Em never
create or destroy encryption roots; use
.Xr zfs-change-key 8
for that.
.Pp
First, a connection is made to the FIDO2 device, which
.Em must
support the
.Ql hmac-secret
extension.
.Pp
If
.Ar dataset
was previously encrypted with
.Nm fzifdso
and the
.Sy FIDO2
back-end was used, the metadata will be silently cleared.
Otherwise, or in case of an error, data required for manual intervention will be written to the standard error stream.
.Pp
Next, a new credential of type ES256 is generated on the device (with relying party ID
.Li fzifdso
and name equal to the dataset name)
with the
.Ql hmac-secret
extension requested; the device PIN, if any, is prompted for here.
This mimicks a WebAuthn registration step.
.Pp
Then, the credential is asserted with a 32-byte random salt,
which hashes it with device-private data, and thus generates the wrapping key
.Pq which is optionally backed up Pq see Sx OPTIONS .
This mimicks a WebAuthn login step.
.Pp
The following properties are set on
.Ar dataset :
.Bl -bullet -compact -offset 4n -width "@"
.It
.Li xyz.nabijaczleweli:tzpfms.backend Ns = Ns Sy FIDO2
.It
.Li xyz.nabijaczleweli:tzpfms.key Ns = Ns Ar salt Ns Cm :\:\& Ns Ar credential-ID Ns Cm :\:\& Ns Ar credential-public-key Ns Oo Cm \&. Ns … Oc Ns …
.El
.Pp
.Li tzpfms.backend
identifies this dataset for work with
.Sy FIDO2 Ns -back-ended
.Nm tzpfms
tools
.Pq i.e. Nm fzifdso Xr zfs-fido2-change-key 8 , Xr zfs-fido2-load-key 8 , Xr zfs-fido2-add-backup 8 , and Xr zfs-fido2-clear-key 8 .
.Pp
.Li 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 \(en its public key.
There exists no other user-land tool for deciphering this; perhaps there should be.
.\"" TODO: make an LD_PRELOADable for extracting the key maybe?
.Pp
Finally, the equivalent of
.Nm zfs Cm change-key Fl o Li keylocation=prompt Fl o Li keyformat=raw Ar 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.
.Pp
A final verification should be made by running
.Nm zfs-fido2-load-key Fl n Ar dataset .
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a passphrase with
.Nm zfs-fido2-clear-key Ar dataset
.Pq or, if that fails to work, Nm zfs Cm change-key Fl o Li keyformat=passphrase Ar dataset ,
and you are hereby asked to report a bug, please.
.Pp
.Nm zfs-fido2-clear-key Ar dataset
can be used to clear the properties and go back to using a passphrase.
.
.Sh OPTIONS
.Bl -tag -compact -width ".Fl b Ar backup-file"
.It Fl b Ar backup-file
Save a back-up of the key to
.Ar backup-file ,
which must not exist beforehand.
This back-up
.Em must
be stored securely, off-site.
In case of a catastrophic event, the key can be loaded by running
.Dl Nm zfs Cm load-key Ar dataset Li < Ar backup-file
.El
.
.\" SPDX-License-Identifier: MIT
.
.Sh ENVIRONMENT VARIABLES
.Bl -tag -compact -width 4n
.It Ev TZPFMS_PASSPHRASE_HELPER
By default, passphrases are prompted for and read in on the standard output and input streams.
If
.Ev TZPFMS_PASSPHRASE_HELPER
is set and nonempty, it will be run via
.Pa /bin/ Ns Nm sh Fl c
to provide each passphrase, instead.
.Pp
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:
.Bl -tag -compact -offset 2n -width ".Li $1"
.It Li $1
Pre-formatted noun phrase with all the information below, for use as a prompt
.\" Passphrase for tarta-zoot
.\" New passphrase for tarta-zoot (again)
.It Li $2
Either the dataset name or the element of the TPM hierarchy being prompted for
.It Li $3
.Qq new
if this is for a new passphrase, otherwise blank
.It Li $4
.Qq again
if it's the second prompt for that passphrase, otherwise blank
.El
.Pp
If the helper doesn't exist
.Pq the shell exits with Sy 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.
.
.
.El
.
.\" SPDX-License-Identifier: MIT
.
.Sh FIDO2 back-end configuration
.Ss Environment variables
.Bl -tag -compact -width ".Ev FIDO_DEBUG"
.It Ev FIDO_DEBUG
If set, enables libfido2 debug logging to the standard error stream.
.El
.
.Ss Device selection
When creating, the first device which supports the
.Ql hmac-secret
extension is used.
When loading, the assertion is shopped around to every such device.
.
.Ss See also
The libfido2 documentation at
.Lk https:/\&/developers.yubico.com/libfido2/ .
.
.\" SPDX-License-Identifier: MIT
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.Bl -bullet -offset 4n -compact -width "@"
.It
ThePhD
.It
Embark Studios
.It
Jasper Bekkers
.It
EvModder
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/\(tinabijaczleweli/fzifdso
.Pp
.Mt \(tinabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/\(tinabijaczleweli/tzpfms .