123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142 |
- .\" 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 choosen 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>.
|