mirror of
https://git.sr.ht/~nabijaczleweli/tzpfms
synced 2025-04-25 09:52:11 +03:00
273 lines
16 KiB
HTML
273 lines
16 KiB
HTML
<!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-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> —
|
|
<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>]
|
|
[<code class="Fl">-P</code>
|
|
<var class="Ar">algorithm</var><code class="Cm">:</code><var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]…[<code class="Cm">+</code><var class="Ar">algorithm</var><code class="Cm">:</code><var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]…]…
|
|
[<code class="Fl">-A</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">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/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-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 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 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">persistent-object-ID</var>[<code class="Cm">;</code><var class="Ar">algorithm</var><code class="Cm">:</code><var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]…[<code class="Cm">+</code><var class="Ar">algorithm</var><code class="Cm">:</code><var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</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, optionally followed by a semicolon and PCR list as specified
|
|
with <code class="Fl">-P</code>, normalised to be
|
|
<code class="Nm">tpm-tools</code>-toolchain-compatible; 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="Cm">%%</code><code class="Li">;*</code><code class="Ev">}</code>
|
|
with <code class="Fl">-p</code>
|
|
"<code class="Li">str:</code><code class="Ev">${passphrase}</code>"
|
|
or <code class="Fl">-p</code>
|
|
"<code class="Li">pcr:</code><code class="Ev">${tzpfms.key</code><code class="Cm">#</code><code class="Li">*;</code><code class="Ev">}</code>",
|
|
as the case may be, 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 passphrase 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 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>
|
|
<p class="Pp"></p>
|
|
</dd>
|
|
<dt id="P"><a class="permalink" href="#P"><code class="Fl">-P</code></a>
|
|
<var class="Ar">algorithm</var><code class="Cm">:</code><var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]…[<code class="Cm">+</code><var class="Ar">algorithm</var><code class="Cm">:</code><var class="Ar">PCR</var>[<code class="Cm">,</code><var class="Ar">PCR</var>]…]…</dt>
|
|
<dd>Bind the key to space- or comma-separated <var class="Ar">PCR</var>s
|
|
within their corresponding hashing <var class="Ar">algorithm</var>
|
|
— if they change, the wrapping key will not be able to be unsealed.
|
|
There are <a class="permalink" href="#24"><b class="Sy" id="24">24</b></a>
|
|
PCRs, 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>].
|
|
<p class="Pp" id="sha1"><var class="Ar">algorithm</var> may be any of
|
|
case-insensitive
|
|
"<a class="permalink" href="#sha1"><b class="Sy">sha1</b></a>",
|
|
"<a class="permalink" href="#sha256"><b class="Sy" id="sha256">sha256</b></a>",
|
|
"<a class="permalink" href="#sha384"><b class="Sy" id="sha384">sha384</b></a>",
|
|
"<a class="permalink" href="#sha512"><b class="Sy" id="sha512">sha512</b></a>",
|
|
"<a class="permalink" href="#sm3_256"><b class="Sy" id="sm3_256">sm3_256</b></a>",
|
|
"<a class="permalink" href="#sm3-256"><b class="Sy" id="sm3-256">sm3-256</b></a>",
|
|
"<a class="permalink" href="#sha3_256"><b class="Sy" id="sha3_256">sha3_256</b></a>",
|
|
"<a class="permalink" href="#sha3-256"><b class="Sy" id="sha3-256">sha3-256</b></a>",
|
|
"<a class="permalink" href="#sha3_384"><b class="Sy" id="sha3_384">sha3_384</b></a>",
|
|
"<a class="permalink" href="#sha3-384"><b class="Sy" id="sha3-384">sha3-384</b></a>",
|
|
"<a class="permalink" href="#sha3_512"><b class="Sy" id="sha3_512">sha3_512</b></a>",
|
|
or
|
|
"<a class="permalink" href="#sha3-512"><b class="Sy" id="sha3-512">sha3-512</b></a>",
|
|
and must be supported by the TPM.</p>
|
|
<p class="Pp"></p>
|
|
</dd>
|
|
<dt id="A"><a class="permalink" href="#A"><code class="Fl">-A</code></a></dt>
|
|
<dd>With <code class="Fl">-P</code>, also prompt for a passphrase. This is
|
|
skipped by default because the passphrase is
|
|
<a class="permalink" href="#OR"><i class="Em" id="OR">OR</i></a>ed with
|
|
the PCR policy — the wrapping key can be unsealed
|
|
<a class="permalink" href="#either"><i class="Em" id="either">either</i></a>
|
|
passphraseless with the right PCRs
|
|
<a class="permalink" href="#or"><i class="Em" id="or">or</i></a> with the
|
|
passphrase, and this is usually not the intent.</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="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/resource/tpm-library-specification/">https://trustedcomputinggroup.org/resource/tpm-library-specification/</a>,
|
|
<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>
|
|
<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"><a class="Xr" href="https://manpages.debian.org/bookworm/tpm2_unseal.1">tpm2_unseal(1)</a></p>
|
|
<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 "PCR Usage", Table 1.</p>
|
|
</section>
|
|
</div>
|
|
<table class="foot">
|
|
<tr>
|
|
<td class="foot-date">February 28, 2024</td>
|
|
<td class="foot-os">tzpfms 0.3.4-28-g7e4ea2c</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|