clevis/doc/clevis-encrypt-tpm2.1

.\" Automatically generated by Pandoc 1.19.1
.\"
.TH "CLEVIS\-ENCRYPT\-TPM2" "1" "November 2017" "" ""
.hy
.SH NAME
.PP
clevis\-encrypt\-tpm2 \-\- Encrypts using a TPM2.0 chip binding policy
.SH SYNOPSIS
.PP
\f[C]clevis\ encrypt\ tpm2\f[] CONFIG < PT > JWE
.SH OVERVIEW
.PP
The \f[C]clevis\ encrypt\ tpm2\f[] command encrypts using a Trusted
Platform Module 2.0 (TPM2) chip.
Its only argument is the JSON configuration object.
.PP
When using the tpm2 pin, we create a new, cryptographically\-strong,
random key.
This key is encrypted using the TPM2 chip.
Then at decryption time, the key is decrypted again using the TPM2 chip.
.IP
.nf
\f[C]
$\ clevis\ encrypt\ tpm2\ \[aq]{}\[aq]\ <\ PT\ >\ JWE
\f[]
.fi
.PP
The pin has reasonable defaults for its configuration, but a different
hierarchy, hash, and key algorithms can be chosen if the defaults used
are not suitable:
.IP
.nf
\f[C]
$\ clevis\ encrypt\ tpm2\ \[aq]{"hash":"sha1","key":"rsa"}\[aq]\ <\ PT\ >\ JWE
\f[]
.fi
.PP
To decrypt the data, simply provide the ciphertext (JWE):
.IP
.nf
\f[C]
$\ clevis\ decrypt\ <\ JWE\ >\ PT
\f[]
.fi
.PP
Note that like other pins no configuration is used for decryption, this
is due clevis storing the public and private keys to unseal the TPM2
encrypted object in the JWE so clevis can fetch that information from
there.
.PP
The pin also supports sealing data to a Platform Configuration Registers
(PCR) state.
That way the data can only be unsealed if the PCRs hashes values match
the policy used when sealing.
.PP
For example, to seal the data to the PCR with index 0 and 1 for the SHA1
bank:
.IP
.nf
\f[C]
$\ clevis\ encrypt\ tpm2\ \[aq]{"pcr_bank":"sha1","pcr_ids":"0,1"}\[aq]\ <\ PT\ >\ JWE
\f[]
.fi
.PP
The PCR digest values are looked up from the current hash values for the
PCRs, but a digest can also be provided if the data needs to be sealed
with values different to the current ones, by passing the binary hash
encoded in base64:
.IP
.nf
\f[C]
$\ clevis\ encrypt\ tpm2\ \[aq]{"pcr_ids":"0","pcr_digest":"xy7J5svCtqlfM03d1lE5gdoA8MI"}\[aq]\ <\ PT\ >\ JWE
\f[]
.fi
.SH Threat model
.PP
The Clevis security model relies in the fact that an attacker will not
be able to access both the encrypted data and the decryption key.
.PP
For most Clevis pins, the decryption key is not locally stored, so the
decryption policy is only satisfied if the decryption key can be
remotely accessed.
It could for example be stored in a remote server or in a hardware
authentication device that has to be plugged into the machine.
.PP
The tpm2 pin is different in this regard, since a key is wrapped by a
TPM2 chip that is always present in the machine.
This does not mean that there are not use cases for this pin, but it is
important to understand the fact that an attacker that has access to
both the encrypted data and the local TPM2 chip will be able to decrypt
the data.
.SH CONFIG
.PP
This command uses the following configuration properties:
.IP \[bu] 2
\f[C]hash\f[] (string) : Hash algorithm used in the computation of the
object name (default: sha256)
.PP
It must be one of the following:
.IP \[bu] 2
\f[C]sha1\f[]
.IP \[bu] 2
\f[C]sha256\f[]
.IP \[bu] 2
\f[C]sha384\f[]
.IP \[bu] 2
\f[C]sha512\f[]
.IP \[bu] 2
\f[C]sm3_256\f[]
.IP \[bu] 2
\f[C]key\f[] (string) : Algorithm type for the generated key (default:
ecc)
.PP
It must be one of the following:
.IP \[bu] 2
\f[C]rsa\f[]
.IP \[bu] 2
\f[C]keyedhash\f[]
.IP \[bu] 2
\f[C]ecc\f[]
.IP \[bu] 2
\f[C]symcipher\f[]
.IP \[bu] 2
\f[C]pcr_bank\f[] (string) : PCR algorithm bank to use for policy
(default: sha1)
.PP
It must be one of the following:
.IP \[bu] 2
\f[C]sha1\f[]
.IP \[bu] 2
\f[C]sha256\f[]
.IP \[bu] 2
\f[C]pcr_ids\f[] (string) : Comma separated list of PCR used for policy.
If not present, no policy is used
.IP \[bu] 2
\f[C]pcr_digest\f[] (string) : Binary PCR hashes encoded in base64.
If not present, the hash values are looked up
.SH SEE ALSO
.PP
\f[C]clevis\-decrypt\f[](1)
.SH AUTHORS
Javier Martinez Canillas <javierm@redhat.com>.