third-party-mirrors/tzpfms
1
0
Fork 0
mirror of https://git.sr.ht/~nabijaczleweli/tzpfms synced 2025-04-21 09:47:35 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Manpage update by job 327356

Browse Source
This commit is contained in:
наб autouploader 2020-10-25 12:07:50 +00:00
parent d0979bb54c
commit 7dc56023f1
13 changed files with 1036 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
index.txt
View File

@ -3,6 +3,7 @@ zfs-tpm2-load-key(8) zfs-tpm2-load-key.8.ronn
zfs-tpm2-clear-key(8) zfs-tpm2-clear-key.8.ronn
zfs(8) https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html
tcsd(8) https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html
tpm2_unseal(1) https://manpages.debian.org/bullseye/tpm2-tools/tpm2_unseal.1.en.html
ESYS_CONTEXT(3) https://www.mankier.com/3/ESYS_CONTEXT

60
zfs-tpm1x-change-key.8 Normal file
View File

@ -0,0 +1,60 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM1X\-CHANGE\-KEY" "8" "October 2020" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm1x\-change\-key\fR \- change ZFS dataset key to one stored on the TPM
.SH "SYNOPSIS"
\fBzfs\-tpm1x\-change\-key\fR [\-b file] \fIdataset\fR
.SH "DESCRIPTION"
To normalise \fBdataset\fR, zfs\-tpm1x\-change\-key(8) will open its encryption root in its stead\. zfs\-tpm1x\-change\-key(8) will \fInever\fR create or destroy encryption roots; use \fBzfs(8) change\-key\fR for that\.
.P
First, a connection is made to the TPM, which \fImust\fR be TPM\-1\.X\-compatible\.
.P
If \fBdataset\fR was previously encrypted with tzpfms and the \fITPM1\.X\fR back\-end was used, the metadata will be silently cleared\. Otherwise, or in case of an error, data required for manual intervention will be printed to the standard error stream\.
.P
Next, a new wrapping key is be generated on the TPM, optionally backed up (see \fIOPTIONS\fR), and sealed on the TPM; if the SRK passphrase, set when taking ownership, is not "well\-known" (all zeroes), the user is prompted for it; the user is always prompted for an optional passphrase to protect the key with\.
.P
The following properties are set on \fBdataset\fR:
.IP "\[ci]" 4
\fBxyz\.nabijaczleweli:tzpfms\.backend\fR=\fBTPM1\.X\fR
.IP "\[ci]" 4
\fBxyz\.nabijaczleweli:tzpfms\.key\fR=\fI(parent key blob)\fR\fB:\fR\fI(sealed object blob)\fR
.IP "" 0
.P
\fBtzpfms\.backend\fR identifies this dataset for work with \fITPM1\.X\fR\-back\-ended tzpfms tools (namely zfs\-tpm1x\-change\-key(8), zfs\-tpm1x\-load\-key(8), and zfs\-tpm1x\-clear\-key(8))\.
.P
\fBtzpfms\.key\fR is a colon\-separated pair of hexadecimal\-string (i\.e\. "4F7730" for "Ow0") blobs; the first one represents the RSA key protecting the blob, and it is protected with either the password, if provided, or the SHA1 constant \fICE4CF677875B5EB8993591D5A9AF1ED24A3A8736\fR; the second represents the sealed object containing the wrapping key, and is protected with the SHA1 constant \fIB9EE715DBE4B243FAA81EA04306E063710383E35\fR\. There exists no other user\-land tool for decrypting this\. (TODO: make an LD_PRELOADable for extracting the key maybe)
.P
Finally, the equivalent of \fBzfs(8) change\-key \-o keylocation=prompt \-o keyformat=raw dataset\fR 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
A final verification should be made by running \fBzfs\-tpm1x\-load\-key(8) \-n dataset\fR\. If that command succeeds, all is well, but otherwise the dataset can be manually rolled back to a password with \fBzfs\-tpm1x\-clear\-key(8) dataset\fR (or, if that fails to work, \fBzfs(8) change\-key \-o keyformat=passphrase dataset\fR), and you are hereby asked to report a bug, please\.
.P
\fBzfs\-tpm1x\-clear\-key(8) dataset\fR can be used to clear the properties and go back to using a password\.
.SH "OPTIONS"
.TP
\fB\-b\fR \fIfile\fR
Save a back\-up of the key to \fIfile\fR, which must not exist beforehand\. This back\-up \fBmust\fR be stored securely, off\-site\. In case of a catastrophic event, the key can be loaded by running \fBzfs(8) load\-key dataset < backup\-file\fR\.
.SH "TPM1\.X back\-end configuration"
.SS "TPM selection"
The tzpfms suite always connects to a local tcsd(8) process (at \fBlocalhost:30003\fR)\.
.P
The TrouSerS tcsd(8) daemon will try \fB/dev/tpm0\fR, then \fB/udev/tpm0\fR, then \fB/dev/tpm\fR; by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected\.
.SS "See also"
The TrouSerS project page at \fIhttps://sourceforge\.net/projects/trousers\fR\.
.P
The TPM 1\.2 main specification index at <\fIhttps://trustedcomputinggroup\.org/resource/tpm\-main\-specification\fR>\.
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
To all who support further development, in particular:
.IP "\[ci]" 4
ThePhD
.IP "\[ci]" 4
Embark Studios
.IP "" 0
.SH "REPORTING BUGS"
<\fIhttps://todo\.sr\.ht/~nabijaczleweli/tzpfms\fR>
.P
<\fI~nabijaczleweli/tzpfms@lists\.sr\.ht\fR>, archived at <\fIhttps://lists\.sr\.ht/~nabijaczleweli/tzpfms\fR>
.SH "SEE ALSO"
<\fIhttps://git\.sr\.ht/~nabijaczleweli/tzpfms\fR>

186
zfs-tpm1x-change-key.8.html Normal file
View File

@ -0,0 +1,186 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html;charset=utf8'>
<meta name='generator' content='Ronn-NG/v0.9.1 (http://github.com/apjanke/ronn-ng/tree/0.9.1)'>
<title>zfs-tpm1x-change-key(8) - change ZFS dataset key to one stored on the TPM</title>
<style type='text/css' media='all'>
/* style: man */
body#manpage {margin:0}
.mp {max-width:100ex;padding:0 9ex 1ex 4ex}
.mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
.mp h2 {margin:10px 0 0 0}
.mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
.mp h3 {margin:0 0 0 4ex}
.mp dt {margin:0;clear:left}
.mp dt.flush {float:left;width:8ex}
.mp dd {margin:0 0 0 9ex}
.mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
.mp pre {margin-bottom:20px}
.mp pre+h2,.mp pre+h3 {margin-top:22px}
.mp h2+pre,.mp h3+pre {margin-top:5px}
.mp img {display:block;margin:auto}
.mp h1.man-title {display:none}
.mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
.mp h2 {font-size:16px;line-height:1.25}
.mp h1 {font-size:20px;line-height:2}
.mp {text-align:justify;background:#fff}
.mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
.mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
.mp u {text-decoration:underline}
.mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
.mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
.mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
.mp b.man-ref {font-weight:normal;color:#434241}
.mp pre {padding:0 4ex}
.mp pre code {font-weight:normal;color:#434241}
.mp h2+pre,h3+pre {padding-left:0}
ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
ol.man-decor {width:100%}
ol.man-decor li.tl {text-align:left}
ol.man-decor li.tc {text-align:center;letter-spacing:4px}
ol.man-decor li.tr {text-align:right;float:right}
</style>
</head>
<!--
The following styles are deprecated and will be removed at some point:
div#man, div#man ol.man, div#man ol.head, div#man ol.man.
The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
.man-navigation should be used instead.
-->
<body id='manpage'>
<div class='mp' id='man'>
<div class='man-navigation' style='display:none'>
<a href="#NAME">NAME</a>
<a href="#SYNOPSIS">SYNOPSIS</a>
<a href="#DESCRIPTION">DESCRIPTION</a>
<a href="#OPTIONS">OPTIONS</a>
<a href="#TPM1-X-BACK-END-CONFIGURATION">TPM1.X back-end configuration</a>
<a href="#AUTHOR">AUTHOR</a>
<a href="#SPECIAL-THANKS">SPECIAL THANKS</a>
<a href="#REPORTING-BUGS">REPORTING BUGS</a>
<a href="#SEE-ALSO">SEE ALSO</a>
</div>
<ol class='man-decor man-head man head'>
<li class='tl'>zfs-tpm1x-change-key(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm1x-change-key(8)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm1x-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-tpm1x-change-key</code> [-b file] <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p>To normalise <code>dataset</code>, <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> will open its encryption root in its stead.
<span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> 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-1.X-compatible.</p>
<p>If <code>dataset</code> was previously encrypted with tzpfms and the <em>TPM1.X</em> back-end was used, the metadata will be silently cleared.
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 on the TPM;
if the SRK passphrase, set when taking ownership, is not "well-known" (all zeroes), the user is prompted for it;
the user is always prompted for an optional passphrase to protect the key with.</p>
<p>The following properties are set on <code>dataset</code>:</p>
<ul>
<li>
<code>xyz.nabijaczleweli:tzpfms.backend</code>=<code>TPM1.X</code>
</li>
<li>
<code>xyz.nabijaczleweli:tzpfms.key</code>=<em>(parent key blob)</em><code>:</code><em>(sealed object blob)</em>
</li>
</ul>
<p><code>tzpfms.backend</code> identifies this dataset for work with <em>TPM1.X</em>-back-ended tzpfms tools
(namely <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span>, <span class="man-ref">zfs-tpm1x-load-key<span class="s">(8)</span></span>, and <span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span>).</p>
<p><code>tzpfms.key</code> is a colon-separated pair of hexadecimal-string (i.e. "4F7730" for "Ow0") blobs;
the first one represents the RSA key protecting the blob,
and it is protected with either the password, if provided, or the SHA1 constant <em>CE4CF677875B5EB8993591D5A9AF1ED24A3A8736</em>;
the second represents the sealed object containing the wrapping key,
and is protected with the SHA1 constant <em>B9EE715DBE4B243FAA81EA04306E063710383E35</em>.
There exists no other user-land tool for decrypting this. (TODO: make an LD_PRELOADable for extracting the key maybe)</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 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><span class="man-ref">zfs-tpm1x-load-key<span class="s">(8)</span></span> -n dataset</strong>.
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a password with <strong><span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span> 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><span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span> dataset</strong> can be used to clear the properties 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 &lt; backup-file</strong>.</dd>
</dl>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite always connects to a local <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> process (at <code>localhost:30003</code>).</p>
<p>The TrouSerS <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> daemon will try <code>/dev/tpm0</code>, then <code>/udev/tpm0</code>, then <code>/dev/tpm</code>;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.</p>
<h3 id="See-also">See also</h3>
<p>The TrouSerS project page at <a href="https://sourceforge.net/projects/trousers" data-bare-link="true">https://sourceforge.net/projects/trousers</a>.</p>
<p>The TPM 1.2 main specification index at &lt;<a href="https://trustedcomputinggroup.org/resource/tpm-main-specification" data-bare-link="true">https://trustedcomputinggroup.org/resource/tpm-main-specification</a>&gt;.</p>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by наб &lt;<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>&gt;</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>&lt;<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<p>&lt;<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>&gt;, archived at &lt;<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p>&lt;<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<ol class='man-decor man-foot man foot'>
<li class='tl'>tzpfms developers</li>
<li class='tc'>October 2020</li>
<li class='tr'>zfs-tpm1x-change-key(8)</li>
</ol>
</div>
</body>
</html>

105
zfs-tpm1x-change-key.8.html_fragment Normal file
View File

@ -0,0 +1,105 @@
<div class='mp'>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm1x-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-tpm1x-change-key</code> [-b file] <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p>To normalise <code>dataset</code>, <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> will open its encryption root in its stead.
<span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> 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-1.X-compatible.</p>
<p>If <code>dataset</code> was previously encrypted with tzpfms and the <em>TPM1.X</em> back-end was used, the metadata will be silently cleared.
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 on the TPM;
if the SRK passphrase, set when taking ownership, is not "well-known" (all zeroes), the user is prompted for it;
the user is always prompted for an optional passphrase to protect the key with.</p>
<p>The following properties are set on <code>dataset</code>:</p>
<ul>
<li>
<code>xyz.nabijaczleweli:tzpfms.backend</code>=<code>TPM1.X</code>
</li>
<li>
<code>xyz.nabijaczleweli:tzpfms.key</code>=<em>(parent key blob)</em><code>:</code><em>(sealed object blob)</em>
</li>
</ul>
<p><code>tzpfms.backend</code> identifies this dataset for work with <em>TPM1.X</em>-back-ended tzpfms tools
(namely <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span>, <span class="man-ref">zfs-tpm1x-load-key<span class="s">(8)</span></span>, and <span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span>).</p>
<p><code>tzpfms.key</code> is a colon-separated pair of hexadecimal-string (i.e. "4F7730" for "Ow0") blobs;
the first one represents the RSA key protecting the blob,
and it is protected with either the password, if provided, or the SHA1 constant <em>CE4CF677875B5EB8993591D5A9AF1ED24A3A8736</em>;
the second represents the sealed object containing the wrapping key,
and is protected with the SHA1 constant <em>B9EE715DBE4B243FAA81EA04306E063710383E35</em>.
There exists no other user-land tool for decrypting this. (TODO: make an LD_PRELOADable for extracting the key maybe)</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 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><span class="man-ref">zfs-tpm1x-load-key<span class="s">(8)</span></span> -n dataset</strong>.
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a password with <strong><span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span> 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><span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span> dataset</strong> can be used to clear the properties 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 &lt; backup-file</strong>.</dd>
</dl>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite always connects to a local <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> process (at <code>localhost:30003</code>).</p>
<p>The TrouSerS <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> daemon will try <code>/dev/tpm0</code>, then <code>/udev/tpm0</code>, then <code>/dev/tpm</code>;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.</p>
<h3 id="See-also">See also</h3>
<p>The TrouSerS project page at <a href="https://sourceforge.net/projects/trousers" data-bare-link="true">https://sourceforge.net/projects/trousers</a>.</p>
<p>The TPM 1.2 main specification index at &lt;<a href="https://trustedcomputinggroup.org/resource/tpm-main-specification" data-bare-link="true">https://trustedcomputinggroup.org/resource/tpm-main-specification</a>&gt;.</p>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by наб &lt;<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>&gt;</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>&lt;<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<p>&lt;<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>&gt;, archived at &lt;<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p>&lt;<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
</div>

89
zfs-tpm1x-change-key.md Normal file
View File

@ -0,0 +1,89 @@
zfs-tpm1x-change-key(8) -- change ZFS dataset key to one stored on the TPM
==========================================================================
## SYNOPSIS
`zfs-tpm1x-change-key` [-b file] <dataset>
## DESCRIPTION
To normalise `dataset`, zfs-tpm1x-change-key(8) will open its encryption root in its stead.
zfs-tpm1x-change-key(8) will *never* create or destroy encryption roots; use **zfs(8) change-key** for that.
First, a connection is made to the TPM, which *must* be TPM-1.X-compatible.
If `dataset` was previously encrypted with tzpfms and the *TPM1.X* back-end was used, the metadata will be silently cleared.
Otherwise, or in case of an error, data required for manual intervention will be printed to the standard error stream.
Next, a new wrapping key is be generated on the TPM, optionally backed up (see [OPTIONS][]),
and sealed on the TPM;
if the SRK passphrase, set when taking ownership, is not "well-known" (all zeroes), the user is prompted for it;
the user is always prompted for an optional passphrase to protect the key with.
The following properties are set on `dataset`:
* `xyz.nabijaczleweli:tzpfms.backend`=`TPM1.X`
* `xyz.nabijaczleweli:tzpfms.key`=*(parent key blob)*`:`*(sealed object blob)*
`tzpfms.backend` identifies this dataset for work with *TPM1.X*-back-ended tzpfms tools
(namely zfs-tpm1x-change-key(8), zfs-tpm1x-load-key(8), and zfs-tpm1x-clear-key(8)).
`tzpfms.key` is a colon-separated pair of hexadecimal-string (i.e. "4F7730" for "Ow0") blobs;
the first one represents the RSA key protecting the blob,
and it is protected with either the password, if provided, or the SHA1 constant *CE4CF677875B5EB8993591D5A9AF1ED24A3A8736*;
the second represents the sealed object containing the wrapping key,
and is protected with the SHA1 constant *B9EE715DBE4B243FAA81EA04306E063710383E35*.
There exists no other user-land tool for decrypting this. (TODO: make an LD_PRELOADable for extracting the key maybe)
Finally, the equivalent of **zfs(8) change-key -o keylocation=prompt -o keyformat=raw 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.
A final verification should be made by running **zfs-tpm1x-load-key(8) -n dataset**.
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a password with **zfs-tpm1x-clear-key(8) dataset** (or, if that fails to work, **zfs(8) change-key -o keyformat=passphrase dataset**), and you are hereby asked to report a bug, please.
**zfs-tpm1x-clear-key(8) dataset** can be used to clear the properties and go back to using a password.
## OPTIONS
* `-b` *file*:
Save a back-up of the key to *file*, which must not exist beforehand.
This back-up **must** be stored securely, off-site.
In case of a catastrophic event, the key can be loaded by running **zfs(8) load-key dataset < backup-file**.
## TPM1.X back-end configuration
### TPM selection
The tzpfms suite always connects to a local tcsd(8) process (at `localhost:30003`).
The TrouSerS tcsd(8) daemon will try `/dev/tpm0`, then `/udev/tpm0`, then `/dev/tpm`;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.
### See also
The TrouSerS project page at <https://sourceforge.net/projects/trousers>.
The TPM 1.2 main specification index at &lt;<https://trustedcomputinggroup.org/resource/tpm-main-specification>&gt;.
## AUTHOR
Written by наб &lt;<nabijaczleweli@nabijaczleweli.xyz>&gt;
## SPECIAL THANKS
To all who support further development, in particular:
* ThePhD
* Embark Studios
## REPORTING BUGS
&lt;<https://todo.sr.ht/~nabijaczleweli/tzpfms>&gt;
&lt;<mailto:~nabijaczleweli/tzpfms@lists.sr.ht>&gt;, archived at &lt;<https://lists.sr.ht/~nabijaczleweli/tzpfms>&gt;
## SEE ALSO
&lt;<https://git.sr.ht/~nabijaczleweli/tzpfms>&gt;

40
zfs-tpm1x-clear-key.8 Normal file
View File

@ -0,0 +1,40 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM1X\-CLEAR\-KEY" "8" "October 2020" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm1x\-clear\-key\fR \- rewrap ZFS dataset key in passsword and clear tzpfms TPM1\.X metadata
.SH "SYNOPSIS"
\fBzfs\-tpm1x\-clear\-key\fR \fIdataset\fR
.SH "DESCRIPTION"
zfs\-tpm1x\-clear\-key(8), after verifying that \fBdataset\fR was encrypted with tzpfms backend \fITPM1\.X\fR will:
.IP "1." 4
perform the equivalent of \fBzfs(8) change\-key \-o keylocation=prompt \-o keyformat=passphrase dataset\fR,
.IP "2." 4
remove the \fBxyz\.nabijaczleweli:tzpfms\.{backend,key}\fR properties from \fBdataset\fR\.
.IP "" 0
.P
See zfs\-tpm1x\-change\-key(8) for a detailed description\.
.SH "TPM1\.X back\-end configuration"
.SS "TPM selection"
The tzpfms suite always connects to a local tcsd(8) process (at \fBlocalhost:30003\fR)\.
.P
The TrouSerS tcsd(8) daemon will try \fB/dev/tpm0\fR, then \fB/udev/tpm0\fR, then \fB/dev/tpm\fR; by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected\.
.SS "See also"
The TrouSerS project page at \fIhttps://sourceforge\.net/projects/trousers\fR\.
.P
The TPM 1\.2 main specification index at <\fIhttps://trustedcomputinggroup\.org/resource/tpm\-main\-specification\fR>\.
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
To all who support further development, in particular:
.IP "\[ci]" 4
ThePhD
.IP "\[ci]" 4
Embark Studios
.IP "" 0
.SH "REPORTING BUGS"
<\fIhttps://todo\.sr\.ht/~nabijaczleweli/tzpfms\fR>
.P
<\fI~nabijaczleweli/tzpfms@lists\.sr\.ht\fR>, archived at <\fIhttps://lists\.sr\.ht/~nabijaczleweli/tzpfms\fR>
.SH "SEE ALSO"
<\fIhttps://git\.sr\.ht/~nabijaczleweli/tzpfms\fR>

139
zfs-tpm1x-clear-key.8.html Normal file
View File

@ -0,0 +1,139 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html;charset=utf8'>
<meta name='generator' content='Ronn-NG/v0.9.1 (http://github.com/apjanke/ronn-ng/tree/0.9.1)'>
<title>zfs-tpm1x-clear-key(8) - rewrap ZFS dataset key in passsword and clear tzpfms TPM1.X metadata</title>
<style type='text/css' media='all'>
/* style: man */
body#manpage {margin:0}
.mp {max-width:100ex;padding:0 9ex 1ex 4ex}
.mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
.mp h2 {margin:10px 0 0 0}
.mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
.mp h3 {margin:0 0 0 4ex}
.mp dt {margin:0;clear:left}
.mp dt.flush {float:left;width:8ex}
.mp dd {margin:0 0 0 9ex}
.mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
.mp pre {margin-bottom:20px}
.mp pre+h2,.mp pre+h3 {margin-top:22px}
.mp h2+pre,.mp h3+pre {margin-top:5px}
.mp img {display:block;margin:auto}
.mp h1.man-title {display:none}
.mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
.mp h2 {font-size:16px;line-height:1.25}
.mp h1 {font-size:20px;line-height:2}
.mp {text-align:justify;background:#fff}
.mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
.mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
.mp u {text-decoration:underline}
.mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
.mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
.mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
.mp b.man-ref {font-weight:normal;color:#434241}
.mp pre {padding:0 4ex}
.mp pre code {font-weight:normal;color:#434241}
.mp h2+pre,h3+pre {padding-left:0}
ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
ol.man-decor {width:100%}
ol.man-decor li.tl {text-align:left}
ol.man-decor li.tc {text-align:center;letter-spacing:4px}
ol.man-decor li.tr {text-align:right;float:right}
</style>
</head>
<!--
The following styles are deprecated and will be removed at some point:
div#man, div#man ol.man, div#man ol.head, div#man ol.man.
The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
.man-navigation should be used instead.
-->
<body id='manpage'>
<div class='mp' id='man'>
<div class='man-navigation' style='display:none'>
<a href="#NAME">NAME</a>
<a href="#SYNOPSIS">SYNOPSIS</a>
<a href="#DESCRIPTION">DESCRIPTION</a>
<a href="#TPM1-X-BACK-END-CONFIGURATION">TPM1.X back-end configuration</a>
<a href="#AUTHOR">AUTHOR</a>
<a href="#SPECIAL-THANKS">SPECIAL THANKS</a>
<a href="#REPORTING-BUGS">REPORTING BUGS</a>
<a href="#SEE-ALSO">SEE ALSO</a>
</div>
<ol class='man-decor man-head man head'>
<li class='tl'>zfs-tpm1x-clear-key(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm1x-clear-key(8)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm1x-clear-key</code> - <span class="man-whatis">rewrap ZFS dataset key in passsword and clear tzpfms TPM1.X metadata</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm1x-clear-key</code> <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM1.X</em> will:</p>
<ol>
<li>perform 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=passphrase dataset</strong>,</li>
<li>remove the <code>xyz.nabijaczleweli:tzpfms.{backend,key}</code> properties from <code>dataset</code>.</li>
</ol>
<p>See <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> for a detailed description.</p>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite always connects to a local <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> process (at <code>localhost:30003</code>).</p>
<p>The TrouSerS <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> daemon will try <code>/dev/tpm0</code>, then <code>/udev/tpm0</code>, then <code>/dev/tpm</code>;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.</p>
<h3 id="See-also">See also</h3>
<p>The TrouSerS project page at <a href="https://sourceforge.net/projects/trousers" data-bare-link="true">https://sourceforge.net/projects/trousers</a>.</p>
<p>The TPM 1.2 main specification index at &lt;<a href="https://trustedcomputinggroup.org/resource/tpm-main-specification" data-bare-link="true">https://trustedcomputinggroup.org/resource/tpm-main-specification</a>&gt;.</p>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by наб &lt;<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>&gt;</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>&lt;<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<p>&lt;<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>&gt;, archived at &lt;<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p>&lt;<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<ol class='man-decor man-foot man foot'>
<li class='tl'>tzpfms developers</li>
<li class='tc'>October 2020</li>
<li class='tr'>zfs-tpm1x-clear-key(8)</li>
</ol>
</div>
</body>
</html>

59
zfs-tpm1x-clear-key.8.html_fragment Normal file
View File

@ -0,0 +1,59 @@
<div class='mp'>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm1x-clear-key</code> - <span class="man-whatis">rewrap ZFS dataset key in passsword and clear tzpfms TPM1.X metadata</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm1x-clear-key</code> <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><span class="man-ref">zfs-tpm1x-clear-key<span class="s">(8)</span></span>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM1.X</em> will:</p>
<ol>
<li>perform 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=passphrase dataset</strong>,</li>
<li>remove the <code>xyz.nabijaczleweli:tzpfms.{backend,key}</code> properties from <code>dataset</code>.</li>
</ol>
<p>See <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> for a detailed description.</p>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite always connects to a local <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> process (at <code>localhost:30003</code>).</p>
<p>The TrouSerS <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> daemon will try <code>/dev/tpm0</code>, then <code>/udev/tpm0</code>, then <code>/dev/tpm</code>;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.</p>
<h3 id="See-also">See also</h3>
<p>The TrouSerS project page at <a href="https://sourceforge.net/projects/trousers" data-bare-link="true">https://sourceforge.net/projects/trousers</a>.</p>
<p>The TPM 1.2 main specification index at &lt;<a href="https://trustedcomputinggroup.org/resource/tpm-main-specification" data-bare-link="true">https://trustedcomputinggroup.org/resource/tpm-main-specification</a>&gt;.</p>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by наб &lt;<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>&gt;</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>&lt;<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<p>&lt;<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>&gt;, archived at &lt;<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p>&lt;<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
</div>

51
zfs-tpm1x-clear-key.md Normal file
View File

@ -0,0 +1,51 @@
zfs-tpm1x-clear-key(8) -- rewrap ZFS dataset key in passsword and clear tzpfms TPM1.X metadata
==============================================================================================
## SYNOPSIS
`zfs-tpm1x-clear-key` <dataset>
## DESCRIPTION
zfs-tpm1x-clear-key(8), after verifying that `dataset` was encrypted with tzpfms backend *TPM1.X* will:
1. perform the equivalent of **zfs(8) change-key -o keylocation=prompt -o keyformat=passphrase dataset**,
2. remove the `xyz.nabijaczleweli:tzpfms.{backend,key}` properties from `dataset`.
See zfs-tpm1x-change-key(8) for a detailed description.
## TPM1.X back-end configuration
### TPM selection
The tzpfms suite always connects to a local tcsd(8) process (at `localhost:30003`).
The TrouSerS tcsd(8) daemon will try `/dev/tpm0`, then `/udev/tpm0`, then `/dev/tpm`;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.
### See also
The TrouSerS project page at <https://sourceforge.net/projects/trousers>.
The TPM 1.2 main specification index at &lt;<https://trustedcomputinggroup.org/resource/tpm-main-specification>&gt;.
## AUTHOR
Written by наб &lt;<nabijaczleweli@nabijaczleweli.xyz>&gt;
## SPECIAL THANKS
To all who support further development, in particular:
* ThePhD
* Embark Studios
## REPORTING BUGS
&lt;<https://todo.sr.ht/~nabijaczleweli/tzpfms>&gt;
&lt;<mailto:~nabijaczleweli/tzpfms@lists.sr.ht>&gt;, archived at &lt;<https://lists.sr.ht/~nabijaczleweli/tzpfms>&gt;
## SEE ALSO
&lt;<https://git.sr.ht/~nabijaczleweli/tzpfms>&gt;

41
zfs-tpm1x-load-key.8 Normal file
View File

@ -0,0 +1,41 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM1X\-LOAD\-KEY" "8" "October 2020" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm1x\-load\-key\fR \- load tzpfms TPM1\.X\-encrypted ZFS dataset key
.SH "SYNOPSIS"
\fBzfs\-tpm1x\-load\-key\fR [\-n] \fIdataset\fR
.SH "DESCRIPTION"
zfs\-tpm1x\-load\-key(8), after verifying that \fBdataset\fR was encrypted with tzpfms backend \fITPM1\.X\fR will unseal the key and load it into \fBdataset\fR\.
.P
The user is prompted for, first, the SRK passphrase, set when taking ownership, if it\'s not "well\-known" (all zeroes), then the additional passphrase set when creating the key, if it was provided\.
.P
See zfs\-tpm1x\-change\-key(8) for a detailed description\.
.SH "OPTIONS"
.TP
\fB\-n\fR
Do a no\-op/dry run, can be used even if the key is already loaded\. Equivalent to \fBzfs(8) load\-key\fR\'s \fB\-n\fR option\.
.SH "TPM1\.X back\-end configuration"
.SS "TPM selection"
The tzpfms suite always connects to a local tcsd(8) process (at \fBlocalhost:30003\fR)\.
.P
The TrouSerS tcsd(8) daemon will try \fB/dev/tpm0\fR, then \fB/udev/tpm0\fR, then \fB/dev/tpm\fR; by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected\.
.SS "See also"
The TrouSerS project page at \fIhttps://sourceforge\.net/projects/trousers\fR\.
.P
The TPM 1\.2 main specification index at <\fIhttps://trustedcomputinggroup\.org/resource/tpm\-main\-specification\fR>\.
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
To all who support further development, in particular:
.IP "\[ci]" 4
ThePhD
.IP "\[ci]" 4
Embark Studios
.IP "" 0
.SH "REPORTING BUGS"
<\fIhttps://todo\.sr\.ht/~nabijaczleweli/tzpfms\fR>
.P
<\fI~nabijaczleweli/tzpfms@lists\.sr\.ht\fR>, archived at <\fIhttps://lists\.sr\.ht/~nabijaczleweli/tzpfms\fR>
.SH "SEE ALSO"
<\fIhttps://git\.sr\.ht/~nabijaczleweli/tzpfms\fR>

145
zfs-tpm1x-load-key.8.html Normal file
View File

@ -0,0 +1,145 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html;charset=utf8'>
<meta name='generator' content='Ronn-NG/v0.9.1 (http://github.com/apjanke/ronn-ng/tree/0.9.1)'>
<title>zfs-tpm1x-load-key(8) - load tzpfms TPM1.X-encrypted ZFS dataset key</title>
<style type='text/css' media='all'>
/* style: man */
body#manpage {margin:0}
.mp {max-width:100ex;padding:0 9ex 1ex 4ex}
.mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
.mp h2 {margin:10px 0 0 0}
.mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
.mp h3 {margin:0 0 0 4ex}
.mp dt {margin:0;clear:left}
.mp dt.flush {float:left;width:8ex}
.mp dd {margin:0 0 0 9ex}
.mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
.mp pre {margin-bottom:20px}
.mp pre+h2,.mp pre+h3 {margin-top:22px}
.mp h2+pre,.mp h3+pre {margin-top:5px}
.mp img {display:block;margin:auto}
.mp h1.man-title {display:none}
.mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
.mp h2 {font-size:16px;line-height:1.25}
.mp h1 {font-size:20px;line-height:2}
.mp {text-align:justify;background:#fff}
.mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
.mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
.mp u {text-decoration:underline}
.mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
.mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
.mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
.mp b.man-ref {font-weight:normal;color:#434241}
.mp pre {padding:0 4ex}
.mp pre code {font-weight:normal;color:#434241}
.mp h2+pre,h3+pre {padding-left:0}
ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
ol.man-decor {width:100%}
ol.man-decor li.tl {text-align:left}
ol.man-decor li.tc {text-align:center;letter-spacing:4px}
ol.man-decor li.tr {text-align:right;float:right}
</style>
</head>
<!--
The following styles are deprecated and will be removed at some point:
div#man, div#man ol.man, div#man ol.head, div#man ol.man.
The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
.man-navigation should be used instead.
-->
<body id='manpage'>
<div class='mp' id='man'>
<div class='man-navigation' style='display:none'>
<a href="#NAME">NAME</a>
<a href="#SYNOPSIS">SYNOPSIS</a>
<a href="#DESCRIPTION">DESCRIPTION</a>
<a href="#OPTIONS">OPTIONS</a>
<a href="#TPM1-X-BACK-END-CONFIGURATION">TPM1.X back-end configuration</a>
<a href="#AUTHOR">AUTHOR</a>
<a href="#SPECIAL-THANKS">SPECIAL THANKS</a>
<a href="#REPORTING-BUGS">REPORTING BUGS</a>
<a href="#SEE-ALSO">SEE ALSO</a>
</div>
<ol class='man-decor man-head man head'>
<li class='tl'>zfs-tpm1x-load-key(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm1x-load-key(8)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm1x-load-key</code> - <span class="man-whatis">load tzpfms TPM1.X-encrypted ZFS dataset key</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm1x-load-key</code> [-n] <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><span class="man-ref">zfs-tpm1x-load-key<span class="s">(8)</span></span>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM1.X</em> will unseal the key and load it into <code>dataset</code>.</p>
<p>The user is prompted for, first, the SRK passphrase, set when taking ownership, if it's not "well-known" (all zeroes),
then the additional passphrase set when creating the key, if it was provided.</p>
<p>See <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> for a detailed description.</p>
<h2 id="OPTIONS">OPTIONS</h2>
<dl>
<dt><code>-n</code></dt>
<dd>Do a no-op/dry run, can be used even if the key is already loaded. Equivalent to <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</strong>'s <code>-n</code> option.</dd>
</dl>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite always connects to a local <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> process (at <code>localhost:30003</code>).</p>
<p>The TrouSerS <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> daemon will try <code>/dev/tpm0</code>, then <code>/udev/tpm0</code>, then <code>/dev/tpm</code>;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.</p>
<h3 id="See-also">See also</h3>
<p>The TrouSerS project page at <a href="https://sourceforge.net/projects/trousers" data-bare-link="true">https://sourceforge.net/projects/trousers</a>.</p>
<p>The TPM 1.2 main specification index at &lt;<a href="https://trustedcomputinggroup.org/resource/tpm-main-specification" data-bare-link="true">https://trustedcomputinggroup.org/resource/tpm-main-specification</a>&gt;.</p>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by наб &lt;<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>&gt;</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>&lt;<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<p>&lt;<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>&gt;, archived at &lt;<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p>&lt;<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<ol class='man-decor man-foot man foot'>
<li class='tl'>tzpfms developers</li>
<li class='tc'>October 2020</li>
<li class='tr'>zfs-tpm1x-load-key(8)</li>
</ol>
</div>
</body>
</html>

64
zfs-tpm1x-load-key.8.html_fragment Normal file
View File

@ -0,0 +1,64 @@
<div class='mp'>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm1x-load-key</code> - <span class="man-whatis">load tzpfms TPM1.X-encrypted ZFS dataset key</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm1x-load-key</code> [-n] <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><span class="man-ref">zfs-tpm1x-load-key<span class="s">(8)</span></span>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM1.X</em> will unseal the key and load it into <code>dataset</code>.</p>
<p>The user is prompted for, first, the SRK passphrase, set when taking ownership, if it's not "well-known" (all zeroes),
then the additional passphrase set when creating the key, if it was provided.</p>
<p>See <span class="man-ref">zfs-tpm1x-change-key<span class="s">(8)</span></span> for a detailed description.</p>
<h2 id="OPTIONS">OPTIONS</h2>
<dl>
<dt><code>-n</code></dt>
<dd>Do a no-op/dry run, can be used even if the key is already loaded. Equivalent to <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</strong>'s <code>-n</code> option.</dd>
</dl>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite always connects to a local <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> process (at <code>localhost:30003</code>).</p>
<p>The TrouSerS <a class="man-ref" href="https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html">tcsd<span class="s">(8)</span></a> daemon will try <code>/dev/tpm0</code>, then <code>/udev/tpm0</code>, then <code>/dev/tpm</code>;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.</p>
<h3 id="See-also">See also</h3>
<p>The TrouSerS project page at <a href="https://sourceforge.net/projects/trousers" data-bare-link="true">https://sourceforge.net/projects/trousers</a>.</p>
<p>The TPM 1.2 main specification index at &lt;<a href="https://trustedcomputinggroup.org/resource/tpm-main-specification" data-bare-link="true">https://trustedcomputinggroup.org/resource/tpm-main-specification</a>&gt;.</p>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by наб &lt;<a href="mailto:nabijaczleweli@nabijaczleweli.xyz" data-bare-link="true">nabijaczleweli@nabijaczleweli.xyz</a>&gt;</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>&lt;<a href="https://todo.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://todo.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<p>&lt;<a href="mailto:~nabijaczleweli/tzpfms@lists.sr.ht" data-bare-link="true">~nabijaczleweli/tzpfms@lists.sr.ht</a>&gt;, archived at &lt;<a href="https://lists.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://lists.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p>&lt;<a href="https://git.sr.ht/~nabijaczleweli/tzpfms" data-bare-link="true">https://git.sr.ht/~nabijaczleweli/tzpfms</a>&gt;</p>
</div>

56
zfs-tpm1x-load-key.md Normal file
View File

@ -0,0 +1,56 @@
zfs-tpm1x-load-key(8) -- load tzpfms TPM1.X-encrypted ZFS dataset key
=====================================================================
## SYNOPSIS
`zfs-tpm1x-load-key` [-n] <dataset>
## DESCRIPTION
zfs-tpm1x-load-key(8), after verifying that `dataset` was encrypted with tzpfms backend *TPM1.X* will unseal the key and load it into `dataset`.
The user is prompted for, first, the SRK passphrase, set when taking ownership, if it's not "well-known" (all zeroes),
then the additional passphrase set when creating the key, if it was provided.
See zfs-tpm1x-change-key(8) for a detailed description.
## OPTIONS
* `-n`:
Do a no-op/dry run, can be used even if the key is already loaded. Equivalent to **zfs(8) load-key**'s `-n` option.
## TPM1.X back-end configuration
### TPM selection
The tzpfms suite always connects to a local tcsd(8) process (at `localhost:30003`).
The TrouSerS tcsd(8) daemon will try `/dev/tpm0`, then `/udev/tpm0`, then `/dev/tpm`;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.
### See also
The TrouSerS project page at <https://sourceforge.net/projects/trousers>.
The TPM 1.2 main specification index at &lt;<https://trustedcomputinggroup.org/resource/tpm-main-specification>&gt;.
## AUTHOR
Written by наб &lt;<nabijaczleweli@nabijaczleweli.xyz>&gt;
## SPECIAL THANKS
To all who support further development, in particular:
* ThePhD
* Embark Studios
## REPORTING BUGS
&lt;<https://todo.sr.ht/~nabijaczleweli/tzpfms>&gt;
&lt;<mailto:~nabijaczleweli/tzpfms@lists.sr.ht>&gt;, archived at &lt;<https://lists.sr.ht/~nabijaczleweli/tzpfms>&gt;
## SEE ALSO
&lt;<https://git.sr.ht/~nabijaczleweli/tzpfms>&gt;