~nabijaczleweli/tzpfms

f8bb6174c3f6780478afc17962cd0dc02073a836 — наб a month ago 8653f24
Add manpages for zfs-tpm1x-*
A man/backend-tpm1x.h => man/backend-tpm1x.h +14 -0
@@ 0,0 1,14 @@
## TPM1.X back-end configuration

### TPM selection

The tzpfms suite always connects to a local tcsd(8) process (at `localhost:30003`).

The TrouSerS tcsd(8) daemon will try `/dev/tpm0`, then `/udev/tpm0`, then `/dev/tpm`;
by occupying one of the earlier ones with, for example, shell redirection, a later one can be selected.

### See also

The TrouSerS project page at <https://sourceforge.net/projects/trousers>.

The TPM 1.2 main specification index at &lt;<https://trustedcomputinggroup.org/resource/tpm-main-specification>&gt;.

M man/index.txt => man/index.txt +1 -0
@@ 3,6 3,7 @@ zfs-tpm2-load-key(8)    zfs-tpm2-load-key.8.ronn
zfs-tpm2-clear-key(8)   zfs-tpm2-clear-key.8.ronn

zfs(8)                  https://manpages.debian.org/bullseye/zfsutils-linux/zfs.8.en.html
tcsd(8)                 https://manpages.debian.org/bullseye/trousers/tcsd.8.en.html
tpm2_unseal(1)          https://manpages.debian.org/bullseye/tpm2-tools/tpm2_unseal.1.en.html

ESYS_CONTEXT(3)         https://www.mankier.com/3/ESYS_CONTEXT

A man/zfs-tpm1x-change-key.md.pp => man/zfs-tpm1x-change-key.md.pp +61 -0
@@ 0,0 1,61 @@
zfs-tpm1x-change-key(8) -- change ZFS dataset key to one stored on the TPM
==========================================================================

## SYNOPSIS

`zfs-tpm1x-change-key` [-b file] <dataset>

## DESCRIPTION

To normalise `dataset`, zfs-tpm1x-change-key(8) will open its encryption root in its stead.
zfs-tpm1x-change-key(8) will *never* create or destroy encryption roots; use **zfs(8) change-key** for that.

First, a connection is made to the TPM, which *must* be TPM-1.X-compatible.

If `dataset` was previously encrypted with tzpfms and the *TPM1.X* back-end was used, the metadata will be silently cleared.
Otherwise, or in case of an error, data required for manual intervention will be printed to the standard error stream.

Next, a new wrapping key is be generated on the TPM, optionally backed up (see [OPTIONS][]),
and sealed on the TPM;
if the SRK passphrase, set when taking ownership, is not "well-known" (all zeroes), the user is prompted for it;
the user is always prompted for an optional passphrase to protect the key with.

The following properties are set on `dataset`:

  * `xyz.nabijaczleweli:tzpfms.backend`=`TPM1.X`
  * `xyz.nabijaczleweli:tzpfms.key`=*(parent key blob)*`:`*(sealed object blob)*

`tzpfms.backend` identifies this dataset for work with *TPM1.X*-back-ended tzpfms tools
(namely zfs-tpm1x-change-key(8), zfs-tpm1x-load-key(8), and zfs-tpm1x-clear-key(8)).

`tzpfms.key` is a colon-separated pair of hexadecimal-string (i.e. "4F7730" for "Ow0") blobs;
the first one represents the RSA key protecting the blob,
and it is protected with either the password, if provided, or the SHA1 constant *CE4CF677875B5EB8993591D5A9AF1ED24A3A8736*;
the second represents the sealed object containing the wrapping key,
and is protected with the SHA1 constant *B9EE715DBE4B243FAA81EA04306E063710383E35*.
There exists no other user-land tool for decrypting this. (TODO: make an LD_PRELOADable for extracting the key maybe)

Finally, the equivalent of **zfs(8) change-key -o keylocation=prompt -o keyformat=raw dataset** is performed with the new key.
If an error occurred, best effort is made to clean up the properties,
or to issue a note for manual intervention into the standard error stream.

A final verification should be made by running **zfs-tpm1x-load-key(8) -n dataset**.
If that command succeeds, all is well,
but otherwise the dataset can be manually rolled back to a password with **zfs-tpm1x-clear-key(8) dataset** (or, if that fails to work, **zfs(8) change-key -o keyformat=passphrase dataset**), and you are hereby asked to report a bug, please.

**zfs-tpm1x-clear-key(8) dataset** can be used to clear the properties and go back to using a password.

## OPTIONS

  * `-b` *file*:
    Save a back-up of the key to *file*, which must not exist beforehand.
    This back-up **must** be stored securely, off-site.
    In case of a catastrophic event, the key can be loaded by running **zfs(8) load-key dataset < backup-file**.

#include "backend-tpm1x.h"

#include "common.h"

## SEE ALSO

&lt;<https://git.sr.ht/~nabijaczleweli/tzpfms>&gt;

A man/zfs-tpm1x-clear-key.md.pp => man/zfs-tpm1x-clear-key.md.pp +23 -0
@@ 0,0 1,23 @@
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.

#include "backend-tpm1x.h"

#include "common.h"

## SEE ALSO

&lt;<https://git.sr.ht/~nabijaczleweli/tzpfms>&gt;

A man/zfs-tpm1x-load-key.md.pp => man/zfs-tpm1x-load-key.md.pp +28 -0
@@ 0,0 1,28 @@
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.

#include "backend-tpm1x.h"

#include "common.h"

## SEE ALSO

&lt;<https://git.sr.ht/~nabijaczleweli/tzpfms>&gt;