~nabijaczleweli/tzpfms

fc4094f42484cb7979b51f344fb85c7b1af29454 — наб autouploader a month ago ef49e75
Manpage update by job 608529
30 files changed, 1962 insertions(+), 2513 deletions(-)

D index.txt
A style.css
M zfs-tpm-list.8
M zfs-tpm-list.8.html
D zfs-tpm-list.8.html_fragment
D zfs-tpm-list.md
M zfs-tpm1x-change-key.8
M zfs-tpm1x-change-key.8.html
D zfs-tpm1x-change-key.8.html_fragment
D zfs-tpm1x-change-key.md
M zfs-tpm1x-clear-key.8
M zfs-tpm1x-clear-key.8.html
D zfs-tpm1x-clear-key.8.html_fragment
D zfs-tpm1x-clear-key.md
M zfs-tpm1x-load-key.8
M zfs-tpm1x-load-key.8.html
D zfs-tpm1x-load-key.8.html_fragment
D zfs-tpm1x-load-key.md
M zfs-tpm2-change-key.8
M zfs-tpm2-change-key.8.html
D zfs-tpm2-change-key.8.html_fragment
D zfs-tpm2-change-key.md
M zfs-tpm2-clear-key.8
M zfs-tpm2-clear-key.8.html
D zfs-tpm2-clear-key.8.html_fragment
D zfs-tpm2-clear-key.md
M zfs-tpm2-load-key.8
M zfs-tpm2-load-key.8.html
D zfs-tpm2-load-key.8.html_fragment
D zfs-tpm2-load-key.md
D index.txt => index.txt +0 -13
@@ 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

A style.css => style.css +297 -0
@@ 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; }
}

M zfs-tpm-list.8 => zfs-tpm-list.8 +128 -81
@@ 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

M zfs-tpm-list.8.html => zfs-tpm-list.8.html +165 -181
@@ 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>

<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>
</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

<code class="Li">$</code> <code class="Nm"></code>zfs-tpm-list
  <code class="Fl">-ad0</code>
NAME BACK-END KEYSTATUS COHERENT
awa - 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

<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

<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>

D zfs-tpm-list.8.html_fragment => zfs-tpm-list.8.html_fragment +0 -110
@@ 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>

D zfs-tpm-list.md => zfs-tpm-list.md +0 -95
@@ 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;

M zfs-tpm1x-change-key.8 => zfs-tpm1x-change-key.8 +147 -57
@@ 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

M zfs-tpm1x-change-key.8.html => zfs-tpm1x-change-key.8.html +159 -176
@@ 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>

D zfs-tpm1x-change-key.8.html_fragment => zfs-tpm1x-change-key.8.html_fragment +0 -106
@@ 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>

D zfs-tpm1x-change-key.md => zfs-tpm1x-change-key.md +0 -90
@@ 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;

M zfs-tpm1x-clear-key.8 => zfs-tpm1x-clear-key.8 +79 -37
@@ 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

M zfs-tpm1x-clear-key.8.html => zfs-tpm1x-clear-key.8.html +100 -130
@@ 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>

D zfs-tpm1x-clear-key.8.html_fragment => zfs-tpm1x-clear-key.8.html_fragment +0 -60
@@ 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>

D zfs-tpm1x-clear-key.md => zfs-tpm1x-clear-key.md +0 -52
@@ 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;

M zfs-tpm1x-load-key.8 => zfs-tpm1x-load-key.8 +85 -38
@@ 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

M zfs-tpm1x-load-key.8.html => zfs-tpm1x-load-key.8.html +101 -136
@@ 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>

D zfs-tpm1x-load-key.8.html_fragment => zfs-tpm1x-load-key.8.html_fragment +0 -65
@@ 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>

D zfs-tpm1x-load-key.md => zfs-tpm1x-load-key.md +0 -57
@@ 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;

M zfs-tpm2-change-key.8 => zfs-tpm2-change-key.8 +150 -59
@@ 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

M zfs-tpm2-change-key.8.html => zfs-tpm2-change-key.8.html +171 -177
@@ 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>

D zfs-tpm2-change-key.8.html_fragment => zfs-tpm2-change-key.8.html_fragment +0 -108
@@ 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>

D zfs-tpm2-change-key.md => zfs-tpm2-change-key.md +0 -89
@@ 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;

M zfs-tpm2-clear-key.8 => zfs-tpm2-clear-key.8 +86 -41
@@ 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

M zfs-tpm2-clear-key.8.html => zfs-tpm2-clear-key.8.html +114 -135
@@ 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>

D zfs-tpm2-clear-key.8.html_fragment => zfs-tpm2-clear-key.8.html_fragment +0 -66
@@ 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>

D zfs-tpm2-clear-key.md => zfs-tpm2-clear-key.md +0 -55
@@ 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;

M zfs-tpm2-load-key.8 => zfs-tpm2-load-key.8 +82 -38
@@ 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

M zfs-tpm2-load-key.8.html => zfs-tpm2-load-key.8.html +98 -138
@@ 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>

D zfs-tpm2-load-key.8.html_fragment => zfs-tpm2-load-key.8.html_fragment +0 -67
@@ 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>

D zfs-tpm2-load-key.md => zfs-tpm2-load-key.md +0 -56
@@ 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;