mirror of
https://git.sr.ht/~nabijaczleweli/tzpfms
synced 2025-04-27 10:02:12 +03:00
Manpage update by job 1160990
This commit is contained in:
наб autouploader
parent
a567a146c4
commit
fc6c86b6a7
BIN
tzpfms.pdf
BIN
tzpfms.pdf
Binary file not shown.
125
zfs-fido2-add-backup.8
Normal file
125
zfs-fido2-add-backup.8
Normal file
@ -0,0 +1,125 @@
|
|||||||
|
.\" 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 .
|
||||||
153
zfs-fido2-add-backup.8.html
Normal file
153
zfs-fido2-add-backup.8.html
Normal file
@ -0,0 +1,153 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<!-- This is an automatically generated file. Do not edit.
|
||||||
|
SPDX-License-Identifier: MIT
|
||||||
|
-->
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8"/>
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
|
||||||
|
<title>ZFS-FIDO2-ADD-BACKUP(8)</title>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<table class="head">
|
||||||
|
<tr>
|
||||||
|
<td class="head-ltitle">ZFS-FIDO2-ADD-BACKUP(8)</td>
|
||||||
|
<td class="head-vol">System Manager's Manual</td>
|
||||||
|
<td class="head-rtitle">ZFS-FIDO2-ADD-BACKUP(8)</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<div class="manual-text">
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
||||||
|
<p class="Pp"><code class="Nm">zfs-fido2-add-backup</code> —
|
||||||
|
<span class="Nd">allow another FIDO2 device to unlock ZFS dataset</span></p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
||||||
|
<table class="Nm">
|
||||||
|
<tr>
|
||||||
|
<td><code class="Nm">zfs-fido2-add-backup</code></td>
|
||||||
|
<td><var class="Ar">dataset</var></td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||||
|
<p class="Pp">After
|
||||||
|
<a class="Xr" href="zfs-fido2-change-key.8.html">zfs-fido2-change-key(8)</a>
|
||||||
|
derives the key for a dataset from a FIDO2 device,
|
||||||
|
<code class="Nm">zfs-fido2-add-backup</code> may be executed to extend this
|
||||||
|
to any number of additional devices.</p>
|
||||||
|
<p class="Pp">First, the wrapping key is extracted as normally during
|
||||||
|
<a class="Xr" href="zfs-fido2-load-key.8.html">zfs-fido2-load-key(8)</a>,
|
||||||
|
then a credential is made as-if during
|
||||||
|
<a class="Xr" href="zfs-fido2-change-key.8.html">zfs-fido2-change-key(8)</a>
|
||||||
|
(except the "primary" device and all the ones holding backups are
|
||||||
|
excluded from the search); however, the
|
||||||
|
‘<code class="Li">hmac-secret</code>’ is instead used as a
|
||||||
|
symmetric AES-256-GCM
|
||||||
|
(<a class="Xr" href="https://manpages.debian.org/bookworm/EVP_CIPHER-AES.7ssl">EVP_CIPHER-AES(7ssl)</a>)
|
||||||
|
key to encrypt the wrapping key directly with a random IV.</p>
|
||||||
|
<p class="Pp">This turns the
|
||||||
|
<code class="Li">xyz.nabijaczleweli:tzpfms.key</code> variable into
|
||||||
|
<br/>
|
||||||
|
<var class="Ar">salt</var><code class="Cm">:</code><var class="Ar">credential-ID</var><code class="Cm">:</code><var class="Ar">credential-public-key</var>[<code class="Cm">.</code><var class="Ar">backup-salt</var><code class="Cm">:</code><var class="Ar">backup-credential-ID</var><code class="Cm">:</code><var class="Ar">backup-credential-public-key</var><code class="Cm">:</code><var class="Ar">IV</var><code class="Cm">:</code><var class="Ar">encrypted-key</var>]…</p>
|
||||||
|
<p class="Pp"><code class="Li">tzpfms.key</code> is actually a dot-separated
|
||||||
|
list of device bundles. The first one is as-described in
|
||||||
|
<a class="Xr" href="zfs-fido2-change-key.8.html">zfs-fido2-change-key(8)</a>.
|
||||||
|
Subsequent ones also include (identically-encoded) IVs and encrypted
|
||||||
|
blobs.</p>
|
||||||
|
<p class="Pp"><a class="Xr" href="zfs-fido2-load-key.8.html">zfs-fido2-load-key(8)</a>
|
||||||
|
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.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="ENVIRONMENT_VARIABLES"><a class="permalink" href="#ENVIRONMENT_VARIABLES">ENVIRONMENT
|
||||||
|
VARIABLES</a></h1>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="TZPFMS_PASSPHRASE_HELPER"><a class="permalink" href="#TZPFMS_PASSPHRASE_HELPER"><code class="Ev">TZPFMS_PASSPHRASE_HELPER</code></a></dt>
|
||||||
|
<dd>By default, passphrases are prompted for and read in on the standard
|
||||||
|
output and input streams. If
|
||||||
|
<code class="Ev">TZPFMS_PASSPHRASE_HELPER</code> is set and nonempty, it
|
||||||
|
will be run via <span class="Pa">/bin/</span><code class="Nm">sh</code>
|
||||||
|
<code class="Fl">-c</code> to provide each passphrase, instead.
|
||||||
|
<p class="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:</p>
|
||||||
|
<div class="Bd-indent">
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="$1"><a class="permalink" href="#$1"><code class="Li">$1</code></a></dt>
|
||||||
|
<dd>Pre-formatted noun phrase with all the information below, for use as a
|
||||||
|
prompt</dd>
|
||||||
|
<dt id="$2"><a class="permalink" href="#$2"><code class="Li">$2</code></a></dt>
|
||||||
|
<dd>Either the dataset name or the element of the TPM hierarchy being
|
||||||
|
prompted for</dd>
|
||||||
|
<dt id="$3"><a class="permalink" href="#$3"><code class="Li">$3</code></a></dt>
|
||||||
|
<dd>"new" if this is for a new passphrase, otherwise blank</dd>
|
||||||
|
<dt id="$4"><a class="permalink" href="#$4"><code class="Li">$4</code></a></dt>
|
||||||
|
<dd>"again" if it's the second prompt for that passphrase,
|
||||||
|
otherwise blank</dd>
|
||||||
|
</dl>
|
||||||
|
</div>
|
||||||
|
<p class="Pp" id="127">If the helper doesn't exist (the shell exits with
|
||||||
|
<a class="permalink" href="#127"><b class="Sy">127</b></a>), a
|
||||||
|
diagnostic is issued and the normal prompt is used as fall-back. If it
|
||||||
|
fails for any other reason, the prompting is aborted.</p>
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="FIDO2_back-end_configuration"><a class="permalink" href="#FIDO2_back-end_configuration">FIDO2
|
||||||
|
back-end configuration</a></h1>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="Environment_variables"><a class="permalink" href="#Environment_variables">Environment
|
||||||
|
variables</a></h2>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="FIDO_DEBUG"><a class="permalink" href="#FIDO_DEBUG"><code class="Ev">FIDO_DEBUG</code></a></dt>
|
||||||
|
<dd>If set, enables libfido2 debug logging to the standard error stream.</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="Device_selection"><a class="permalink" href="#Device_selection">Device
|
||||||
|
selection</a></h2>
|
||||||
|
<p class="Pp">When creating, the first device which supports the
|
||||||
|
‘<code class="Li">hmac-secret</code>’ extension is used. When
|
||||||
|
loading, the assertion is shopped around to every such device.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="See_also"><a class="permalink" href="#See_also">See
|
||||||
|
also</a></h2>
|
||||||
|
<p class="Pp">The libfido2 documentation at
|
||||||
|
<a class="Lk" href="https://developers.yubico.com/libfido2/">https://developers.yubico.com/libfido2/</a>.</p>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SPECIAL_THANKS"><a class="permalink" href="#SPECIAL_THANKS">SPECIAL
|
||||||
|
THANKS</a></h1>
|
||||||
|
<p class="Pp">To all who support further development, in particular:</p>
|
||||||
|
<ul class="Bl-bullet Bd-indent Bl-compact">
|
||||||
|
<li>ThePhD</li>
|
||||||
|
<li>Embark Studios</li>
|
||||||
|
<li>Jasper Bekkers</li>
|
||||||
|
<li>EvModder</li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="REPORTING_BUGS"><a class="permalink" href="#REPORTING_BUGS">REPORTING
|
||||||
|
BUGS</a></h1>
|
||||||
|
<p class="Pp"><a class="Lk" href="https://todo.sr.ht/~nabijaczleweli/fzifdso">https://todo.sr.ht/~nabijaczleweli/fzifdso</a></p>
|
||||||
|
<p class="Pp"><a class="Mt" href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht">~nabijaczleweli/tzpfms@lists.sr.ht</a>,
|
||||||
|
archived at
|
||||||
|
<a class="Lk" href="https://lists.sr.ht/~nabijaczleweli/tzpfms">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>.</p>
|
||||||
|
</section>
|
||||||
|
</div>
|
||||||
|
<table class="foot">
|
||||||
|
<tr>
|
||||||
|
<td class="foot-date">February 29, 2024</td>
|
||||||
|
<td class="foot-os">fzifdso 0</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
186
zfs-fido2-change-key.8
Normal file
186
zfs-fido2-change-key.8
Normal file
@ -0,0 +1,186 @@
|
|||||||
|
.\" 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 .
|
||||||
206
zfs-fido2-change-key.8.html
Normal file
206
zfs-fido2-change-key.8.html
Normal file
@ -0,0 +1,206 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<!-- This is an automatically generated file. Do not edit.
|
||||||
|
SPDX-License-Identifier: MIT
|
||||||
|
-->
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8"/>
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
|
||||||
|
<title>ZFS-FIDO2-CHANGE-KEY(8)</title>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<table class="head">
|
||||||
|
<tr>
|
||||||
|
<td class="head-ltitle">ZFS-FIDO2-CHANGE-KEY(8)</td>
|
||||||
|
<td class="head-vol">System Manager's Manual</td>
|
||||||
|
<td class="head-rtitle">ZFS-FIDO2-CHANGE-KEY(8)</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<div class="manual-text">
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
||||||
|
<p class="Pp"><code class="Nm">zfs-fido2-change-key</code> —
|
||||||
|
<span class="Nd">change ZFS dataset key to one authenticated by a FIDO2
|
||||||
|
device</span></p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
||||||
|
<table class="Nm">
|
||||||
|
<tr>
|
||||||
|
<td><code class="Nm">zfs-fido2-change-key</code></td>
|
||||||
|
<td>[<code class="Fl">-b</code> <var class="Ar">backup-file</var>]
|
||||||
|
<var class="Ar">dataset</var></td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||||
|
<p class="Pp">To normalise the <var class="Ar">dataset</var>,
|
||||||
|
<code class="Nm">zfs-fido2-change-key</code> will open its encryption root
|
||||||
|
in its stead. <code class="Nm">zfs-fido2-change-key</code> will
|
||||||
|
<a class="permalink" href="#never"><i class="Em" id="never">never</i></a>
|
||||||
|
create or destroy encryption roots; use
|
||||||
|
<a class="Xr" href="https://manpages.debian.org/bookworm/zfs-change-key.8">zfs-change-key(8)</a>
|
||||||
|
for that.</p>
|
||||||
|
<p class="Pp">First, a connection is made to the FIDO2 device, which
|
||||||
|
<i class="Em">must</i> support the
|
||||||
|
‘<code class="Li">hmac-secret</code>’ extension.</p>
|
||||||
|
<p class="Pp">If <var class="Ar">dataset</var> was previously encrypted with
|
||||||
|
<code class="Nm">fzifdso</code> and the <b class="Sy">FIDO2</b> 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.</p>
|
||||||
|
<p class="Pp">Next, a new credential of type ES256 is generated on the device
|
||||||
|
(with relying party ID <code class="Li">fzifdso</code> and name equal to the
|
||||||
|
dataset name) with the ‘<code class="Li">hmac-secret</code>’
|
||||||
|
extension requested; the device PIN, if any, is prompted for here. This
|
||||||
|
mimicks a WebAuthn registration step.</p>
|
||||||
|
<p class="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
|
||||||
|
(which is optionally backed up (see
|
||||||
|
<a class="Sx" href="#OPTIONS">OPTIONS</a>)). This mimicks a WebAuthn login
|
||||||
|
step.</p>
|
||||||
|
<p class="Pp">The following properties are set on
|
||||||
|
<var class="Ar">dataset</var>:</p>
|
||||||
|
<ul class="Bl-bullet Bd-indent Bl-compact">
|
||||||
|
<li id="xyz.nabijaczleweli:tzpfms.backend"><a class="permalink" href="#xyz.nabijaczleweli:tzpfms.backend"><code class="Li">xyz.nabijaczleweli:tzpfms.backend</code></a>=<b class="Sy">FIDO2</b></li>
|
||||||
|
<li id="xyz.nabijaczleweli:tzpfms.key"><a class="permalink" href="#xyz.nabijaczleweli:tzpfms.key"><code class="Li">xyz.nabijaczleweli:tzpfms.key</code></a>=<var class="Ar">salt</var><code class="Cm">:</code><var class="Ar">credential-ID</var><code class="Cm">:</code><var class="Ar">credential-public-key</var>[<code class="Cm">.</code>…]…</li>
|
||||||
|
</ul>
|
||||||
|
<p class="Pp"><code class="Li">tzpfms.backend</code> identifies this dataset for
|
||||||
|
work with <b class="Sy">FIDO2</b>-back-ended <code class="Nm">tzpfms</code>
|
||||||
|
tools (i.e. <code class="Nm">fzifdso</code>
|
||||||
|
<a class="Xr" href="zfs-fido2-change-key.8.html">zfs-fido2-change-key(8)</a>,
|
||||||
|
<a class="Xr" href="zfs-fido2-load-key.8.html">zfs-fido2-load-key(8)</a>,
|
||||||
|
<a class="Xr" href="zfs-fido2-add-backup.8.html">zfs-fido2-add-backup(8)</a>,
|
||||||
|
and
|
||||||
|
<a class="Xr" href="zfs-fido2-clear-key.8.html">zfs-fido2-clear-key(8)</a>).</p>
|
||||||
|
<p class="Pp"><code class="Li">tzpfms.key</code> 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 – its public
|
||||||
|
key. There exists no other user-land tool for deciphering this; perhaps
|
||||||
|
there should be.</p>
|
||||||
|
<p class="Pp">Finally, the equivalent of <code class="Nm">zfs</code>
|
||||||
|
<code class="Cm">change-key</code> <code class="Fl">-o</code>
|
||||||
|
<code class="Li">keylocation=prompt</code> <code class="Fl">-o</code>
|
||||||
|
<code class="Li">keyformat=raw</code> <var class="Ar">dataset</var> 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.</p>
|
||||||
|
<p class="Pp">A final verification should be made by running
|
||||||
|
<code class="Nm">zfs-fido2-load-key</code> <code class="Fl">-n</code>
|
||||||
|
<var class="Ar">dataset</var>. If that command succeeds, all is well, but
|
||||||
|
otherwise the dataset can be manually rolled back to a passphrase with
|
||||||
|
<code class="Nm">zfs-fido2-clear-key</code> <var class="Ar">dataset</var>
|
||||||
|
(or, if that fails to work, <code class="Nm">zfs</code>
|
||||||
|
<code class="Cm">change-key</code> <code class="Fl">-o</code>
|
||||||
|
<code class="Li">keyformat=passphrase</code> <var class="Ar">dataset</var>),
|
||||||
|
and you are hereby asked to report a bug, please.</p>
|
||||||
|
<p class="Pp"><code class="Nm">zfs-fido2-clear-key</code>
|
||||||
|
<var class="Ar">dataset</var> can be used to clear the properties and go
|
||||||
|
back to using a passphrase.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="b"><a class="permalink" href="#b"><code class="Fl">-b</code></a>
|
||||||
|
<var class="Ar">backup-file</var></dt>
|
||||||
|
<dd>Save a back-up of the key to <var class="Ar">backup-file</var>, which must
|
||||||
|
not exist beforehand. This back-up <i class="Em">must</i> be stored
|
||||||
|
securely, off-site. In case of a catastrophic event, the key can be loaded
|
||||||
|
by running
|
||||||
|
<div class="Bd Bd-indent"><code class="Li"><code class="Nm">zfs</code>
|
||||||
|
<code class="Cm">load-key</code> <var class="Ar">dataset</var>
|
||||||
|
<code class="Li"><</code>
|
||||||
|
<var class="Ar">backup-file</var></code></div>
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="ENVIRONMENT_VARIABLES"><a class="permalink" href="#ENVIRONMENT_VARIABLES">ENVIRONMENT
|
||||||
|
VARIABLES</a></h1>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="TZPFMS_PASSPHRASE_HELPER"><a class="permalink" href="#TZPFMS_PASSPHRASE_HELPER"><code class="Ev">TZPFMS_PASSPHRASE_HELPER</code></a></dt>
|
||||||
|
<dd>By default, passphrases are prompted for and read in on the standard
|
||||||
|
output and input streams. If
|
||||||
|
<code class="Ev">TZPFMS_PASSPHRASE_HELPER</code> is set and nonempty, it
|
||||||
|
will be run via <span class="Pa">/bin/</span><code class="Nm">sh</code>
|
||||||
|
<code class="Fl">-c</code> to provide each passphrase, instead.
|
||||||
|
<p class="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:</p>
|
||||||
|
<div class="Bd-indent">
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="$1"><a class="permalink" href="#$1"><code class="Li">$1</code></a></dt>
|
||||||
|
<dd>Pre-formatted noun phrase with all the information below, for use as a
|
||||||
|
prompt</dd>
|
||||||
|
<dt id="$2"><a class="permalink" href="#$2"><code class="Li">$2</code></a></dt>
|
||||||
|
<dd>Either the dataset name or the element of the TPM hierarchy being
|
||||||
|
prompted for</dd>
|
||||||
|
<dt id="$3"><a class="permalink" href="#$3"><code class="Li">$3</code></a></dt>
|
||||||
|
<dd>"new" if this is for a new passphrase, otherwise blank</dd>
|
||||||
|
<dt id="$4"><a class="permalink" href="#$4"><code class="Li">$4</code></a></dt>
|
||||||
|
<dd>"again" if it's the second prompt for that passphrase,
|
||||||
|
otherwise blank</dd>
|
||||||
|
</dl>
|
||||||
|
</div>
|
||||||
|
<p class="Pp" id="127">If the helper doesn't exist (the shell exits with
|
||||||
|
<a class="permalink" href="#127"><b class="Sy">127</b></a>), a
|
||||||
|
diagnostic is issued and the normal prompt is used as fall-back. If it
|
||||||
|
fails for any other reason, the prompting is aborted.</p>
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="FIDO2_back-end_configuration"><a class="permalink" href="#FIDO2_back-end_configuration">FIDO2
|
||||||
|
back-end configuration</a></h1>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="Environment_variables"><a class="permalink" href="#Environment_variables">Environment
|
||||||
|
variables</a></h2>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="FIDO_DEBUG"><a class="permalink" href="#FIDO_DEBUG"><code class="Ev">FIDO_DEBUG</code></a></dt>
|
||||||
|
<dd>If set, enables libfido2 debug logging to the standard error stream.</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="Device_selection"><a class="permalink" href="#Device_selection">Device
|
||||||
|
selection</a></h2>
|
||||||
|
<p class="Pp">When creating, the first device which supports the
|
||||||
|
‘<code class="Li">hmac-secret</code>’ extension is used. When
|
||||||
|
loading, the assertion is shopped around to every such device.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="See_also"><a class="permalink" href="#See_also">See
|
||||||
|
also</a></h2>
|
||||||
|
<p class="Pp">The libfido2 documentation at
|
||||||
|
<a class="Lk" href="https://developers.yubico.com/libfido2/">https://developers.yubico.com/libfido2/</a>.</p>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SPECIAL_THANKS"><a class="permalink" href="#SPECIAL_THANKS">SPECIAL
|
||||||
|
THANKS</a></h1>
|
||||||
|
<p class="Pp">To all who support further development, in particular:</p>
|
||||||
|
<ul class="Bl-bullet Bd-indent Bl-compact">
|
||||||
|
<li>ThePhD</li>
|
||||||
|
<li>Embark Studios</li>
|
||||||
|
<li>Jasper Bekkers</li>
|
||||||
|
<li>EvModder</li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="REPORTING_BUGS"><a class="permalink" href="#REPORTING_BUGS">REPORTING
|
||||||
|
BUGS</a></h1>
|
||||||
|
<p class="Pp"><a class="Lk" href="https://todo.sr.ht/~nabijaczleweli/fzifdso">https://todo.sr.ht/~nabijaczleweli/fzifdso</a></p>
|
||||||
|
<p class="Pp"><a class="Mt" href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht">~nabijaczleweli/tzpfms@lists.sr.ht</a>,
|
||||||
|
archived at
|
||||||
|
<a class="Lk" href="https://lists.sr.ht/~nabijaczleweli/tzpfms">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>.</p>
|
||||||
|
</section>
|
||||||
|
</div>
|
||||||
|
<table class="foot">
|
||||||
|
<tr>
|
||||||
|
<td class="foot-date">February 29, 2024</td>
|
||||||
|
<td class="foot-os">fzifdso 0</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
113
zfs-fido2-clear-key.8
Normal file
113
zfs-fido2-clear-key.8
Normal file
@ -0,0 +1,113 @@
|
|||||||
|
.\" SPDX-License-Identifier: MIT
|
||||||
|
.
|
||||||
|
.Dd February 28, 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
|
||||||
|
removes the
|
||||||
|
.Li xyz.nabijaczleweli:tzpfms.\& Ns Brq Li backend , key
|
||||||
|
properties from
|
||||||
|
.Ar dataset .
|
||||||
|
.El
|
||||||
|
.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 .
|
||||||
143
zfs-fido2-clear-key.8.html
Normal file
143
zfs-fido2-clear-key.8.html
Normal file
@ -0,0 +1,143 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<!-- This is an automatically generated file. Do not edit.
|
||||||
|
SPDX-License-Identifier: MIT
|
||||||
|
-->
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8"/>
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
|
||||||
|
<title>ZFS-FIDO2-CLEAR-KEY(8)</title>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<table class="head">
|
||||||
|
<tr>
|
||||||
|
<td class="head-ltitle">ZFS-FIDO2-CLEAR-KEY(8)</td>
|
||||||
|
<td class="head-vol">System Manager's Manual</td>
|
||||||
|
<td class="head-rtitle">ZFS-FIDO2-CLEAR-KEY(8)</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<div class="manual-text">
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
||||||
|
<p class="Pp"><code class="Nm">zfs-fido2-clear-key</code> —
|
||||||
|
<span class="Nd">rewrap ZFS dataset key in passsword and clear tzpfms FIDO2
|
||||||
|
metadata</span></p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
||||||
|
<table class="Nm">
|
||||||
|
<tr>
|
||||||
|
<td><code class="Nm">zfs-fido2-clear-key</code></td>
|
||||||
|
<td><var class="Ar">dataset</var></td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||||
|
<p class="Pp">After verifying <var class="Ar">dataset</var> was encrypted with
|
||||||
|
<code class="Nm">tzpfms</code> backend
|
||||||
|
<a class="permalink" href="#FIDO2"><b class="Sy" id="FIDO2">FIDO2</b></a>:</p>
|
||||||
|
<ol class="Bl-enum Bd-indent Bl-compact">
|
||||||
|
<li>performs the equivalent of <code class="Nm">zfs</code>
|
||||||
|
<code class="Cm">change-key</code> <code class="Fl">-o</code>
|
||||||
|
<code class="Li">keylocation=prompt</code> <code class="Fl">-o</code>
|
||||||
|
<code class="Li">keyformat=passphrase</code>
|
||||||
|
<var class="Ar">dataset</var>,</li>
|
||||||
|
<li>removes the
|
||||||
|
<code class="Li">xyz.nabijaczleweli:tzpfms.</code>{<code class="Li">backend</code>,
|
||||||
|
<code class="Li">key</code>} properties from
|
||||||
|
<var class="Ar">dataset</var>.</li>
|
||||||
|
</ol>
|
||||||
|
<p class="Pp">See
|
||||||
|
<a class="Xr" href="zfs-fido2-change-key.8.html">zfs-fido2-change-key(8)</a>
|
||||||
|
for a detailed description.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="ENVIRONMENT_VARIABLES"><a class="permalink" href="#ENVIRONMENT_VARIABLES">ENVIRONMENT
|
||||||
|
VARIABLES</a></h1>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="TZPFMS_PASSPHRASE_HELPER"><a class="permalink" href="#TZPFMS_PASSPHRASE_HELPER"><code class="Ev">TZPFMS_PASSPHRASE_HELPER</code></a></dt>
|
||||||
|
<dd>By default, passphrases are prompted for and read in on the standard
|
||||||
|
output and input streams. If
|
||||||
|
<code class="Ev">TZPFMS_PASSPHRASE_HELPER</code> is set and nonempty, it
|
||||||
|
will be run via <span class="Pa">/bin/</span><code class="Nm">sh</code>
|
||||||
|
<code class="Fl">-c</code> to provide each passphrase, instead.
|
||||||
|
<p class="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:</p>
|
||||||
|
<div class="Bd-indent">
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="$1"><a class="permalink" href="#$1"><code class="Li">$1</code></a></dt>
|
||||||
|
<dd>Pre-formatted noun phrase with all the information below, for use as a
|
||||||
|
prompt</dd>
|
||||||
|
<dt id="$2"><a class="permalink" href="#$2"><code class="Li">$2</code></a></dt>
|
||||||
|
<dd>Either the dataset name or the element of the TPM hierarchy being
|
||||||
|
prompted for</dd>
|
||||||
|
<dt id="$3"><a class="permalink" href="#$3"><code class="Li">$3</code></a></dt>
|
||||||
|
<dd>"new" if this is for a new passphrase, otherwise blank</dd>
|
||||||
|
<dt id="$4"><a class="permalink" href="#$4"><code class="Li">$4</code></a></dt>
|
||||||
|
<dd>"again" if it's the second prompt for that passphrase,
|
||||||
|
otherwise blank</dd>
|
||||||
|
</dl>
|
||||||
|
</div>
|
||||||
|
<p class="Pp" id="127">If the helper doesn't exist (the shell exits with
|
||||||
|
<a class="permalink" href="#127"><b class="Sy">127</b></a>), a
|
||||||
|
diagnostic is issued and the normal prompt is used as fall-back. If it
|
||||||
|
fails for any other reason, the prompting is aborted.</p>
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="FIDO2_back-end_configuration"><a class="permalink" href="#FIDO2_back-end_configuration">FIDO2
|
||||||
|
back-end configuration</a></h1>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="Environment_variables"><a class="permalink" href="#Environment_variables">Environment
|
||||||
|
variables</a></h2>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="FIDO_DEBUG"><a class="permalink" href="#FIDO_DEBUG"><code class="Ev">FIDO_DEBUG</code></a></dt>
|
||||||
|
<dd>If set, enables libfido2 debug logging to the standard error stream.</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="Device_selection"><a class="permalink" href="#Device_selection">Device
|
||||||
|
selection</a></h2>
|
||||||
|
<p class="Pp">When creating, the first device which supports the
|
||||||
|
‘<code class="Li">hmac-secret</code>’ extension is used. When
|
||||||
|
loading, the assertion is shopped around to every such device.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Ss">
|
||||||
|
<h2 class="Ss" id="See_also"><a class="permalink" href="#See_also">See
|
||||||
|
also</a></h2>
|
||||||
|
<p class="Pp">The libfido2 documentation at
|
||||||
|
<a class="Lk" href="https://developers.yubico.com/libfido2/">https://developers.yubico.com/libfido2/</a>.</p>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SPECIAL_THANKS"><a class="permalink" href="#SPECIAL_THANKS">SPECIAL
|
||||||
|
THANKS</a></h1>
|
||||||
|
<p class="Pp">To all who support further development, in particular:</p>
|
||||||
|
<ul class="Bl-bullet Bd-indent Bl-compact">
|
||||||
|
<li>ThePhD</li>
|
||||||
|
<li>Embark Studios</li>
|
||||||
|
<li>Jasper Bekkers</li>
|
||||||
|
<li>EvModder</li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="REPORTING_BUGS"><a class="permalink" href="#REPORTING_BUGS">REPORTING
|
||||||
|
BUGS</a></h1>
|
||||||
|
<p class="Pp"><a class="Lk" href="https://todo.sr.ht/~nabijaczleweli/fzifdso">https://todo.sr.ht/~nabijaczleweli/fzifdso</a></p>
|
||||||
|
<p class="Pp"><a class="Mt" href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht">~nabijaczleweli/tzpfms@lists.sr.ht</a>,
|
||||||
|
archived at
|
||||||
|
<a class="Lk" href="https://lists.sr.ht/~nabijaczleweli/tzpfms">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>.</p>
|
||||||
|
</section>
|
||||||
|
</div>
|
||||||
|
<table class="foot">
|
||||||
|
<tr>
|
||||||
|
<td class="foot-date">February 28, 2024</td>
|
||||||
|
<td class="foot-os">fzifdso 0</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
98
zfs-fido2-load-key.8
Normal file
98
zfs-fido2-load-key.8
Normal file
@ -0,0 +1,98 @@
|
|||||||
|
.\" SPDX-License-Identifier: MIT
|
||||||
|
.
|
||||||
|
.Dd February 28, 2024
|
||||||
|
.ds doc-volume-operating-system
|
||||||
|
.Dt ZFS-FIDO2-LOAD-KEY 8
|
||||||
|
.Os fzifdso 0
|
||||||
|
.
|
||||||
|
.Sh NAME
|
||||||
|
.Nm zfs-fido2-load-key
|
||||||
|
.Nd load FIDO2-encrypted ZFS dataset key
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.Nm
|
||||||
|
.Op Fl n
|
||||||
|
.Ar dataset
|
||||||
|
.
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
After verifying
|
||||||
|
.Ar dataset
|
||||||
|
was encrypted with
|
||||||
|
.Nm tzpfms
|
||||||
|
backend
|
||||||
|
.Sy FIDO2 ,
|
||||||
|
asserts the preserved challenge, HMACking the salt with the on-device secret, and loads the resulting key into
|
||||||
|
.Ar dataset .
|
||||||
|
.Pp
|
||||||
|
See
|
||||||
|
.Xr zfs-fido2-change-key 8
|
||||||
|
for a detailed description.
|
||||||
|
.
|
||||||
|
.Sh OPTIONS
|
||||||
|
.Bl -tag -compact -width ".Fl n"
|
||||||
|
.It Fl n
|
||||||
|
Do a no-op/dry run, can be used even if the key is already loaded.
|
||||||
|
Equivalent to
|
||||||
|
.Nm zfs Cm load-key Ns 's
|
||||||
|
.Fl n
|
||||||
|
option.
|
||||||
|
.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 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 .
|
||||||
117
zfs-fido2-load-key.8.html
Normal file
117
zfs-fido2-load-key.8.html
Normal file
@ -0,0 +1,117 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<!-- This is an automatically generated file. Do not edit.
|
||||||
|
SPDX-License-Identifier: MIT
|
||||||
|
-->
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8"/>
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
|
||||||
|
<title>ZFS-FIDO2-LOAD-KEY(8)</title>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<table class="head">
|
||||||
|
<tr>
|
||||||
|
<td class="head-ltitle">ZFS-FIDO2-LOAD-KEY(8)</td>
|
||||||
|
<td class="head-vol">System Manager's Manual</td>
|
||||||
|
<td class="head-rtitle">ZFS-FIDO2-LOAD-KEY(8)</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<div class="manual-text">
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
||||||
|
<p class="Pp"><code class="Nm">zfs-fido2-load-key</code> —
|
||||||
|
<span class="Nd">load FIDO2-encrypted ZFS dataset key</span></p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
||||||
|
<table class="Nm">
|
||||||
|
<tr>
|
||||||
|
<td><code class="Nm">zfs-fido2-load-key</code></td>
|
||||||
|
<td>[<code class="Fl">-n</code>] <var class="Ar">dataset</var></td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||||
|
<p class="Pp">After verifying <var class="Ar">dataset</var> was encrypted with
|
||||||
|
<code class="Nm">tzpfms</code> backend
|
||||||
|
<a class="permalink" href="#FIDO2"><b class="Sy" id="FIDO2">FIDO2</b></a>,
|
||||||
|
asserts the preserved challenge, HMACking the salt with the on-device
|
||||||
|
secret, and loads the resulting key into <var class="Ar">dataset</var>.</p>
|
||||||
|
<p class="Pp">See
|
||||||
|
<a class="Xr" href="zfs-fido2-change-key.8.html">zfs-fido2-change-key(8)</a>
|
||||||
|
for a detailed description.</p>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
|
||||||
|
<dd>Do a no-op/dry run, can be used even if the key is already loaded.
|
||||||
|
Equivalent to <code class="Nm">zfs</code>
|
||||||
|
<code class="Cm">load-key</code>'s <code class="Fl">-n</code> option.</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="ENVIRONMENT_VARIABLES"><a class="permalink" href="#ENVIRONMENT_VARIABLES">ENVIRONMENT
|
||||||
|
VARIABLES</a></h1>
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="TZPFMS_PASSPHRASE_HELPER"><a class="permalink" href="#TZPFMS_PASSPHRASE_HELPER"><code class="Ev">TZPFMS_PASSPHRASE_HELPER</code></a></dt>
|
||||||
|
<dd>By default, passphrases are prompted for and read in on the standard
|
||||||
|
output and input streams. If
|
||||||
|
<code class="Ev">TZPFMS_PASSPHRASE_HELPER</code> is set and nonempty, it
|
||||||
|
will be run via <span class="Pa">/bin/</span><code class="Nm">sh</code>
|
||||||
|
<code class="Fl">-c</code> to provide each passphrase, instead.
|
||||||
|
<p class="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:</p>
|
||||||
|
<div class="Bd-indent">
|
||||||
|
<dl class="Bl-tag Bl-compact">
|
||||||
|
<dt id="$1"><a class="permalink" href="#$1"><code class="Li">$1</code></a></dt>
|
||||||
|
<dd>Pre-formatted noun phrase with all the information below, for use as a
|
||||||
|
prompt</dd>
|
||||||
|
<dt id="$2"><a class="permalink" href="#$2"><code class="Li">$2</code></a></dt>
|
||||||
|
<dd>Either the dataset name or the element of the TPM hierarchy being
|
||||||
|
prompted for</dd>
|
||||||
|
<dt id="$3"><a class="permalink" href="#$3"><code class="Li">$3</code></a></dt>
|
||||||
|
<dd>"new" if this is for a new passphrase, otherwise blank</dd>
|
||||||
|
<dt id="$4"><a class="permalink" href="#$4"><code class="Li">$4</code></a></dt>
|
||||||
|
<dd>"again" if it's the second prompt for that passphrase,
|
||||||
|
otherwise blank</dd>
|
||||||
|
</dl>
|
||||||
|
</div>
|
||||||
|
<p class="Pp" id="127">If the helper doesn't exist (the shell exits with
|
||||||
|
<a class="permalink" href="#127"><b class="Sy">127</b></a>), a
|
||||||
|
diagnostic is issued and the normal prompt is used as fall-back. If it
|
||||||
|
fails for any other reason, the prompting is aborted.</p>
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="SPECIAL_THANKS"><a class="permalink" href="#SPECIAL_THANKS">SPECIAL
|
||||||
|
THANKS</a></h1>
|
||||||
|
<p class="Pp">To all who support further development, in particular:</p>
|
||||||
|
<ul class="Bl-bullet Bd-indent Bl-compact">
|
||||||
|
<li>ThePhD</li>
|
||||||
|
<li>Embark Studios</li>
|
||||||
|
<li>Jasper Bekkers</li>
|
||||||
|
<li>EvModder</li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
<section class="Sh">
|
||||||
|
<h1 class="Sh" id="REPORTING_BUGS"><a class="permalink" href="#REPORTING_BUGS">REPORTING
|
||||||
|
BUGS</a></h1>
|
||||||
|
<p class="Pp"><a class="Lk" href="https://todo.sr.ht/~nabijaczleweli/fzifdso">https://todo.sr.ht/~nabijaczleweli/fzifdso</a></p>
|
||||||
|
<p class="Pp"><a class="Mt" href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht">~nabijaczleweli/tzpfms@lists.sr.ht</a>,
|
||||||
|
archived at
|
||||||
|
<a class="Lk" href="https://lists.sr.ht/~nabijaczleweli/tzpfms">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>.</p>
|
||||||
|
</section>
|
||||||
|
</div>
|
||||||
|
<table class="foot">
|
||||||
|
<tr>
|
||||||
|
<td class="foot-date">February 28, 2024</td>
|
||||||
|
<td class="foot-os">fzifdso 0</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
Loading…
x
Reference in New Issue
Block a user