ZFS-TPM1X-CHANGE-KEY(8) | System Manager's Manual | ZFS-TPM1X-CHANGE-KEY(8) |
zfs-tpm1x-change-key
—
change ZFS dataset key to one stored on the TPM
zfs-tpm1x-change-key |
[-b backup-file]
dataset |
To normalise the dataset,
zfs-tpm1x-change-key
will open its encryption root
in its stead. zfs-tpm1x-change-key
will
never
create or destroy encryption roots; use
zfs-change-key(8)
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 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 not "well-known" (all zeroes).
The following properties are set on dataset:
xyz.nabijaczleweli:tzpfms.backend
=TPM1.Xxyz.nabijaczleweli:tzpfms.key
=parent-key-blob:
sealed-object-blobtzpfms.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
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
-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
dataset
(or, if that fails to work, zfs
change-key
-o
keyformat=passphrase
dataset),
and you are hereby asked to report a bug, please.
zfs-tpm1x-clear-key
dataset can be used to clear the properties and go
back to using a password.
-b
backup-filezfs
load-key
dataset
<
backup-file
TZPFMS_PASSPHRASE_HELPER
sh
-c
to provide a passphrase, instead of reading
from the standard input stream.
The standard output stream of the helper is tied to an anonymous file and used in its entirety as the passphrase, except for a trailing new-line, if any. The arguments are:
If the helper doesn't exist (the shell exits with 127), a diagnostic is issued and the normal prompt is used as fall-back. If it fails for any other reason, the prompting is aborted.
An example value facilitating
systemd(1)
integration would be:
'exec
systemd-ask-password
--id
=
"tzpfms:
$2"
"$1:
"'.
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.
The TrouSerS project page at https://sourceforge.net/projects/trousers.
The TPM 1.2 main specification index at https://trustedcomputinggroup.org/resource/tpm-main-specification.
To all who support further development, in particular:
https://todo.sr.ht/~nabijaczleweli/tzpfms
~nabijaczleweli/tzpfms@lists.sr.ht, archived at https://lists.sr.ht/~nabijaczleweli/tzpfms.
November 18, 2021 | tzpfms 0.1-16 |