mirror of
https://git.sr.ht/~nabijaczleweli/tzpfms
synced 2025-05-01 10:11:30 +03:00
126 lines
3.5 KiB
Groff
126 lines
3.5 KiB
Groff
.\" SPDX-License-Identifier: MIT
|
|
.
|
|
.Dd February 29, 2024
|
|
.ds doc-volume-operating-system
|
|
.Dt ZFS-FIDO2-ADD-BACKUP 8
|
|
.Os fzifdso 0
|
|
.
|
|
.Sh NAME
|
|
.Nm zfs-fido2-add-backup
|
|
.Nd allow another FIDO2 device to unlock ZFS dataset
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar dataset
|
|
.
|
|
.Sh DESCRIPTION
|
|
After
|
|
.Xr zfs-fido2-change-key 8
|
|
derives the key for a dataset from a FIDO2 device,
|
|
.Nm
|
|
may be executed to extend this to any number of additional devices.
|
|
.Pp
|
|
First, the wrapping key is extracted as normally during
|
|
.Xr zfs-fido2-load-key 8 ,
|
|
then a credential is made as-if during
|
|
.Xr zfs-fido2-change-key 8
|
|
(except the "primary" device and all the ones holding backups are excluded from the search);
|
|
however, the
|
|
.Ql hmac-secret
|
|
is instead used as a symmetric AES-256-GCM
|
|
.Pq Xr EVP_CIPHER-AES 7ssl
|
|
key to encrypt the wrapping key directly with a random IV.
|
|
.Pp
|
|
This turns the
|
|
.Li xyz.nabijaczleweli:tzpfms.key
|
|
variable into
|
|
.br
|
|
.Ar salt Ns Cm :\:\& Ns Ar credential-ID Ns Cm :\:\& Ns Ar credential-public-key Ns Oo Cm \&. Ns Ar backup-salt Ns Cm :\:\& Ns Ar backup-credential-ID Ns Cm :\:\& Ns Ar backup-credential-public-key Ns Cm :\:\& Ns Ar IV Ns Cm :\:\& Ns Ar encrypted-key Oc Ns …
|
|
.Pp
|
|
.Li tzpfms.key
|
|
is actually a dot-separated list of device bundles.
|
|
The first one is as-described in
|
|
.Xr zfs-fido2-change-key 8 .
|
|
Subsequent ones also include (identically-encoded) IVs and encrypted blobs.
|
|
.Pp
|
|
.Xr zfs-fido2-load-key 8
|
|
shops assertions around devices in a device-major order \(em
|
|
depending on device numbering, a backup may be loaded even if the primary device is present.
|
|
.
|
|
.\" 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 .
|