third-party-mirrors/tzpfms
1
0
Fork 0
mirror of https://git.sr.ht/~nabijaczleweli/tzpfms synced 2025-04-19 09:47:35 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity
tzpfms/zfs-tpm1x-change-key.8.html
наб autouploader f2bb78cd74 Manpage update by job 1445917
2025-03-09 17:57:25 +00:00

227 lines
12 KiB
HTML
Raw Permalink Blame History

<!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-TPM1X-CHANGE-KEY(8)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM1X-CHANGE-KEY(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM1X-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-tpm1x-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-tpm1x-change-key</code></td>
<td>[<code class="Fl">-b</code> <var class="Ar">backup-file</var>]
[<code class="Fl">-P</code>
<var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]&#x2026;]
<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-tpm1x-change-key</code> will open its encryption root
in its stead. <code class="Nm">zfs-tpm1x-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 TPM, which
<i class="Em">must</i> be TPM-1.X-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">TPM1.X</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 wrapping key is generated on the TPM, optionally
backed up (see <a class="Sx" href="#OPTIONS">OPTIONS</a>), and sealed on the
TPM; the user is prompted for an optional passphrase to protect the key
with, and for the SRK passphrase, set when taking ownership, if not
&quot;well-known&quot; (all zeroes).</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">TPM1.X</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">parent-key-blob</var><code class="Cm">:</code><var class="Ar">sealed-object-blob</var></li>
</ul>
<p class="Pp"><code class="Li">tzpfms.backend</code> identifies this dataset for
work with <b class="Sy">TPM1.X</b>-back-ended <code class="Nm">tzpfms</code>
programs (namely
<a class="Xr" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key(8)</a>,
<a class="Xr" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-load-key(8)</a>,
and
<a class="Xr" href="zfs-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key(8)</a>).</p>
<p class="Pp"><code class="Li">tzpfms.key</code> is a colon-separated pair of
hexadecimal-string (i.e. &quot;4F7730&quot; for &quot;Ow0&quot;) blobs; the
first one represents the RSA key protecting the blob, and it is protected
with either the passphrase, if provided, or the SHA1 constant
<code class="Li">CE4CF677875B5EB8993591D5A9AF1ED24A3A8736</code>; the second
represents the sealed object containing the wrapping key, and is protected
with the SHA1 constant
<code class="Li">B9EE715DBE4B243FAA81EA04306E063710383E35</code>. There
exists no other user-land tool for decrypting 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-tpm1x-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-tpm1x-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-tpm1x-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">&lt;</code>
<var class="Ar">backup-file</var></code></div>
<p class="Pp"></p>
</dd>
<dt id="P"><a class="permalink" href="#P"><code class="Fl">-P</code></a>
<var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]&#x2026;</dt>
<dd>Bind the key to space- or comma-separated <var class="Ar">PCR</var>s
&#x2014; if they change, the wrapping key will not be able to be unsealed.
The minimum number of PCRs for a PC TPM is
<a class="permalink" href="#24"><b class="Sy" id="24">24</b></a> (numbered
[<a class="permalink" href="#0"><b class="Sy" id="0">0</b></a>,
<a class="permalink" href="#23"><b class="Sy" id="23">23</b></a>]). For
most, this is also the maximum.</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>&quot;new&quot; 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>&quot;again&quot; 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="TPM1.X_back-end_configuration"><a class="permalink" href="#TPM1.X_back-end_configuration">TPM1.X
back-end configuration</a></h1>
<section class="Ss">
<h2 class="Ss" id="TPM_selection"><a class="permalink" href="#TPM_selection">TPM
selection</a></h2>
<p class="Pp">The <code class="Nm">tzpfms</code> suite connects to a local
<a class="Xr" href="https://manpages.debian.org/bookworm/tcsd.8">tcsd(8)</a>
process (at <span class="Pa">localhost:30003</span>) by default. Use the
environment variable <code class="Ev">TZPFMS_TPM1X</code> to specify a
remote TCS hostname.</p>
<p class="Pp">The TrouSerS
<a class="Xr" href="https://manpages.debian.org/bookworm/tcsd.8">tcsd(8)</a>
daemon will try <span class="Pa">/dev/tpm0</span>, then
<span class="Pa">/udev/tpm0</span>, then <span class="Pa">/dev/tpm</span>;
by occupying one of the earlier ones with, for example, shell redirection, a
later one can be selected.</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 TrouSerS project page at
<a class="Lk" href="https://sourceforge.net/projects/trousers">https://sourceforge.net/projects/trousers</a>.</p>
<p class="Pp">The TPM 1.2 main specification index at
<a class="Lk" href="https://trustedcomputinggroup.org/resource/tpm-main-specification">https://trustedcomputinggroup.org/resource/tpm-main-specification</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/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">PCR allocations:
<a class="Lk" href="https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers">https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers</a>
and
<a class="Lk" href="https://trustedcomputinggroup.org/wp-content/uploads/PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf">https://trustedcomputinggroup.org/wp-content/uploads/PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf</a>,
Section 2.3.4 &quot;PCR Usage&quot;, Table 1.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">March 11, 2024</td>
<td class="foot-os">tzpfms 0.4.1-1-gfd16dbb</td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink