mirror of
https://git.sr.ht/~nabijaczleweli/tzpfms
synced 2025-06-14 23:12:05 +03:00
107 lines
6.6 KiB
Plaintext
107 lines
6.6 KiB
Plaintext
<div class='mp'>
|
|
|
|
<h2 id="NAME">NAME</h2>
|
|
<p class="man-name">
|
|
<code>zfs-tpm2-change-key</code> - <span class="man-whatis">change ZFS dataset key to one stored on the TPM</span>
|
|
</p>
|
|
<h2 id="SYNOPSIS">SYNOPSIS</h2>
|
|
|
|
<p><code>zfs-tpm2-change-key</code> [-b file] <var>dataset</var></p>
|
|
|
|
<h2 id="DESCRIPTION">DESCRIPTION</h2>
|
|
|
|
<p>To normalise <code>dataset</code>, <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> will open its encryption root in its stead.
|
|
<a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> will <em>never</em> create or destroy encryption roots; use <strong><a class="man-ref" href="https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html">zfs<span class="s">(8)</span></a> change-key</strong> for that.</p>
|
|
|
|
<p>First, a connection is made to the TPM, which <em>must</em> be TPM-2.0-compatible.</p>
|
|
|
|
<p>If <code>dataset</code> was previously encrypted with tzpfms and the <em>TPM2</em> 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>Next, a new wrapping key is be generated on the TPM, optionally backed up (see <a href="#OPTIONS" title="OPTIONS" data-bare-link="true">OPTIONS</a>),
|
|
and sealed to a persistent object on the TPM under the owner hierarchy.</p>
|
|
|
|
<p>The following properties are set on <code>dataset</code>:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>xyz.nabijaczleweli:tzpfms.backend</code>=<code>TPM2</code>
|
|
</li>
|
|
<li>
|
|
<code>xyz.nabijaczleweli:tzpfms.key</code>=<em>(ID of persistent object)</em>
|
|
</li>
|
|
</ul>
|
|
|
|
<p><code>tzpfms.backend</code> identifies this dataset for work with <em>TPM2</em>-back-ended tzpfms tools
|
|
(namely <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a>, <a class="man-ref" href="zfs-tpm2-load-key.8.html">zfs-tpm2-load-key<span class="s">(8)</span></a>, and <a class="man-ref" href="zfs-tpm2-clear-key.8.html">zfs-tpm2-clear-key<span class="s">(8)</span></a>).</p>
|
|
|
|
<p><code>tzpfms.key</code> is an integer representing the sealed object;
|
|
if needed, it can be passed to <strong><a class="man-ref" href="https://manpages.debian.org/bullseye/tpm2-tools/tpm2_unseal.1.en.html">tpm2_unseal<span class="s">(1)</span></a> -c ${tzpfms.key}</strong> or equivalent for back-up (see <a href="#OPTIONS" title="OPTIONS" data-bare-link="true">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>Finally, the equivalent of <strong><a class="man-ref" href="https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html">zfs<span class="s">(8)</span></a> change-key -o keylocation=prompt -o keyformat=raw dataset</strong> 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>A final verification should be made by running <strong><a class="man-ref" href="zfs-tpm2-load-key.8.html">zfs-tpm2-load-key<span class="s">(8)</span></a> -n dataset</strong>.
|
|
If that command succeeds, all is well,
|
|
but otherwise the dataset can be manually rolled back to a password with <strong><a class="man-ref" href="zfs-tpm2-clear-key.8.html">zfs-tpm2-clear-key<span class="s">(8)</span></a> dataset</strong> (or, if that fails to work, <strong><a class="man-ref" href="https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html">zfs<span class="s">(8)</span></a> change-key -o keyformat=passphrase dataset</strong>), and you are hereby asked to report a bug, please.</p>
|
|
|
|
<p><strong><a class="man-ref" href="zfs-tpm2-clear-key.8.html">zfs-tpm2-clear-key<span class="s">(8)</span></a> dataset</strong> can be used to free the TPM persistent object and go back to using a password.</p>
|
|
|
|
<h2 id="OPTIONS">OPTIONS</h2>
|
|
|
|
<dl>
|
|
<dt>
|
|
<code>-b</code> <em>file</em>
|
|
</dt>
|
|
<dd>Save a back-up of the key to <em>file</em>, which must not exist beforehand.
|
|
This back-up <strong>must</strong> be stored securely, off-site.
|
|
In case of a catastrophic event, the key can be loaded by running <strong><a class="man-ref" href="https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html">zfs<span class="s">(8)</span></a> load-key dataset < backup-file</strong>.</dd>
|
|
</dl>
|
|
|
|
<h2 id="TPM2-back-end-configuration">TPM2 back-end configuration</h2>
|
|
|
|
<h3 id="Environment-variables">Environment variables</h3>
|
|
|
|
<dl>
|
|
<dt>
|
|
<code>TSS2_LOG</code>=</dt>
|
|
<dd>Any of: <em>NONE</em>, <em>ERROR</em>, <em>WARNING</em>, <em>INFO</em>, <em>DEBUG</em>, <em>TRACE</em>. Default: <em>WARNING</em>.</dd>
|
|
</dl>
|
|
|
|
<h3 id="TPM-selection">TPM selection</h3>
|
|
|
|
<p>The library <code>libtss2-tcti-default.so</code> can be linked to any of the <code>libtss2-tcti-*.so</code> libraries to select the default,
|
|
otherwise <code>/dev/tpmrm0</code>, then <code>/dev/tpm0</code>, then <code>localhost:2321</code> will be tried, in order (see <a class="man-ref" href="https://www.mankier.com/3/ESYS_CONTEXT">ESYS_CONTEXT<span class="s">(3)</span></a>).</p>
|
|
|
|
<h3 id="See-also">See also</h3>
|
|
|
|
<p>The tpm2-tss git repository at <a href="https://github.com/tpm2-software/tpm2-tss" data-bare-link="true">https://github.com/tpm2-software/tpm2-tss</a> and the documentation at <a href="https://tpm2-tss.readthedocs.io" data-bare-link="true">https://tpm2-tss.readthedocs.io</a>.</p>
|
|
|
|
<p>The TPM 2.0 specifications, mainly at <<a href="https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf" data-bare-link="true">https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf</a>> and related pages.</p>
|
|
|
|
<h2 id="AUTHOR">AUTHOR</h2>
|
|
|
|
<p>Written by наб <<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>></p>
|
|
|
|
<h2 id="SPECIAL-THANKS">SPECIAL THANKS</h2>
|
|
|
|
<p>To all who support further development, in particular:</p>
|
|
|
|
<ul>
|
|
<li>ThePhD</li>
|
|
<li>Embark Studios</li>
|
|
</ul>
|
|
|
|
<h2 id="REPORTING-BUGS">REPORTING BUGS</h2>
|
|
|
|
<p><<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>></p>
|
|
|
|
<p><<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>>, archived at <<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>></p>
|
|
|
|
<h2 id="SEE-ALSO">SEE ALSO</h2>
|
|
|
|
<p><<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>></p>
|
|
</div>
|