.\" SPDX-License-Identifier: MIT
.
.Dd March  4, 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, previous credentials will be deleted from their devices (as-if via
.Xr 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.
.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 .