Debian Codegraph @

src/pins/tpm2/clevis-encrypt-tpm2.1.adoc

raw
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)]