third-party-mirrors/tzpfms
1
0
Fork 0
mirror of https://git.sr.ht/~nabijaczleweli/tzpfms synced 2025-06-08 22:42:05 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Manpage update by job 608529

Browse Source
This commit is contained in:
наб autouploader 2021-10-15 21:34:57 +00:00
parent ef49e75498
commit fc4094f424
30 changed files with 1958 additions and 2509 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
index.txt
View File

@ -1,13 +0,0 @@
zfs-tpm2-change-key(8) zfs-tpm2-change-key.8.ronn
zfs-tpm2-load-key(8) zfs-tpm2-load-key.8.ronn
zfs-tpm2-clear-key(8) zfs-tpm2-clear-key.8.ronn
zfs-tpm1x-change-key(8) zfs-tpm1x-change-key.8.ronn
zfs-tpm1x-load-key(8) zfs-tpm1x-load-key.8.ronn
zfs-tpm1x-clear-key(8) zfs-tpm1x-clear-key.8.ronn
zfs-tpm-list(8) zfs-tpm-list.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

297
style.css Normal file
View File

@ -0,0 +1,297 @@
/* $OpenBSD: mandoc.css,v 1.33 2019/06/02 16:50:46 schwarze Exp $ */
/*
* Standard style sheet for mandoc(1) -Thtml and man.cgi(8).
*
* Written by Ingo Schwarze <schwarze@openbsd.org>.
* I place this file into the public domain.
* Permission to use, copy, modify, and distribute it for any purpose
* with or without fee is hereby granted, without any conditions.
*/
/* Tooltips removed. */
/* Global defaults. */
html { max-width: 65em;
--bg: #FFFFFF;
--fg: #000000; }
body { background: var(--bg);
color: var(--fg);
font-family: Helvetica,Arial,sans-serif; }
h1 { font-size: 110%; }
table { margin-top: 0em;
margin-bottom: 0em;
border-collapse: collapse; }
/* Some browsers set border-color in a browser style for tbody,
* but not for table, resulting in inconsistent border styling. */
tbody { border-color: inherit; }
tr { border-color: inherit; }
td { vertical-align: top;
padding-left: 0.2em;
padding-right: 0.2em;
border-color: inherit; }
ul, ol, dl { margin-top: 0em;
margin-bottom: 0em; }
li, dt { margin-top: 1em; }
.permalink { border-bottom: thin dotted;
color: inherit;
font: inherit;
text-decoration: inherit; }
* { clear: both }
/* Search form and search results. */
fieldset { border: thin solid silver;
border-radius: 1em;
text-align: center; }
input[name=expr] {
width: 25%; }
table.results { margin-top: 1em;
margin-left: 2em;
font-size: smaller; }
/* Header and footer lines. */
table.head { width: 100%;
border-bottom: 1px dotted #808080;
margin-bottom: 1em;
font-size: smaller; }
td.head-vol { text-align: center; }
td.head-rtitle {
text-align: right; }
table.foot { width: 100%;
border-top: 1px dotted #808080;
margin-top: 1em;
font-size: smaller; }
td.foot-os { text-align: right; }
/* Sections and paragraphs. */
.manual-text {
margin-left: 3.8em; }
.Nd { }
section.Sh { }
h1.Sh { margin-top: 1.2em;
margin-bottom: 0.6em;
margin-left: -3.2em; }
section.Ss { }
h2.Ss { margin-top: 1.2em;
margin-bottom: 0.6em;
margin-left: -1.2em;
font-size: 105%; }
.Pp { margin: 0.6em 0em; }
.Sx { }
.Xr { }
/* Displays and lists. */
.Bd { }
.Bd-indent { margin-left: 3.8em; }
.Bl-bullet { list-style-type: disc;
padding-left: 1em; }
.Bl-bullet > li { }
.Bl-dash { list-style-type: none;
padding-left: 0em; }
.Bl-dash > li:before {
content: "\2014 "; }
.Bl-item { list-style-type: none;
padding-left: 0em; }
.Bl-item > li { }
.Bl-compact > li {
margin-top: 0em; }
.Bl-enum { padding-left: 2em; }
.Bl-enum > li { }
.Bl-compact > li {
margin-top: 0em; }
.Bl-diag { }
.Bl-diag > dt {
font-style: normal;
font-weight: bold; }
.Bl-diag > dd {
margin-left: 0em; }
.Bl-hang { }
.Bl-hang > dt { }
.Bl-hang > dd {
margin-left: 5.5em; }
.Bl-inset { }
.Bl-inset > dt { }
.Bl-inset > dd {
margin-left: 0em; }
.Bl-ohang { }
.Bl-ohang > dt { }
.Bl-ohang > dd {
margin-left: 0em; }
.Bl-tag { margin-top: 0.6em;
margin-left: 5.5em; }
.Bl-tag > dt {
float: left;
margin-top: 0em;
margin-left: -5.5em;
padding-right: 0.5em;
vertical-align: top; }
.Bl-tag > dd {
clear: right;
column-count: 1; /* Force block formatting context. */
width: 100%;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0.6em;
vertical-align: top; }
.Bl-compact { margin-top: 0em; }
.Bl-compact > dd {
margin-bottom: 0em; }
.Bl-compact > dt {
margin-top: 0em; }
.Bl-column { }
.Bl-column > tbody > tr { }
.Bl-column > tbody > tr > td {
margin-top: 1em; }
.Bl-compact > tbody > tr > td {
margin-top: 0em; }
.Rs { font-style: normal;
font-weight: normal; }
.RsA { }
.RsB { font-style: italic;
font-weight: normal; }
.RsC { }
.RsD { }
.RsI { font-style: italic;
font-weight: normal; }
.RsJ { font-style: italic;
font-weight: normal; }
.RsN { }
.RsO { }
.RsP { }
.RsQ { }
.RsR { }
.RsT { text-decoration: underline; }
.RsU { }
.RsV { }
.eqn { }
.tbl td { vertical-align: middle; }
.HP { margin-left: 3.8em;
text-indent: -3.8em; }
/* Semantic markup for command line utilities. */
table.Nm { }
code.Nm { font-style: normal;
font-weight: bold;
font-family: monospace; }
.Fl { font-style: normal;
font-weight: bold;
font-family: monospace; }
.Cm { font-style: normal;
font-weight: bold;
font-family: monospace; }
.Ar { font-style: italic;
font-weight: normal;
font-family: monospace; }
.Op { display: inline; }
.Ic { font-style: normal;
font-weight: bold;
font-family: monospace; }
.Ev { font-style: normal;
font-weight: normal;
font-family: monospace; }
.Pa { font-style: italic;
font-weight: normal; }
/* Semantic markup for function libraries. */
.Lb { }
code.In { font-style: normal;
font-weight: bold;
font-family: inherit; }
a.In { }
.Fd { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Ft { font-style: italic;
font-weight: normal; }
.Fn { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Fa { font-style: italic;
font-weight: normal; }
.Vt { font-style: italic;
font-weight: normal; }
.Va { font-style: italic;
font-weight: normal; }
.Dv { font-style: normal;
font-weight: normal;
font-family: monospace; }
.Er { font-style: normal;
font-weight: normal;
font-family: monospace; }
/* Various semantic markup. */
.An { }
.Lk { }
.Mt { }
.Cd { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Ad { font-style: italic;
font-weight: normal; }
.Ms { font-style: normal;
font-weight: bold; }
.St { }
.Ux { }
/* Physical markup. */
.Bf { display: inline; }
.No { font-style: normal;
font-weight: normal; }
.Em { font-style: italic;
font-weight: normal; }
.Sy { font-style: normal;
font-weight: bold; }
.Li { font-style: normal;
font-weight: normal;
font-family: monospace; }
/* Tooltip support. */
h1.Sh, h2.Ss { position: relative; }
.Li, .An, .Ar, .Cd, .Cm, .Dv, .Em, .Er, .Ev, .Fa, .Fd, .Fl, .Fn, .Ft,
.Ic, code.In, .Lb, .Lk, .Ms, .Mt, .Nd, code.Nm, .Pa, .Rs,
.St, .Sx, .Sy, .Va, .Vt, .Xr {
display: inline-block;
position: relative; }
/* Overrides to avoid excessive margins on small devices. */
@media (max-width: 37.5em) {
.manual-text {
margin-left: 0.5em; }
h1.Sh, h2.Ss { margin-left: 0em; }
.Bd-indent { margin-left: 2em; }
.Bl-hang > dd {
margin-left: 2em; }
.Bl-tag { margin-left: 2em; }
.Bl-tag > dt {
margin-left: -2em; }
.HP { margin-left: 2em;
text-indent: -2em; }
}
/* Overrides for a dark color scheme for accessibility. */
@media (prefers-color-scheme: dark) {
html { --bg: #1E1F21;
--fg: #EEEFF1; }
:link { color: #BAD7FF; }
:visited { color: #F6BAFF; }
}

209
zfs-tpm-list.8
View File

@ -1,88 +1,135 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM\-LIST" "8" "January 2021" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm\-list\fR \- print dataset tzpfms metadata
.SH "SYNOPSIS"
\fBzfs\-tpm\-list\fR [\-H] [\-r|\-d \fIdepth\fR] [\-a|\-b \fIback\-end\fR] [\-u|\-l] [\fIfilesystem\fR|\fIvolume\fR]…
.SH "DESCRIPTION"
zfs\-tpm\-list(8) lists the following properties on encryption roots:
.IP "\[ci]" 4
\fBname\fR,
.IP "\[ci]" 4
\fBback\-end\fR: the tzpfms back\-end (e\.g\. "TPM2" for zfs\-tpm2\-change\-key(8) or "TPM1\.X" for zfs\-tpm1x\-change\-key(8)), or "\-" if none is configured,
.IP "\[ci]" 4
\fBkeystatus\fR: "available" or "unavailable",
.IP "\[ci]" 4
\fBcoherent\fR: "yes" if either both \fBxyz\.nabijaczleweli:tzpfms\.backend\fR and \fBxyz\.nabijaczleweli:tzpfms\.key\fR are present or missing, "no" otherwise\.
.IP "" 0
.P
Incoherent datasets require immediate operator attention, with either the appropriate zfs\-tpm*\-clear\-key program or zfs(8) change\-key and zfs(8) inherit \(em if the key becomes unloaded, they will require restoration from back\-up\. However, they should never occur, unless something went terribly wrong with the dataset properties\.
.P
If no datasets are specified, lists all matching encryption roots\. The default filter is to list all roots managed by tzpfms\. The \fB\-a\fR and \fB\-b\fR OPTIONS \fI\fR can be used to either list all roots or only ones backed by a particular end, respectively\.
.SH "OPTIONS"
.TP
\fB\-H\fR
Used for scripting mode\. Do not print headers and separate fields by a single tab instead of arbitrary white space\.
.TP
\fB\-r\fR
Recurse into all descendant datasets\. Default if no datasets listed on the command\-line\.
.TP
\fB\-d\fR \fIdepth\fR
Recurse at most \fIdepth\fR datasets deep\. Defaults to zero if datasets were listed on the command\-line\.
.TP
\fB\-a\fR
List all encryption roots, even ones not managed by tzpfms\.
.TP
\fB\-b\fR \fIback\-end\fR
List only encryption roots with tzpfms back\-end \fIback\-end\fR\.
.TP
\fB\-l\fR
List only encryption roots whose keys are available\.
.TP
\fB\-u\fR
List only encryption roots whose keys are unavailable\.
.SH "EXAMPLES"
.nf
$ zfs\-tpm\-list
NAME BACK\-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/enc TPM1\.X available yes
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM-LIST 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm-list
.Nd print dataset tzpfms metadata
.Sh SYNOPSIS
.Nm
.Op Fl H
.Op Fl r Ns \&| Ns Fl d Ar depth
.Op Fl a Ns \&| Ns Fl b Ar back-end
.Op Fl u Ns \&| Ns Fl l
.Oo Ar filesystem Ns \&| Ns Ar volume Oc Ns …
.
.Sh DESCRIPTION
Lists the following properties on encryption roots:
.Bl -tag -compact -offset Ds -width "keystatus"
.It Li name
.It Li back-end
the
.Nm tzpfms
back-end
.Pq e.g. Sy TPM2 No for Xr zfs-tpm2-change-key 8 or Sy TPM1.X No for Xr zfs-tpm1x-change-key 8 ,
or
.Qq Sy -
if none is configured
.It Li keystatus
.Sy available
or
.Sy unavailable
.It Li coherent
.Sy yes
if either both
.Li xyz.nabijaczleweli:tzpfms.backend
and
.Li xyz.nabijaczleweli:tzpfms.key
are present or missing,
.Sy no
otherwise
.El
.Pp
Incoherent datasets require immediate operator attention, with either the appropriate
.Nm zfs-tpm*-clear-key
program or
.Nm zfs Cm change-key
and
.Nm zfs Cm inherit
\(em if the key becomes unloaded, they will require restoration from back-up.
However, they should never occur, unless something went terribly wrong with the dataset properties.
.Pp
If no datasets are specified, lists all matching encryption roots.
The default filter is to list all roots managed by
.Nm tzpfms .
.Fl ab
can be used to either list all roots or only ones backed by a particular end, respectively.
.
.Sh OPTIONS
.Bl -tag -compact -width "-b back-end"
.It Fl H
Scripting mode \(em do not print headers and separate fields by a single tab instead of columnating with spaces.
.Pp
.It Fl r
Recurse into all descendants of specified datasets.
.It Fl d Ar depth
Recurse at most
.Ar depth
datasets deep.
Default:
.Sy 0 .
.Pp
.It Fl a
List all encryption roots, even ones not managed by
.Nm tzpfms .
.It Fl b Ar back-end
List only encryption roots with
.Ar tzpfms
back-end
.Ar back-end .
.Pp
.It Fl l
List only encryption roots whose keys are available.
.It Fl y
List only encryption roots whose keys are unavailable.
.El
.
.Sh EXAMPLES
.Bd -literal -compact
.Li $ Nm
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/enc TPM1.X available yes
$ zfs\-tpm\-list \-ad0
NAME BACK\-END KEYSTATUS COHERENT
awa \- available yes
.Li $ Nm Fl ad0
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
$ zfs\-tpm\-list \-b TPM2
NAME BACK\-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
.Li $ Nm Fl b Sy TPM2
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
$ zfs\-tpm\-list \-ra owo
NAME BACK\-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/vtnc \- available yes
owo/v nc \- available yes
owo/enc TPM1\.X available yes
.Li $ Nm Fl ra Ar owo
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
$ zfs\-tpm\-list \-al
NAME BACK\-END KEYSTATUS COHERENT
awa \- available yes
owo/vtnc \- available yes
owo/v nc \- available yes
owo/enc TPM1\.X available yes
.fi
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
.Li $ Nm Fl al
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
.Ed
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

338
zfs-tpm-list.8.html
View File

@ -1,191 +1,175 @@
<!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-tpm-list(8) - print dataset tzpfms 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>
<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-TPM-LIST(8)</title>
</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="#EXAMPLES">EXAMPLES</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-tpm-list(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm-list(8)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm-list</code> - <span class="man-whatis">print dataset tzpfms metadata</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm-list</code> [-H] [-r|-d <em>depth</em>] [-a|-b <em>back-end</em>] [-u|-l] [<em>filesystem</em>|<em>volume</em>]…</p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><a class="man-ref" href="zfs-tpm-list.8.html">zfs-tpm-list<span class="s">(8)</span></a> lists the following properties on encryption roots:</p>
<ul>
<li>
<code>name</code>,</li>
<li>
<code>back-end</code>: the tzpfms back-end (e.g. "TPM2" for <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> or "TPM1.X" for <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a>),
or "-" if none is configured,</li>
<li>
<code>keystatus</code>: "available" or "unavailable",</li>
<li>
<code>coherent</code>: "yes" if either both <code>xyz.nabijaczleweli:tzpfms.backend</code> and <code>xyz.nabijaczleweli:tzpfms.key</code> are present or missing, "no" otherwise.</li>
</ul>
<p>Incoherent datasets require immediate operator attention, with either the appropriate zfs-tpm*-clear-key program or <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 and <a class="man-ref" href="https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html">zfs<span class="s">(8)</span></a> inherit —
if the key becomes unloaded, they will require restoration from back-up.
However, they should never occur, unless something went terribly wrong with the dataset properties.</p>
<p>If no datasets are specified, lists all matching encryption roots.
The default filter is to list all roots managed by tzpfms.
The <code>-a</code> and <code>-b</code> <a href="">OPTIONS</a> can be used to either list all roots or only ones backed by a particular end, respectively.</p>
<h2 id="OPTIONS">OPTIONS</h2>
<dl>
<dt><code>-H</code></dt>
<dd>Used for scripting mode. Do not print headers and separate fields by a single tab instead of arbitrary white space.</dd>
<dt><code>-r</code></dt>
<dd>Recurse into all descendant datasets. Default if no datasets listed on the command-line.</dd>
<dt>
<code>-d</code> <em>depth</em>
</dt>
<dd>Recurse at most <em>depth</em> datasets deep. Defaults to zero if datasets were listed on the command-line.</dd>
<dt><code>-a</code></dt>
<dd>List all encryption roots, even ones not managed by tzpfms.</dd>
<dt>
<code>-b</code> <em>back-end</em>
</dt>
<dd>List only encryption roots with tzpfms back-end <em>back-end</em>.</dd>
<dt><code>-l</code></dt>
<dd>List only encryption roots whose keys are available.</dd>
<dt><code>-u</code></dt>
<dd>List only encryption roots whose keys are unavailable.</dd>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM-LIST(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM-LIST(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-tpm-list</code> &#x2014;
<span class="Nd">print dataset tzpfms metadata</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-tpm-list</code></td>
<td>[<code class="Fl">-H</code>]
[<code class="Fl">-r</code>|<code class="Fl">-d</code>
<var class="Ar">depth</var>]
[<code class="Fl">-a</code>|<code class="Fl">-b</code>
<var class="Ar">back-end</var>]
[<code class="Fl">-u</code>|<code class="Fl">-l</code>]
[<var class="Ar">filesystem</var>|<var class="Ar">volume</var>]&#x2026;</td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">Lists the following properties on encryption roots:</p>
<div class="Bd-indent">
<dl class="Bl-tag Bl-compact">
<dt id="name"><a class="permalink" href="#name"><code class="Li">name</code></a></dt>
<dd style="width: auto;">&#x00A0;</dd>
<dt id="back-end"><a class="permalink" href="#back-end"><code class="Li">back-end</code></a></dt>
<dd>the <code class="Nm">tzpfms</code> back-end (e.g. <b class="Sy">TPM2</b>
<span class="No">for</span>
<a class="Xr" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key(8)</a>
or
<a class="permalink" href="#TPM1.X"><b class="Sy" id="TPM1.X">TPM1.X</b></a>
<span class="No">for</span>
<a class="Xr" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key(8)</a>),
or &quot;<b class="Sy">-</b>&quot; if none is configured</dd>
<dt id="keystatus"><a class="permalink" href="#keystatus"><code class="Li">keystatus</code></a></dt>
<dd><a class="permalink" href="#available"><b class="Sy" id="available">available</b></a>
or
<a class="permalink" href="#unavailable"><b class="Sy" id="unavailable">unavailable</b></a></dd>
<dt id="coherent"><a class="permalink" href="#coherent"><code class="Li">coherent</code></a></dt>
<dd><a class="permalink" href="#yes"><b class="Sy" id="yes">yes</b></a> if
either both <code class="Li">xyz.nabijaczleweli:tzpfms.backend</code> and
<code class="Li">xyz.nabijaczleweli:tzpfms.key</code> are present or
missing, <a class="permalink" href="#no"><b class="Sy" id="no">no</b></a>
otherwise</dd>
</dl>
</div>
<p class="Pp">Incoherent datasets require immediate operator attention, with
either the appropriate <code class="Nm">zfs-tpm*-clear-key</code> program or
<code class="Nm">zfs</code> <code class="Cm">change-key</code> and
<code class="Nm">zfs</code> <code class="Cm">inherit</code> &#x2014; if the
key becomes unloaded, they will require restoration from back-up. However,
they should never occur, unless something went terribly wrong with the
dataset properties.</p>
<p class="Pp">If no datasets are specified, lists all matching encryption roots.
The default filter is to list all roots managed by
<code class="Nm">tzpfms</code>. <code class="Fl">-ab</code> can be used to
either list all roots or only ones backed by a particular end,
respectively.</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="H"><a class="permalink" href="#H"><code class="Fl">-H</code></a></dt>
<dd>Scripting mode &#x2014; do not print headers and separate fields by a
single tab instead of columnating with spaces.
<p class="Pp"></p>
</dd>
<dt id="r"><a class="permalink" href="#r"><code class="Fl">-r</code></a></dt>
<dd>Recurse into all descendants of specified datasets.</dd>
<dt id="d"><a class="permalink" href="#d"><code class="Fl">-d</code></a>
<var class="Ar">depth</var></dt>
<dd>Recurse at most <var class="Ar">depth</var> datasets deep. Default:
<a class="permalink" href="#0"><b class="Sy" id="0">0</b></a>.
<p class="Pp"></p>
</dd>
<dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a></dt>
<dd>List all encryption roots, even ones not managed by
<code class="Nm">tzpfms</code>.</dd>
<dt id="b"><a class="permalink" href="#b"><code class="Fl">-b</code></a>
<var class="Ar">back-end</var></dt>
<dd>List only encryption roots with <var class="Ar">tzpfms</var> back-end
<var class="Ar">back-end</var>.
<p class="Pp"></p>
</dd>
<dt id="l"><a class="permalink" href="#l"><code class="Fl">-l</code></a></dt>
<dd>List only encryption roots whose keys are available.</dd>
<dt id="y"><a class="permalink" href="#y"><code class="Fl">-y</code></a></dt>
<dd>List only encryption roots whose keys are unavailable.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<div class="Bd Li">
<pre><code class="Li">$</code> <code class="Nm"></code></pre>
zfs-tpm-list
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/enc TPM1.X available yes
<h2 id="EXAMPLES">EXAMPLES</h2>
<code class="Li">$</code> <code class="Nm"></code>zfs-tpm-list
<code class="Fl">-ad0</code>
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
<pre><code>$ zfs-tpm-list
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/enc TPM1.X available yes
<code class="Li">$</code> <code class="Nm"></code>zfs-tpm-list
<code class="Fl">-b</code> <b class="Sy">TPM2</b>
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
$ zfs-tpm-list -ad0
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
<code class="Li">$</code> <code class="Nm"></code>zfs-tpm-list
<code class="Fl">-ra</code> <var class="Ar">owo</var>
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
$ zfs-tpm-list -b TPM2
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
$ zfs-tpm-list -ra owo
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
$ zfs-tpm-list -al
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
</code></pre>
<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>
<code class="Li">$</code> <code class="Nm"></code>zfs-tpm-list
<code class="Fl">-al</code>
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes</div>
</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>
<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'>January 2021</li>
<li class='tr'>zfs-tpm-list(8)</li>
</ol>
</div>
</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="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>

110
zfs-tpm-list.8.html_fragment
View File

@ -1,110 +0,0 @@
<div class='mp'>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm-list</code> - <span class="man-whatis">print dataset tzpfms metadata</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm-list</code> [-H] [-r|-d <em>depth</em>] [-a|-b <em>back-end</em>] [-u|-l] [<em>filesystem</em>|<em>volume</em>]…</p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><a class="man-ref" href="zfs-tpm-list.8.html">zfs-tpm-list<span class="s">(8)</span></a> lists the following properties on encryption roots:</p>
<ul>
<li>
<code>name</code>,</li>
<li>
<code>back-end</code>: the tzpfms back-end (e.g. "TPM2" for <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> or "TPM1.X" for <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a>),
or "-" if none is configured,</li>
<li>
<code>keystatus</code>: "available" or "unavailable",</li>
<li>
<code>coherent</code>: "yes" if either both <code>xyz.nabijaczleweli:tzpfms.backend</code> and <code>xyz.nabijaczleweli:tzpfms.key</code> are present or missing, "no" otherwise.</li>
</ul>
<p>Incoherent datasets require immediate operator attention, with either the appropriate zfs-tpm*-clear-key program or <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 and <a class="man-ref" href="https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html">zfs<span class="s">(8)</span></a> inherit —
if the key becomes unloaded, they will require restoration from back-up.
However, they should never occur, unless something went terribly wrong with the dataset properties.</p>
<p>If no datasets are specified, lists all matching encryption roots.
The default filter is to list all roots managed by tzpfms.
The <code>-a</code> and <code>-b</code> <a href="">OPTIONS</a> can be used to either list all roots or only ones backed by a particular end, respectively.</p>
<h2 id="OPTIONS">OPTIONS</h2>
<dl>
<dt><code>-H</code></dt>
<dd>Used for scripting mode. Do not print headers and separate fields by a single tab instead of arbitrary white space.</dd>
<dt><code>-r</code></dt>
<dd>Recurse into all descendant datasets. Default if no datasets listed on the command-line.</dd>
<dt>
<code>-d</code> <em>depth</em>
</dt>
<dd>Recurse at most <em>depth</em> datasets deep. Defaults to zero if datasets were listed on the command-line.</dd>
<dt><code>-a</code></dt>
<dd>List all encryption roots, even ones not managed by tzpfms.</dd>
<dt>
<code>-b</code> <em>back-end</em>
</dt>
<dd>List only encryption roots with tzpfms back-end <em>back-end</em>.</dd>
<dt><code>-l</code></dt>
<dd>List only encryption roots whose keys are available.</dd>
<dt><code>-u</code></dt>
<dd>List only encryption roots whose keys are unavailable.</dd>
</dl>
<h2 id="EXAMPLES">EXAMPLES</h2>
<pre><code>$ zfs-tpm-list
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/enc TPM1.X available yes
$ zfs-tpm-list -ad0
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
$ zfs-tpm-list -b TPM2
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
$ zfs-tpm-list -ra owo
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
$ zfs-tpm-list -al
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
</code></pre>
<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>

95
zfs-tpm-list.md
View File

@ -1,95 +0,0 @@
zfs-tpm-list(8) -- print dataset tzpfms metadata
================================================
## SYNOPSIS
`zfs-tpm-list` [-H] [-r\|-d *depth*] [-a\|-b *back-end*] [-u\|-l] [*filesystem*\|*volume*]…
## DESCRIPTION
zfs-tpm-list(8) lists the following properties on encryption roots:
* `name`,
* `back-end`: the tzpfms back-end (e.g. "TPM2" for zfs-tpm2-change-key(8) or "TPM1.X" for zfs-tpm1x-change-key(8)),
or "-" if none is configured,
* `keystatus`: "available" or "unavailable",
* `coherent`: "yes" if either both `xyz.nabijaczleweli:tzpfms.backend` and `xyz.nabijaczleweli:tzpfms.key` are present or missing, "no" otherwise.
Incoherent datasets require immediate operator attention, with either the appropriate zfs-tpm\*-clear-key program or zfs(8) change-key and zfs(8) inherit —
if the key becomes unloaded, they will require restoration from back-up.
However, they should never occur, unless something went terribly wrong with the dataset properties.
If no datasets are specified, lists all matching encryption roots.
The default filter is to list all roots managed by tzpfms.
The `-a` and `-b` [OPTIONS]() can be used to either list all roots or only ones backed by a particular end, respectively.
## OPTIONS
* `-H`:
Used for scripting mode. Do not print headers and separate fields by a single tab instead of arbitrary white space.
* `-r`:
Recurse into all descendant datasets. Default if no datasets listed on the command-line.
* `-d` *depth*:
Recurse at most *depth* datasets deep. Defaults to zero if datasets were listed on the command-line.
* `-a`:
List all encryption roots, even ones not managed by tzpfms.
* `-b` *back-end*:
List only encryption roots with tzpfms back-end *back-end*.
* `-l`:
List only encryption roots whose keys are available.
* `-u`:
List only encryption roots whose keys are unavailable.
## EXAMPLES
$ zfs-tpm-list
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/enc TPM1.X available yes
$ zfs-tpm-list -ad0
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
$ zfs-tpm-list -b TPM2
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
$ zfs-tpm-list -ra owo
NAME BACK-END KEYSTATUS COHERENT
owo/venc TPM2 unavailable yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
$ zfs-tpm-list -al
NAME BACK-END KEYSTATUS COHERENT
awa - available yes
owo/vtnc - available yes
owo/v nc - available yes
owo/enc TPM1.X available yes
## 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;

204
zfs-tpm1x-change-key.8
View File

@ -1,60 +1,150 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM1X\-CHANGE\-KEY" "8" "January 2021" "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; the user is prompted for an optional passphrase to protect the key with, and for the SRK passphrase, set when taking ownership, if it is not "well\-known" (all zeroes)\.
.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; perhaps there should be\.
.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 connects to a local tcsd(8) process (at \fBlocalhost:30003\fR) by default\. Use the environment variable \fBTZPFMS_TPM1X\fR to specify a remote TCS hostname\.
.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"
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM1X-CHANGE-KEY 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm1x-change-key
.Nd change ZFS dataset key to one stored on the TPM
.Sh SYNOPSIS
.Nm
.Op Fl b Ar backup-file
.Ar dataset
.
.Sh DESCRIPTION
To normalise the
.Ar dataset ,
.Nm
will open its encryption root in its stead.
.Nm
will
.Em never
create or destroy encryption roots; use
.Xr zfs-change-key 8
for that.
.Pp
First, a connection is made to the TPM, which
.Em must
be TPM-1.X-compatible.
.Pp
If
.Ar dataset
was previously encrypted with
.Nm tzpfms
and the
.Sy 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.
.Pp
Next, a new wrapping key is be generated on the TPM, optionally backed up
.Pq see Sx OPTIONS ,
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 it is not "well-known" (all zeroes).
.Pp
The following properties are set on
.Ar dataset :
.Bl -bullet -compact -offset 4n -width ""
.\"" TODO: width?
.It
.Li xyz.nabijaczleweli:tzpfms.backend Ns = Ns Sy TPM1.X
.It
.Li xyz.nabijaczleweli:tzpfms.key Ns = Ns Ar parent-key-blob Ns Cm \&: Ns Ar sealed-object-blob
.El
.Pp
.Li tzpfms.backend
identifies this dataset for work with
.Sy TPM1.X Ns -back-ended
.Nm tzpfms
tools
.Pq namely Xr zfs-tpm1x-change-key 8 , Xr zfs-tpm1x-load-key 8 , and Xr zfs-tpm1x-clear-key 8 .
.Pp
.Li 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
.Li CE4CF677875B5EB8993591D5A9AF1ED24A3A8736 ;
the second represents the sealed object containing the wrapping key,
and is protected with the SHA1 constant
.Li B9EE715DBE4B243FAA81EA04306E063710383E35 .
There exists no other user-land tool for decrypting this; perhaps there should be.
.\"" TODO: make an LD_PRELOADable for extracting the key maybe?
.Pp
Finally, the equivalent of
.Nm zfs Cm change-key Fl o Li keylocation=prompt Fl o Li keyformat=raw Ar 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.
.Pp
A final verification should be made by running
.Nm zfs-tpm1x-load-key Fl n Ar dataset .
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a password with
.Nm zfs-tpm1x-clear-key Ar dataset
.Pq or, if that fails to work, Nm zfs Cm change-key Fl o Li keyformat=passphrase Ar dataset ,
and you are hereby asked to report a bug, please.
.Pp
.Nm zfs-tpm1x-clear-key Ar dataset
can be used to clear the properties and go back to using a password.
.
.Sh OPTIONS
.Bl -tag -compact -width "-b backup-file"
.It Fl b Ar backup-file
Save a back-up of the key to
.Ar backup-file ,
which must not exist beforehand.
This back-up
.Em must
be stored securely, off-site.
In case of a catastrophic event, the key can be loaded by running
.Dl Nm zfs Cm load-key Ar dataset Li < Ar backup-file
.El
.
.Sh TPM1.X back-end configuration
.Ss TPM selection
The
.Nm tzpfms
suite connects to a local
.Xr tcsd 8
process
.Pq at Pa localhost:30003
by default.
Use the environment variable
.Ev TZPFMS_TPM1X
to specify a remote TCS hostname.
.Pp
The TrouSerS
.Xr tcsd 8
daemon will try
.Pa /dev/tpm0 ,
then
.Pa /udev/tpm0 ,
then
.Pa /dev/tpm ;
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
.Lk https:/\&/sourceforge.net/projects/trousers .
.Pp
The TPM 1.2 main specification index at
.Lk https:/\&/trustedcomputinggroup.org/resource/tpm-main-specification .
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

335
zfs-tpm1x-change-key.8.html
View File

@ -1,187 +1,170 @@
<!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>
<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>
<!--
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>, <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a> will open its encryption root in its stead.
<a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-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-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;
the user is prompted for an optional passphrase to protect the key with,
and for the SRK passphrase, set when taking ownership, if it is not "well-known" (all zeroes).</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>
<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>]
<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/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-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 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 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 it is 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><code>tzpfms.backend</code> identifies this dataset for work with <em>TPM1.X</em>-back-ended tzpfms tools
(namely <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a>, <a class="man-ref" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-load-key<span class="s">(8)</span></a>, and <a class="man-ref" href="zfs-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key<span class="s">(8)</span></a>).</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; perhaps there should be.</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><a class="man-ref" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-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-tpm1x-clear-key.8.html">zfs-tpm1x-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-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key<span class="s">(8)</span></a> 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>
<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>
tools (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 password, 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 password 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 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>
<h2 id="TPM1-X-back-end-configuration">TPM1.X back-end configuration</h2>
<h3 id="TPM-selection">TPM selection</h3>
<p>The tzpfms suite 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>) by default.
Use the environment variable <code>TZPFMS_TPM1X</code> to specify a remote TCS hostname.</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>
</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/bullseye/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/bullseye/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>
</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'>January 2021</li>
<li class='tr'>zfs-tpm1x-change-key(8)</li>
</ol>
</div>
</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="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>

106
zfs-tpm1x-change-key.8.html_fragment
View File

@ -1,106 +0,0 @@
<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>, <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a> will open its encryption root in its stead.
<a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-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-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;
the user is prompted for an optional passphrase to protect the key with,
and for the SRK passphrase, set when taking ownership, if it is not "well-known" (all zeroes).</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 <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a>, <a class="man-ref" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-load-key<span class="s">(8)</span></a>, and <a class="man-ref" href="zfs-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key<span class="s">(8)</span></a>).</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; perhaps there should be.</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><a class="man-ref" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-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-tpm1x-clear-key.8.html">zfs-tpm1x-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-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key<span class="s">(8)</span></a> 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 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>) by default.
Use the environment variable <code>TZPFMS_TPM1X</code> to specify a remote TCS hostname.</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>

90
zfs-tpm1x-change-key.md
View File

@ -1,90 +0,0 @@
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;
the user is prompted for an optional passphrase to protect the key with,
and for the SRK passphrase, set when taking ownership, if it is not "well-known" (all zeroes).
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; perhaps there should be.
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 connects to a local tcsd(8) process (at `localhost:30003`) by default.
Use the environment variable `TZPFMS_TPM1X` to specify a remote TCS hostname.
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;

116
zfs-tpm1x-clear-key.8
View File

@ -1,40 +1,82 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM1X\-CLEAR\-KEY" "8" "January 2021" "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 connects to a local tcsd(8) process (at \fBlocalhost:30003\fR) by default\. Use the environment variable \fBTZPFMS_TPM1X\fR to specify a remote TCS hostname\.
.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"
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM1X-CLEAR-KEY 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm1x-clear-key
.Nd rewrap ZFS dataset key in passsword and clear tzpfms TPM1.X metadata
.Sh SYNOPSIS
.Nm
.Ar dataset
.
.Sh DESCRIPTION
After verifying
.Ar dataset
was encrypted with
.Nm tzpfms
backend
.Sy TPM1.X :
.Bl -enum -compact -offset 4n -width ""
.It
performs the equivalent of
.Nm zfs Cm change-key Fl o Li keylocation=prompt Fl o Li keyformat=passphrase Ar dataset ,
.It
removes the
.Li xyz.nabijaczleweli:tzpfms.\& Ns Brq Li backend , key
properties from
.Ar dataset .
.El
.Pp
See
.Xr zfs-tpm1x-change-key 8
for a detailed description.
.
.Sh TPM1.X back-end configuration
.Ss TPM selection
The
.Nm tzpfms
suite connects to a local
.Xr tcsd 8
process
.Pq at Pa localhost:30003
by default.
Use the environment variable
.Ev TZPFMS_TPM1X
to specify a remote TCS hostname.
.Pp
The TrouSerS
.Xr tcsd 8
daemon will try
.Pa /dev/tpm0 ,
then
.Pa /udev/tpm0 ,
then
.Pa /dev/tpm ;
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
.Lk https:/\&/sourceforge.net/projects/trousers .
.Pp
The TPM 1.2 main specification index at
.Lk https:/\&/trustedcomputinggroup.org/resource/tpm-main-specification .
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

230
zfs-tpm1x-clear-key.8.html
View File

@ -1,140 +1,110 @@
<!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>
<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-CLEAR-KEY(8)</title>
</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><a class="man-ref" href="zfs-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key<span class="s">(8)</span></a>, 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>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM1X-CLEAR-KEY(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM1X-CLEAR-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-clear-key</code> &#x2014;
<span class="Nd">rewrap ZFS dataset key in passsword and clear tzpfms TPM1.X
metadata</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-clear-key</code></td>
<td><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">After verifying <var class="Ar">dataset</var> was encrypted with
<code class="Nm">tzpfms</code> backend
<a class="permalink" href="#TPM1.X"><b class="Sy" id="TPM1.X">TPM1.X</b></a>:</p>
<ol class="Bl-enum Bd-indent Bl-compact">
<li>performs 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=passphrase</code>
<var class="Ar">dataset</var>,</li>
<li>removes the
<code class="Li">xyz.nabijaczleweli:tzpfms.</code>{<code class="Li">backend</code>,
<code class="Li">key</code>} properties from
<var class="Ar">dataset</var>.</li>
</ol>
<p>See <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a> 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 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>) by default.
Use the environment variable <code>TZPFMS_TPM1X</code> to specify a remote TCS hostname.</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>
<p class="Pp">See
<a class="Xr" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key(8)</a>
for a detailed description.</p>
</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/bullseye/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/bullseye/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>
</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'>January 2021</li>
<li class='tr'>zfs-tpm1x-clear-key(8)</li>
</ol>
</div>
</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="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>

60
zfs-tpm1x-clear-key.8.html_fragment
View File

@ -1,60 +0,0 @@
<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><a class="man-ref" href="zfs-tpm1x-clear-key.8.html">zfs-tpm1x-clear-key<span class="s">(8)</span></a>, 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 <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a> 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 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>) by default.
Use the environment variable <code>TZPFMS_TPM1X</code> to specify a remote TCS hostname.</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>

52
zfs-tpm1x-clear-key.md
View File

@ -1,52 +0,0 @@
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 connects to a local tcsd(8) process (at `localhost:30003`) by default.
Use the environment variable `TZPFMS_TPM1X` to specify a remote TCS hostname.
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;

123
zfs-tpm1x-load-key.8
View File

@ -1,41 +1,88 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM1X\-LOAD\-KEY" "8" "January 2021" "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 connects to a local tcsd(8) process (at \fBlocalhost:30003\fR) by default\. Use the environment variable \fBTZPFMS_TPM1X\fR to specify a remote TCS hostname\.
.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"
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM1X-LOAD-KEY 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm1x-load-key
.Nd load tzpfms TPM1.X-encrypted ZFS dataset key
.Sh SYNOPSIS
.Nm
.Op Fl n
.Ar dataset
.
.Sh DESCRIPTION
After verifying
.Ar dataset
was encrypted with
.Nm tzpfms
backend
.Sy TPM1.X
will unseal the key and load it into
.Ar dataset .
.Pp
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.
.Pp
See
.Xr zfs-tpm1x-change-key 8
for a detailed description.
.
.Sh OPTIONS
.Bl -tag -compact -width "-n"
.It Fl n
Do a no-op/dry run, can be used even if the key is already loaded.
Equivalent to
.Nm zfs Cm load-key Ns 's
.Fl n
option.
.El
.
.Sh TPM1.X back-end configuration
.Ss TPM selection
The
.Nm tzpfms
suite connects to a local
.Xr tcsd 8
process
.Pq at Pa localhost:30003
by default.
Use the environment variable
.Ev TZPFMS_TPM1X
to specify a remote TCS hostname.
.Pp
The TrouSerS
.Xr tcsd 8
daemon will try
.Pa /dev/tpm0 ,
then
.Pa /udev/tpm0 ,
then
.Pa /dev/tpm ;
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
.Lk https:/\&/sourceforge.net/projects/trousers .
.Pp
The TPM 1.2 main specification index at
.Lk https:/\&/trustedcomputinggroup.org/resource/tpm-main-specification .
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

237
zfs-tpm1x-load-key.8.html
View File

@ -1,146 +1,111 @@
<!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>
<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-LOAD-KEY(8)</title>
</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><a class="man-ref" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-load-key<span class="s">(8)</span></a>, 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 <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a> 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>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM1X-LOAD-KEY(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM1X-LOAD-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-load-key</code> &#x2014;
<span class="Nd">load tzpfms TPM1.X-encrypted ZFS dataset key</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-load-key</code></td>
<td>[<code class="Fl">-n</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">After verifying <var class="Ar">dataset</var> was encrypted with
<code class="Nm">tzpfms</code> backend
<a class="permalink" href="#TPM1.X"><b class="Sy" id="TPM1.X">TPM1.X</b></a>
will unseal the key and load it into <var class="Ar">dataset</var>.</p>
<p class="Pp">The user is prompted for, first, the SRK passphrase, set when
taking ownership, if it's not &quot;well-known&quot; (all zeroes), then the
additional passphrase set when creating the key, if it was provided.</p>
<p class="Pp">See
<a class="Xr" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key(8)</a>
for a detailed description.</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="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
<dd>Do a no-op/dry run, can be used even if the key is already loaded.
Equivalent to <code class="Nm">zfs</code>
<code class="Cm">load-key</code>'s <code class="Fl">-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 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>) by default.
Use the environment variable <code>TZPFMS_TPM1X</code> to specify a remote TCS hostname.</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>
</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/bullseye/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/bullseye/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>
</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'>January 2021</li>
<li class='tr'>zfs-tpm1x-load-key(8)</li>
</ol>
</div>
</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="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>

65
zfs-tpm1x-load-key.8.html_fragment
View File

@ -1,65 +0,0 @@
<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><a class="man-ref" href="zfs-tpm1x-load-key.8.html">zfs-tpm1x-load-key<span class="s">(8)</span></a>, 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 <a class="man-ref" href="zfs-tpm1x-change-key.8.html">zfs-tpm1x-change-key<span class="s">(8)</span></a> 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 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>) by default.
Use the environment variable <code>TZPFMS_TPM1X</code> to specify a remote TCS hostname.</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>

57
zfs-tpm1x-load-key.md
View File

@ -1,57 +0,0 @@
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 connects to a local tcsd(8) process (at `localhost:30003`) by default.
Use the environment variable `TZPFMS_TPM1X` to specify a remote TCS hostname.
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;

209
zfs-tpm2-change-key.8
View File

@ -1,62 +1,153 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM2\-CHANGE\-KEY" "8" "January 2021" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm2\-change\-key\fR \- change ZFS dataset key to one stored on the TPM
.SH "SYNOPSIS"
\fBzfs\-tpm2\-change\-key\fR [\-b file] \fIdataset\fR
.SH "DESCRIPTION"
To normalise \fBdataset\fR, zfs\-tpm2\-change\-key(8) will open its encryption root in its stead\. zfs\-tpm2\-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\-2\.0\-compatible\.
.P
If \fBdataset\fR was previously encrypted with tzpfms and the \fITPM2\fR 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
Next, a new wrapping key is be generated on the TPM, optionally backed up (see \fIOPTIONS\fR), 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
The following properties are set on \fBdataset\fR:
.IP "\[ci]" 4
\fBxyz\.nabijaczleweli:tzpfms\.backend\fR=\fBTPM2\fR
.IP "\[ci]" 4
\fBxyz\.nabijaczleweli:tzpfms\.key\fR=\fI(ID of persistent object)\fR
.IP "" 0
.P
\fBtzpfms\.backend\fR identifies this dataset for work with \fITPM2\fR\-back\-ended tzpfms tools (namely zfs\-tpm2\-change\-key(8), zfs\-tpm2\-load\-key(8), and zfs\-tpm2\-clear\-key(8))\.
.P
\fBtzpfms\.key\fR is an integer representing the sealed object; if needed, it can be passed to \fBtpm2_unseal(1) \-c ${tzpfms\.key} [\-p ${password}]\fR or equivalent for back\-up (see \fIOPTIONS\fR)\. 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
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 persistent object and properties, or to issue a note for manual intervention into the standard error stream\.
.P
A final verification should be made by running \fBzfs\-tpm2\-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\-tpm2\-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\-tpm2\-clear\-key(8) dataset\fR can be used to free the TPM persistent object 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 "TPM2 back\-end configuration"
.SS "Environment variables"
.TP
\fBTSS2_LOG\fR=
Any of: \fINONE\fR, \fIERROR\fR, \fIWARNING\fR, \fIINFO\fR, \fIDEBUG\fR, \fITRACE\fR\. Default: \fIWARNING\fR\.
.SS "TPM selection"
The library \fBlibtss2\-tcti\-default\.so\fR can be linked to any of the \fBlibtss2\-tcti\-*\.so\fR libraries to select the default, otherwise \fB/dev/tpmrm0\fR, then \fB/dev/tpm0\fR, then \fBlocalhost:2321\fR will be tried, in order (see ESYS_CONTEXT(3))\.
.SS "See also"
The tpm2\-tss git repository at \fIhttps://github\.com/tpm2\-software/tpm2\-tss\fR and the documentation at \fIhttps://tpm2\-tss\.readthedocs\.io\fR\.
.P
The TPM 2\.0 specifications, mainly at <\fIhttps://trustedcomputinggroup\.org/wp\-content/uploads/TPM\-Rev\-2\.0\-Part\-1\-Architecture\-01\.38\.pdf\fR> and related pages\.
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM2-CHANGE-KEY 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm2-change-key
.Nd change ZFS dataset key to one stored on the TPM
.Sh SYNOPSIS
.Nm
.Op Fl b Ar backup-file
.Ar dataset
.
.Sh DESCRIPTION
To normalise
.Ar dataset ,
.Nm
will open its encryption root in its stead.
.Nm
will
.Em never
create or destroy encryption roots; use
.Xr zfs-change-key 8
for that.
.Pp
First, a connection is made to the TPM, which
.Em must
be TPM-2.0-compatible.
.Pp
If
.Ar dataset
was previously encrypted with
.Nm tzpfms
and the
.Sy TPM2
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.
.Pp
Next, a new wrapping key is be generated on the TPM, optionally backed up
.Pq see Sx OPTIONS ,
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.
.Pp
The following properties are set on
.Ar dataset :
.Bl -bullet -compact -offset 4n -width ""
.\"" TODO: width?
.It
.Li xyz.nabijaczleweli:tzpfms.backend Ns = Ns Sy TPM2
.It
.Li xyz.nabijaczleweli:tzpfms.key Ns = Ns Ar ID of persistent object
.El
.Pp
.Li tzpfms.backend
identifies this dataset for work with
.Sy TPM2 Ns -back-ended
.Nm tzpfms
tools
.Pq namely Xr zfs-tpm2-change-key 8 , Xr zfs-tpm2-load-key 8 , and Xr zfs-tpm2-clear-key 8 .
.Pp
.Li tzpfms.key
is an integer representing the sealed object;
if needed, it can be passed to
.Nm tpm2_unseal Fl c Ev ${tzpfms.key} Op Fl p Ev ${password}
or equivalent for back-up
.Pq see Sx OPTIONS .
If you have a sealed key you can access with that or equivalent tool and set both of these properties, it will funxion seamlessly.
.Pp
Finally, the equivalent of
.Nm zfs Cm change-key Fl o Li keylocation=prompt Fl o Li keyformat=raw Ar dataset
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.
.Pp
A final verification should be made by running
.Nm zfs-tpm2-load-key Fl n Ar dataset .
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a password with
.Nm zfs-tpm2-clear-key Ar dataset
.Pq or, if that fails to work, Nm zfs Cm change-key Fl o Li keyformat=passphrase Ar dataset ,
and you are hereby asked to report a bug, please.
.Pp
.Nm zfs-tpm2-clear-key Ar dataset
can be used to free the TPM persistent object and go back to using a password.
.
.Sh OPTIONS
.Bl -tag -compact -width "-b backup-file"
.It Fl b Ar backup-file
Save a back-up of the key to
.Ar backup-file ,
which must not exist beforehand.
This back-up
.Em must
be stored securely, off-site.
In case of a catastrophic event, the key can be loaded by running
.Dl Nm zfs Cm load-key Ar dataset Li < Ar backup-file
.El
.
.Sh TPM2 back-end configuration
.Ss Environment variables
.Bl -tag -compact -width "TSS2_LOG"
.It Ev TSS2_LOG
Any of:
.Sy NONE , ERROR , WARNING , INFO , DEBUG , TRACE .
Default:
.Sy WARNING .
.El
.
.Ss TPM selection
The library
.Nm libtss2-tcti-default.so
can be linked to any of the
.Pa libtss2-tcti-*.so
libraries to select the default, otherwise
.Pa /dev/tpmrm0 ,
then
.Pa /dev/tpm0 ,
then
.Pa localhost:2321
will be tried, in order
.Pq see Xr ESYS_CONTEXT 3 .
.
.Ss See also
The tpm2-tss git repository at
.Lk https:/\&/github.com/tpm2-software/tpm2-tss
and the documentation at
.Lk https:/\&/tpm2-tss.readthedocs.io .
.Pp
The TPM 2.0 specifications, mainly at
.Lk https:/\&/trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
and related pages.
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Xr tpm2_unseal 1
.Pp
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

348
zfs-tpm2-change-key.8.html
View File

@ -1,189 +1,183 @@
<!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-tpm2-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>
<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>
<!--
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="#TPM2-BACK-END-CONFIGURATION">TPM2 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-tpm2-change-key(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm2-change-key(8)</li>
</ol>
<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;
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>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>
<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><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} [-p ${password}]</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 &lt; backup-file</strong>.</dd>
<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>
<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>
</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>
<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 &lt;<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>&gt; and related pages.</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>
</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>
<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'>January 2021</li>
<li class='tr'>zfs-tpm2-change-key(8)</li>
</ol>
</div>
</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>

108
zfs-tpm2-change-key.8.html_fragment
View File

@ -1,108 +0,0 @@
<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;
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>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} [-p ${password}]</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 &lt; 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 &lt;<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>&gt; and related pages.</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-tpm2-change-key.md
View File

@ -1,89 +0,0 @@
zfs-tpm2-change-key(8) -- change ZFS dataset key to one stored on the TPM
=========================================================================
## SYNOPSIS
`zfs-tpm2-change-key` [-b file] <dataset>
## DESCRIPTION
To normalise `dataset`, zfs-tpm2-change-key(8) will open its encryption root in its stead.
zfs-tpm2-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-2.0-compatible.
If `dataset` was previously encrypted with tzpfms and the *TPM2* 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.
Next, a new wrapping key is be generated on the TPM, optionally backed up (see [OPTIONS][]),
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.
The following properties are set on `dataset`:
* `xyz.nabijaczleweli:tzpfms.backend`=`TPM2`
* `xyz.nabijaczleweli:tzpfms.key`=*(ID of persistent object)*
`tzpfms.backend` identifies this dataset for work with *TPM2*-back-ended tzpfms tools
(namely zfs-tpm2-change-key(8), zfs-tpm2-load-key(8), and zfs-tpm2-clear-key(8)).
`tzpfms.key` is an integer representing the sealed object;
if needed, it can be passed to **tpm2_unseal(1) -c ${tzpfms.key} [-p ${password}]** or equivalent for back-up (see [OPTIONS][]).
If you have a sealed key you can access with that or equivalent tool and set both of these properties, it will funxion seamlessly.
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 persistent object and properties,
or to issue a note for manual intervention into the standard error stream.
A final verification should be made by running **zfs-tpm2-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-tpm2-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-tpm2-clear-key(8) dataset** can be used to free the TPM persistent object 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**.
## TPM2 back-end configuration
### Environment variables
* `TSS2_LOG`=:
Any of: *NONE*, *ERROR*, *WARNING*, *INFO*, *DEBUG*, *TRACE*. Default: *WARNING*.
### TPM selection
The library `libtss2-tcti-default.so` can be linked to any of the `libtss2-tcti-*.so` libraries to select the default,
otherwise `/dev/tpmrm0`, then `/dev/tpm0`, then `localhost:2321` will be tried, in order (see ESYS_CONTEXT(3)).
### See also
The tpm2-tss git repository at <https://github.com/tpm2-software/tpm2-tss> and the documentation at <https://tpm2-tss.readthedocs.io>.
The TPM 2.0 specifications, mainly at &lt;<https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf>&gt; and related pages.
## 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;

127
zfs-tpm2-clear-key.8
View File

@ -1,44 +1,89 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM2\-CLEAR\-KEY" "8" "January 2021" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm2\-clear\-key\fR \- rewrap ZFS dataset key in passsword and clear tzpfms TPM2 metadata
.SH "SYNOPSIS"
\fBzfs\-tpm2\-clear\-key\fR \fIdataset\fR
.SH "DESCRIPTION"
zfs\-tpm2\-clear\-key(8), after verifying that \fBdataset\fR was encrypted with tzpfms backend \fITPM2\fR will:
.IP "1." 4
perform the equivalent of \fBzfs(8) change\-key \-o keylocation=prompt \-o keyformat=passphrase dataset\fR,
.IP "2." 4
free the sealed key previously used to encrypt \fBdataset\fR,
.IP "3." 4
remove the \fBxyz\.nabijaczleweli:tzpfms\.{backend,key}\fR properties from \fBdataset\fR\.
.IP "" 0
.P
See zfs\-tpm2\-change\-key(8) for a detailed description\.
.SH "TPM2 back\-end configuration"
.SS "Environment variables"
.TP
\fBTSS2_LOG\fR=
Any of: \fINONE\fR, \fIERROR\fR, \fIWARNING\fR, \fIINFO\fR, \fIDEBUG\fR, \fITRACE\fR\. Default: \fIWARNING\fR\.
.SS "TPM selection"
The library \fBlibtss2\-tcti\-default\.so\fR can be linked to any of the \fBlibtss2\-tcti\-*\.so\fR libraries to select the default, otherwise \fB/dev/tpmrm0\fR, then \fB/dev/tpm0\fR, then \fBlocalhost:2321\fR will be tried, in order (see ESYS_CONTEXT(3))\.
.SS "See also"
The tpm2\-tss git repository at \fIhttps://github\.com/tpm2\-software/tpm2\-tss\fR and the documentation at \fIhttps://tpm2\-tss\.readthedocs\.io\fR\.
.P
The TPM 2\.0 specifications, mainly at <\fIhttps://trustedcomputinggroup\.org/wp\-content/uploads/TPM\-Rev\-2\.0\-Part\-1\-Architecture\-01\.38\.pdf\fR> and related pages\.
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM2-CLEAR-KEY 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm2-clear-key
.Nd rewrap ZFS dataset key in passsword and clear tzpfms TPM2 metadata
.Sh SYNOPSIS
.Nm
.Ar dataset
.
.Sh DESCRIPTION
After verifying
.Ar dataset
was encrypted with
.Nm tzpfms
backend
.Sy TPM2 :
.Bl -enum -compact -offset 4n -width ""
.It
performs the equivalent of
.Nm zfs Cm change-key Fl o Li keylocation=prompt Fl o Li keyformat=passphrase Ar dataset ,
.It
frees the sealed key previously used to encrypt
.Ar dataset ,
.It
removes the
.Li xyz.nabijaczleweli:tzpfms.\& Ns Brq Li backend , key
properties from
.Ar dataset .
.El
.Pp
See
.Xr zfs-tpm2-change-key 8
for a detailed description.
.
.Sh TPM2 back-end configuration
.Ss Environment variables
.Bl -tag -compact -width "TSS2_LOG"
.It Ev TSS2_LOG
Any of:
.Sy NONE , ERROR , WARNING , INFO , DEBUG , TRACE .
Default:
.Sy WARNING .
.El
.
.Ss TPM selection
The library
.Nm libtss2-tcti-default.so
can be linked to any of the
.Pa libtss2-tcti-*.so
libraries to select the default, otherwise
.Pa /dev/tpmrm0 ,
then
.Pa /dev/tpm0 ,
then
.Pa localhost:2321
will be tried, in order
.Pq see Xr ESYS_CONTEXT 3 .
.
.Ss See also
The tpm2-tss git repository at
.Lk https:/\&/github.com/tpm2-software/tpm2-tss
and the documentation at
.Lk https:/\&/tpm2-tss.readthedocs.io .
.Pp
The TPM 2.0 specifications, mainly at
.Lk https:/\&/trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
and related pages.
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

249
zfs-tpm2-clear-key.8.html
View File

@ -1,146 +1,125 @@
<!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-tpm2-clear-key(8) - rewrap ZFS dataset key in passsword and clear tzpfms TPM2 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>
<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-CLEAR-KEY(8)</title>
</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="#TPM2-BACK-END-CONFIGURATION">TPM2 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-tpm2-clear-key(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm2-clear-key(8)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm2-clear-key</code> - <span class="man-whatis">rewrap ZFS dataset key in passsword and clear tzpfms TPM2 metadata</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm2-clear-key</code> <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><a class="man-ref" href="zfs-tpm2-clear-key.8.html">zfs-tpm2-clear-key<span class="s">(8)</span></a>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM2</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>free the sealed key previously used to encrypt <code>dataset</code>,</li>
<li>remove the <code>xyz.nabijaczleweli:tzpfms.{backend,key}</code> properties from <code>dataset</code>.</li>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM2-CLEAR-KEY(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM2-CLEAR-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-clear-key</code> &#x2014;
<span class="Nd">rewrap ZFS dataset key in passsword and clear tzpfms TPM2
metadata</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-clear-key</code></td>
<td><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">After verifying <var class="Ar">dataset</var> was encrypted with
<code class="Nm">tzpfms</code> backend
<a class="permalink" href="#TPM2"><b class="Sy" id="TPM2">TPM2</b></a>:</p>
<ol class="Bl-enum Bd-indent Bl-compact">
<li>performs 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=passphrase</code>
<var class="Ar">dataset</var>,</li>
<li>frees the sealed key previously used to encrypt
<var class="Ar">dataset</var>,</li>
<li>removes the
<code class="Li">xyz.nabijaczleweli:tzpfms.</code>{<code class="Li">backend</code>,
<code class="Li">key</code>} properties from
<var class="Ar">dataset</var>.</li>
</ol>
<p>See <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> for a detailed description.</p>
<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>
<p class="Pp">See
<a class="Xr" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key(8)</a>
for a detailed description.</p>
</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>
<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 &lt;<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>&gt; and related pages.</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>
</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>
<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'>January 2021</li>
<li class='tr'>zfs-tpm2-clear-key(8)</li>
</ol>
</div>
</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="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>

66
zfs-tpm2-clear-key.8.html_fragment
View File

@ -1,66 +0,0 @@
<div class='mp'>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm2-clear-key</code> - <span class="man-whatis">rewrap ZFS dataset key in passsword and clear tzpfms TPM2 metadata</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm2-clear-key</code> <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><a class="man-ref" href="zfs-tpm2-clear-key.8.html">zfs-tpm2-clear-key<span class="s">(8)</span></a>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM2</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>free the sealed key previously used to encrypt <code>dataset</code>,</li>
<li>remove the <code>xyz.nabijaczleweli:tzpfms.{backend,key}</code> properties from <code>dataset</code>.</li>
</ol>
<p>See <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> for a detailed description.</p>
<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 &lt;<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>&gt; and related pages.</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>

55
zfs-tpm2-clear-key.md
View File

@ -1,55 +0,0 @@
zfs-tpm2-clear-key(8) -- rewrap ZFS dataset key in passsword and clear tzpfms TPM2 metadata
===========================================================================================
## SYNOPSIS
`zfs-tpm2-clear-key` <dataset>
## DESCRIPTION
zfs-tpm2-clear-key(8), after verifying that `dataset` was encrypted with tzpfms backend *TPM2* will:
1. perform the equivalent of **zfs(8) change-key -o keylocation=prompt -o keyformat=passphrase dataset**,
2. free the sealed key previously used to encrypt `dataset`,
3. remove the `xyz.nabijaczleweli:tzpfms.{backend,key}` properties from `dataset`.
See zfs-tpm2-change-key(8) for a detailed description.
## TPM2 back-end configuration
### Environment variables
* `TSS2_LOG`=:
Any of: *NONE*, *ERROR*, *WARNING*, *INFO*, *DEBUG*, *TRACE*. Default: *WARNING*.
### TPM selection
The library `libtss2-tcti-default.so` can be linked to any of the `libtss2-tcti-*.so` libraries to select the default,
otherwise `/dev/tpmrm0`, then `/dev/tpm0`, then `localhost:2321` will be tried, in order (see ESYS_CONTEXT(3)).
### See also
The tpm2-tss git repository at <https://github.com/tpm2-software/tpm2-tss> and the documentation at <https://tpm2-tss.readthedocs.io>.
The TPM 2.0 specifications, mainly at &lt;<https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf>&gt; and related pages.
## 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;

120
zfs-tpm2-load-key.8
View File

@ -1,41 +1,85 @@
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "ZFS\-TPM2\-LOAD\-KEY" "8" "January 2021" "tzpfms developers"
.SH "NAME"
\fBzfs\-tpm2\-load\-key\fR \- load tzpfms TPM2\-encrypted ZFS dataset key
.SH "SYNOPSIS"
\fBzfs\-tpm2\-load\-key\fR [\-n] \fIdataset\fR
.SH "DESCRIPTION"
zfs\-tpm2\-load\-key(8), after verifying that \fBdataset\fR was encrypted with tzpfms backend \fITPM2\fR will unseal the key and load it into \fBdataset\fR\.
.P
See zfs\-tpm2\-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 "TPM2 back\-end configuration"
.SS "Environment variables"
.TP
\fBTSS2_LOG\fR=
Any of: \fINONE\fR, \fIERROR\fR, \fIWARNING\fR, \fIINFO\fR, \fIDEBUG\fR, \fITRACE\fR\. Default: \fIWARNING\fR\.
.SS "TPM selection"
The library \fBlibtss2\-tcti\-default\.so\fR can be linked to any of the \fBlibtss2\-tcti\-*\.so\fR libraries to select the default, otherwise \fB/dev/tpmrm0\fR, then \fB/dev/tpm0\fR, then \fBlocalhost:2321\fR will be tried, in order (see ESYS_CONTEXT(3))\.
.SS "See also"
The tpm2\-tss git repository at \fIhttps://github\.com/tpm2\-software/tpm2\-tss\fR and the documentation at \fIhttps://tpm2\-tss\.readthedocs\.io\fR\.
.P
The TPM 2\.0 specifications, mainly at <\fIhttps://trustedcomputinggroup\.org/wp\-content/uploads/TPM\-Rev\-2\.0\-Part\-1\-Architecture\-01\.38\.pdf\fR> and related pages\.
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
.Dd October 15, 2021
.ds doc-volume-operating-system
.Dt ZFS-TPM2-LOAD-KEY 8
.Os tzpfms 0.1-5
.
.Sh NAME
.Nm zfs-tpm2-load-key
.Nd load tzpfms TPM2-encrypted ZFS dataset key
.Sh SYNOPSIS
.Nm
.Op Fl n
.Ar dataset
.
.Sh DESCRIPTION
After verifying
.Ar dataset
was encrypted with
.Nm tzpfms
backend
.Sy TPM2 ,
unseals the key and loads it into
.Ar dataset .
.Pp
See
.Xr zfs-tpm2-change-key 8
for a detailed description.
.
.Sh OPTIONS
.Bl -tag -compact -width "-n"
.It Fl n
Do a no-op/dry run, can be used even if the key is already loaded.
Equivalent to
.Nm zfs Cm load-key Ns 's
.Fl n
option.
.El
.
.Sh TPM1.X back-end configuration
.Ss TPM selection
The
.Nm tzpfms
suite connects to a local
.Xr tcsd 8
process
.Pq at Pa localhost:30003
by default.
Use the environment variable
.Ev TZPFMS_TPM1X
to specify a remote TCS hostname.
.Pp
The TrouSerS
.Xr tcsd 8
daemon will try
.Pa /dev/tpm0 ,
then
.Pa /udev/tpm0 ,
then
.Pa /dev/tpm ;
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
.Lk https:/\&/sourceforge.net/projects/trousers .
.Pp
The TPM 1.2 main specification index at
.Lk https:/\&/trustedcomputinggroup.org/resource/tpm-main-specification .
.
.Sh SPECIAL THANKS
To all who support further development, in particular:
.IP "\[ci]" 4
.Bl -bullet -offset 4n -compact -width 0
.It
ThePhD
.IP "\[ci]" 4
.It
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>
.El
.
.Sh REPORTING BUGS
.Lk https:/\&/todo.sr.ht/~nabijaczleweli/tzpfms
.Pp
.Mt ~nabijaczleweli/tzpfms@lists.sr.ht ,
archived at
.Lk https:/\&/lists.sr.ht/~nabijaczleweli/tzpfms .
.
.Sh SEE ALSO
.Lk https:/\&/git.sr.ht/~nabijaczleweli/tzpfms

236
zfs-tpm2-load-key.8.html
View File

@ -1,148 +1,108 @@
<!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-tpm2-load-key(8) - load tzpfms TPM2-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>
<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-LOAD-KEY(8)</title>
</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="#TPM2-BACK-END-CONFIGURATION">TPM2 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-tpm2-load-key(8)</li>
<li class='tc'></li>
<li class='tr'>zfs-tpm2-load-key(8)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm2-load-key</code> - <span class="man-whatis">load tzpfms TPM2-encrypted ZFS dataset key</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm2-load-key</code> [-n] <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><a class="man-ref" href="zfs-tpm2-load-key.8.html">zfs-tpm2-load-key<span class="s">(8)</span></a>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM2</em> will unseal the key and load it into <code>dataset</code>.</p>
<p>See <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> 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>
<body>
<table class="head">
<tr>
<td class="head-ltitle">ZFS-TPM2-LOAD-KEY(8)</td>
<td class="head-vol">System Manager's Manual</td>
<td class="head-rtitle">ZFS-TPM2-LOAD-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-load-key</code> &#x2014;
<span class="Nd">load tzpfms TPM2-encrypted ZFS dataset key</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-load-key</code></td>
<td>[<code class="Fl">-n</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">After verifying <var class="Ar">dataset</var> was encrypted with
<code class="Nm">tzpfms</code> backend
<a class="permalink" href="#TPM2"><b class="Sy" id="TPM2">TPM2</b></a>,
unseals the key and loads it into <var class="Ar">dataset</var>.</p>
<p class="Pp">See
<a class="Xr" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key(8)</a>
for a detailed description.</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="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
<dd>Do a no-op/dry run, can be used even if the key is already loaded.
Equivalent to <code class="Nm">zfs</code>
<code class="Cm">load-key</code>'s <code class="Fl">-n</code> option.</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 &lt;<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>&gt; and related pages.</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>
</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/bullseye/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/bullseye/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>
</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'>January 2021</li>
<li class='tr'>zfs-tpm2-load-key(8)</li>
</ol>
</div>
</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="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>

67
zfs-tpm2-load-key.8.html_fragment
View File

@ -1,67 +0,0 @@
<div class='mp'>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>zfs-tpm2-load-key</code> - <span class="man-whatis">load tzpfms TPM2-encrypted ZFS dataset key</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>zfs-tpm2-load-key</code> [-n] <var>dataset</var></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p><a class="man-ref" href="zfs-tpm2-load-key.8.html">zfs-tpm2-load-key<span class="s">(8)</span></a>, after verifying that <code>dataset</code> was encrypted with tzpfms backend <em>TPM2</em> will unseal the key and load it into <code>dataset</code>.</p>
<p>See <a class="man-ref" href="zfs-tpm2-change-key.8.html">zfs-tpm2-change-key<span class="s">(8)</span></a> 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="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 &lt;<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>&gt; and related pages.</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-tpm2-load-key.md
View File

@ -1,56 +0,0 @@
zfs-tpm2-load-key(8) -- load tzpfms TPM2-encrypted ZFS dataset key
==================================================================
## SYNOPSIS
`zfs-tpm2-load-key` [-n] <dataset>
## DESCRIPTION
zfs-tpm2-load-key(8), after verifying that `dataset` was encrypted with tzpfms backend *TPM2* will unseal the key and load it into `dataset`.
See zfs-tpm2-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.
## TPM2 back-end configuration
### Environment variables
* `TSS2_LOG`=:
Any of: *NONE*, *ERROR*, *WARNING*, *INFO*, *DEBUG*, *TRACE*. Default: *WARNING*.
### TPM selection
The library `libtss2-tcti-default.so` can be linked to any of the `libtss2-tcti-*.so` libraries to select the default,
otherwise `/dev/tpmrm0`, then `/dev/tpm0`, then `localhost:2321` will be tried, in order (see ESYS_CONTEXT(3)).
### See also
The tpm2-tss git repository at <https://github.com/tpm2-software/tpm2-tss> and the documentation at <https://tpm2-tss.readthedocs.io>.
The TPM 2.0 specifications, mainly at &lt;<https://trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf>&gt; and related pages.
## 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;