mirror of
https://git.sr.ht/~nabijaczleweli/tzpfms
synced 2025-04-25 09:52:11 +03:00
212 lines
6.1 KiB
Groff
212 lines
6.1 KiB
Groff
.\" SPDX-License-Identifier: MIT
|
|
.
|
|
.Dd February 28, 2024
|
|
.ds doc-volume-operating-system
|
|
.Dt ZFS-TPM1X-CHANGE-KEY 8
|
|
.Os tzpfms 0.3.4-28-g7e4ea2c
|
|
.
|
|
.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
|
|
.Op Fl P Ar PCR Ns Oo Ns Cm \&, Ns Ar PCR Oc Ns …
|
|
.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 written to the standard error stream.
|
|
.Pp
|
|
Next, a new wrapping key is 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 not "well-known" (all zeroes).
|
|
.Pp
|
|
The following properties are set on
|
|
.Ar dataset :
|
|
.Bl -bullet -compact -offset 4n -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 passphrase, 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 passphrase 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 passphrase.
|
|
.
|
|
.Sh OPTIONS
|
|
.Bl -tag -compact -width ".Fl b Ar 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
|
|
.Pp
|
|
.
|
|
.It Fl P Ar PCR Ns Oo Ns Cm \&, Ns Ar PCR Oc Ns …
|
|
Bind the key to space- or comma-separated
|
|
.Ar PCR Ns s
|
|
\(em if they change, the wrapping key will not be able to be unsealed.
|
|
The minimum number of PCRs for a PC TPM is
|
|
.Sy 24 Pq numbered Bq Sy 0 , 23 .
|
|
For most, this is also the maximum.
|
|
.El
|
|
.
|
|
.\" SPDX-License-Identifier: MIT
|
|
.
|
|
.Sh ENVIRONMENT VARIABLES
|
|
.Bl -tag -compact -width 4n
|
|
.It Ev TZPFMS_PASSPHRASE_HELPER
|
|
By default, passphrases are prompted for and read in on the standard output and input streams.
|
|
If
|
|
.Ev TZPFMS_PASSPHRASE_HELPER
|
|
is set and nonempty, it will be run via
|
|
.Pa /bin/ Ns Nm sh Fl c
|
|
to provide each passphrase, instead.
|
|
.Pp
|
|
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:
|
|
.Bl -tag -compact -offset 2n -width ".Li $1"
|
|
.It Li $1
|
|
Pre-formatted noun phrase with all the information below, for use as a prompt
|
|
.\" Passphrase for tarta-zoot
|
|
.\" New passphrase for tarta-zoot (again)
|
|
.It Li $2
|
|
Either the dataset name or the element of the TPM hierarchy being prompted for
|
|
.It Li $3
|
|
.Qq new
|
|
if this is for a new passphrase, otherwise blank
|
|
.It Li $4
|
|
.Qq again
|
|
if it's the second prompt for that passphrase, otherwise blank
|
|
.El
|
|
.Pp
|
|
If the helper doesn't exist
|
|
.Pq the shell exits with Sy 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.
|
|
.
|
|
.
|
|
.El
|
|
.
|
|
.\" SPDX-License-Identifier: MIT
|
|
.
|
|
.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 .
|
|
.
|
|
.\" SPDX-License-Identifier: MIT
|
|
.
|
|
.Sh SPECIAL THANKS
|
|
To all who support further development, in particular:
|
|
.Bl -bullet -offset 4n -compact -width "@"
|
|
.It
|
|
ThePhD
|
|
.It
|
|
Embark Studios
|
|
.It
|
|
Jasper Bekkers
|
|
.It
|
|
EvModder
|
|
.El
|
|
.
|
|
.Sh REPORTING BUGS
|
|
.Lk https:/\&/todo.sr.ht/\(tinabijaczleweli/tzpfms
|
|
.Pp
|
|
.Mt \(tinabijaczleweli/tzpfms@lists.sr.ht ,
|
|
archived at
|
|
.Lk https:/\&/lists.sr.ht/\(tinabijaczleweli/tzpfms .
|
|
.
|
|
.Sh SEE ALSO
|
|
.\" Match this to zfs-tpm2-change-key.8:
|
|
PCR allocations:
|
|
.Lk https:/\&/wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers
|
|
and
|
|
.Lk https:/\&/trustedcomputinggroup.org/wp-content/uploads/PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf ,
|
|
Section 2.3.4 "PCR Usage", Table 1.
|