| 1 |
CLEVIS-ENCRYPT-TPM2(1) |
| 2 |
====================== |
| 3 |
:doctype: manpage |
| 4 |
|
| 5 |
|
| 6 |
== NAME |
| 7 |
|
| 8 |
clevis-encrypt-tpm2 - Encrypts using a TPM2.0 chip binding policy |
| 9 |
|
| 10 |
== SYNOPSIS |
| 11 |
|
| 12 |
*clevis encrypt tpm2* CONFIG < PT > JWE |
| 13 |
|
| 14 |
== OVERVIEW |
| 15 |
|
| 16 |
The *clevis encrypt tpm2* command encrypts using a Trusted Platform Module 2.0 |
| 17 |
(TPM2) chip. Its only argument is the JSON configuration object. |
| 18 |
|
| 19 |
When using the tpm2 pin, we create a new, cryptographically-strong, random key. |
| 20 |
This key is encrypted using the TPM2 chip. |
| 21 |
Then at decryption time, the key is decrypted again using the TPM2 chip. |
| 22 |
|
| 23 |
$ clevis encrypt tpm2 '{}' < PT > JWE |
| 24 |
|
| 25 |
The pin has reasonable defaults for its configuration, but a different hierarchy, |
| 26 |
hash, and key algorithms can be chosen if the defaults used are not suitable: |
| 27 |
|
| 28 |
$ clevis encrypt tpm2 '{"hash":"sha1","key":"rsa"}' < PT > JWE |
| 29 |
|
| 30 |
To decrypt the data, simply provide the ciphertext (JWE): |
| 31 |
|
| 32 |
$ clevis decrypt < JWE > PT |
| 33 |
|
| 34 |
Note that like other pins no configuration is used for decryption, this is due |
| 35 |
clevis storing the public and private keys to unseal the TPM2 encrypted object |
| 36 |
in the JWE so clevis can fetch that information from there. |
| 37 |
|
| 38 |
The pin also supports sealing data to a Platform Configuration Registers (PCR) |
| 39 |
state. That way the data can only be unsealed if the PCRs hashes values match |
| 40 |
the policy used when sealing. |
| 41 |
|
| 42 |
For example, to seal the data to the PCR with index 0 and 1 for the SHA1 bank: |
| 43 |
|
| 44 |
$ clevis encrypt tpm2 '{"pcr_bank":"sha1","pcr_ids":"0,1"}' < PT > JWE |
| 45 |
|
| 46 |
The PCR digest values are looked up from the current hash values for the PCRs, |
| 47 |
but a digest can also be provided if the data needs to be sealed with values |
| 48 |
different to the current ones, by passing the binary hash encoded in base64: |
| 49 |
|
| 50 |
$ clevis encrypt tpm2 '{"pcr_ids":"0","pcr_digest":"xy7J5svCtqlfM03d1lE5gdoA8MI"}' < PT > JWE |
| 51 |
|
| 52 |
== Threat model |
| 53 |
|
| 54 |
The Clevis security model relies in the fact that an attacker will not be able to |
| 55 |
access both the encrypted data and the decryption key. |
| 56 |
|
| 57 |
For most Clevis pins, the decryption key is not locally stored, so the decryption |
| 58 |
policy is only satisfied if the decryption key can be remotely accessed. It could |
| 59 |
for example be stored in a remote server or in a hardware authentication device |
| 60 |
that has to be plugged into the machine. |
| 61 |
|
| 62 |
The tpm2 pin is different in this regard, since a key is wrapped by a TPM2 chip |
| 63 |
that is always present in the machine. This does not mean that there are not use |
| 64 |
cases for this pin, but it is important to understand the fact that an attacker |
| 65 |
that has access to both the encrypted data and the local TPM2 chip will be able |
| 66 |
to decrypt the data. |
| 67 |
|
| 68 |
== CONFIG |
| 69 |
|
| 70 |
This command uses the following configuration properties: |
| 71 |
|
| 72 |
* *hash* (string) : |
| 73 |
Hash algorithm used in the computation of the object name (default: sha256) |
| 74 |
|
| 75 |
It must be one of the following: |
| 76 |
|
| 77 |
- *sha1* |
| 78 |
- *sha256* |
| 79 |
- *sha384* |
| 80 |
- *sha512* |
| 81 |
- *sm3_256* |
| 82 |
|
| 83 |
* *key* (string) : |
| 84 |
Algorithm type for the generated key (default: ecc) |
| 85 |
|
| 86 |
It must be one of the following: |
| 87 |
|
| 88 |
- *rsa* |
| 89 |
- *keyedhash* |
| 90 |
- *ecc* |
| 91 |
- *symcipher* |
| 92 |
|
| 93 |
* *pcr_bank* (string) : |
| 94 |
PCR algorithm bank to use for policy (default: first supported by TPM) |
| 95 |
|
| 96 |
Examples of PCR algorithm banks, support depends on TPM chip: |
| 97 |
|
| 98 |
- *sha1* |
| 99 |
- *sha256* |
| 100 |
|
| 101 |
For the full list of algorithms supported by the TPM chip check output of |
| 102 |
`tpm2_getcap pcrs` and use the algorithm which shows non-empty list of PCR |
| 103 |
numbers. |
| 104 |
|
| 105 |
* *pcr_ids* (string) : |
| 106 |
Comma separated list of PCR used for policy. If not present, no policy is used |
| 107 |
|
| 108 |
* *pcr_digest* (string) : |
| 109 |
Binary PCR hashes encoded in base64. If not present, the hash values are looked up |
| 110 |
|
| 111 |
== SEE ALSO |
| 112 |
|
| 113 |
link:clevis-decrypt.1.adoc[*clevis-decrypt*(1)] |