third-party-mirrors/tzpfms
1
0
Fork 0
mirror of https://git.sr.ht/~nabijaczleweli/tzpfms synced 2025-05-05 10:31:02 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity
tzpfms/zfs-tpm2-change-key.8.html
наб autouploader fc4094f424 Manpage update by job 608529
2021-10-15 21:34:57 +00:00

184 lines
9.4 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<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-TPM2-CHANGE-KEY(8)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM2-CHANGE-KEY(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM2-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-tpm2-change-key</code> &#x2014;
<span class="Nd">change ZFS dataset key to one stored on the TPM</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-tpm2-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 <var class="Ar">dataset</var>,
<code class="Nm">zfs-tpm2-change-key</code> will open its encryption root in
its stead. <code class="Nm">zfs-tpm2-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/bullseye/zfs-change-key.8">zfs-change-key(8)</a>
for that.</p>
<p class="Pp">First, a connection is made to the TPM, which
<i class="Em">must</i> be TPM-2.0-compatible.</p>
<p class="Pp">If <var class="Ar">dataset</var> was previously encrypted with
<code class="Nm">tzpfms</code> and the <b class="Sy">TPM2</b> back-end was
used, the previous key will be freed from the TPM. Otherwise, or in case of
an error, data required for manual intervention will be printed to the
standard error stream.</p>
<p class="Pp">Next, a new wrapping key is be generated on the TPM, optionally
backed up (see <a class="Sx" href="#OPTIONS">OPTIONS</a>), and sealed to a
persistent object on the TPM under the owner hierarchy; if there is a
passphrase set on the owner hierarchy, the user is prompted for it; the user
is always prompted for an optional passphrase to protect the sealed object
with.</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">TPM2</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">ID
of persistent object</var></li>
</ul>
<p class="Pp"><code class="Li">tzpfms.backend</code> identifies this dataset for
work with <b class="Sy">TPM2</b>-back-ended <code class="Nm">tzpfms</code>
tools (namely
<a class="Xr" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key(8)</a>,
<a class="Xr" href="zfs-tpm2-load-key.8.html">zfs-tpm2-load-key(8)</a>, and
<a class="Xr" href="zfs-tpm2-clear-key.8.html">zfs-tpm2-clear-key(8)</a>).</p>
<p class="Pp"><code class="Li">tzpfms.key</code> is an integer representing the
sealed object; if needed, it can be passed to
<code class="Nm">tpm2_unseal</code> <code class="Fl">-c</code>
<code class="Ev">${tzpfms.key}</code> [<code class="Fl">-p</code>
<code class="Ev">${password}</code>] or equivalent for back-up (see
<a class="Sx" href="#OPTIONS">OPTIONS</a>). If you have a sealed key you can
access with that or equivalent tool and set both of these properties, it
will funxion seamlessly.</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 persistent object and 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-tpm2-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 password with
<code class="Nm">zfs-tpm2-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-tpm2-clear-key</code>
<var class="Ar">dataset</var> can be used to free the TPM persistent object
and go back to using a password.</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">&lt;</code>
<var class="Ar">backup-file</var></code></div>
</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="TPM2_back-end_configuration"><a class="permalink" href="#TPM2_back-end_configuration">TPM2
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="TSS2_LOG"><a class="permalink" href="#TSS2_LOG"><code class="Ev">TSS2_LOG</code></a></dt>
<dd>Any of:
<a class="permalink" href="#NONE"><b class="Sy" id="NONE">NONE</b></a>,
<a class="permalink" href="#ERROR"><b class="Sy" id="ERROR">ERROR</b></a>,
<b class="Sy">WARNING</b>,
<a class="permalink" href="#INFO"><b class="Sy" id="INFO">INFO</b></a>,
<a class="permalink" href="#DEBUG"><b class="Sy" id="DEBUG">DEBUG</b></a>,
<a class="permalink" href="#TRACE"><b class="Sy" id="TRACE">TRACE</b></a>.
Default: <b class="Sy">WARNING</b>.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="TPM_selection"><a class="permalink" href="#TPM_selection">TPM
selection</a></h2>
<p class="Pp">The library <code class="Nm">libtss2-tcti-default.so</code> can be
linked to any of the <span class="Pa">libtss2-tcti-*.so</span> libraries to
select the default, otherwise <span class="Pa">/dev/tpmrm0</span>, then
<span class="Pa">/dev/tpm0</span>, then
<span class="Pa">localhost:2321</span> will be tried, in order (see
<a class="Xr" href="https://mankier.com/3/ESYS_CONTEXT">ESYS_CONTEXT(3)</a>).</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 tpm2-tss git repository at
<a class="Lk" href="https://github.com/tpm2-software/tpm2-tss">https://github.com/tpm2-software/tpm2-tss</a>
and the documentation at
<a class="Lk" href="https://tpm2-tss.readthedocs.io">https://tpm2-tss.readthedocs.io</a>.</p>
<p class="Pp">The TPM 2.0 specifications, mainly at
<a class="Lk" href="https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf">https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf</a>
and related pages.</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>
</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/tzpfms">https://todo.sr.ht/~nabijaczleweli/tzpfms</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>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr" href="https://manpages.debian.org/bullseye/tpm2_unseal.1">tpm2_unseal(1)</a></p>
<p class="Pp"><a class="Lk" href="https://git.sr.ht/~nabijaczleweli/tzpfms">https://git.sr.ht/~nabijaczleweli/tzpfms</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 15, 2021</td>
<td class="foot-os">tzpfms 0.1-5</td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink