.\" SPDX-License-Identifier: MIT
.
.Dd March  4, 2024
.ds doc-volume-operating-system
.Dt ZFS-FIDO2-CLEAR-KEY 8
.Os fzifdso 0
.
.Sh NAME
.Nm zfs-fido2-clear-key
.Nd rewrap ZFS dataset key in passsword and clear tzpfms FIDO2 metadata
.Sh SYNOPSIS
.Nm
.Ar dataset
.
.Sh DESCRIPTION
After verifying
.Ar dataset
was encrypted with
.Nm tzpfms
backend
.Sy FIDO2 :
.Bl -enum -compact -offset 2n -width 2n
.It
performs the equivalent of
.Nm zfs Cm change-key Fl o Li keylocation=prompt Fl o Li keyformat=passphrase Ar dataset ,
.It
loads the primary and every backup credential, and for each success, if the device containing it supports the
.Ql credMgmt  \" or credentialMgmtPreview
feature and has a PIN set, tries to delete the credential from the device,
.It
removes the
.Li xyz.nabijaczleweli:tzpfms.\& Ns Brq Li backend , key
properties from
.Ar dataset .
.El
.Pp
For every removal failure and missing device or PIN an instruction for manual removal with
.Xr fido2-token 1
is issued.
.Pp
See
.Xr zfs-fido2-change-key 8
for a detailed description.
.
.\" 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 .