1CLEVIS-ENCRYPT-TPM(1)                                    CLEVIS-ENCRYPT-TPM(1)
2
3
4

NAME

6       clevis-encrypt-tpm2 - Encrypts using a TPM2.0 chip binding policy
7

SYNOPSIS

9       clevis encrypt tpm2 CONFIG < PT > JWE
10

OVERVIEW

12       The clevis encrypt tpm2 command encrypts using a Trusted Platform
13       Module 2.0 (TPM2) chip. Its only argument is the JSON configuration
14       object.
15
16       When using the tpm2 pin, we create a new, cryptographically-strong,
17       random key. This key is encrypted using the TPM2 chip. Then at
18       decryption time, the key is decrypted again using the TPM2 chip.
19
20           $ clevis encrypt tpm2 '{}' < PT > JWE
21
22       The pin has reasonable defaults for its configuration, but a different
23       hierarchy, hash, and key algorithms can be chosen if the defaults used
24       are not suitable:
25
26           $ clevis encrypt tpm2 '{"hash":"sha1","key":"rsa"}' < PT > JWE
27
28       To decrypt the data, simply provide the ciphertext (JWE):
29
30           $ clevis decrypt < JWE > PT
31
32       Note that like other pins no configuration is used for decryption, this
33       is due clevis storing the public and private keys to unseal the TPM2
34       encrypted object in the JWE so clevis can fetch that information from
35       there.
36
37       The pin also supports sealing data to a Platform Configuration
38       Registers (PCR) state. That way the data can only be unsealed if the
39       PCRs hashes values match the policy used when sealing.
40
41       For example, to seal the data to the PCR with index 0 and 1 for the
42       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
47       the PCRs, but a digest can also be provided if the data needs to be
48       sealed with values different to the current ones, by passing the binary
49       hash encoded in base64:
50
51           $ clevis encrypt tpm2 '{"pcr_ids":"0","pcr_digest":"xy7J5svCtqlfM03d1lE5gdoA8MI"}' < PT > JWE
52

THREAT MODEL

54       The Clevis security model relies in the fact that an attacker will not
55       be able to access both the encrypted data and the decryption key.
56
57       For most Clevis pins, the decryption key is not locally stored, so the
58       decryption policy is only satisfied if the decryption key can be
59       remotely accessed. It could for example be stored in a remote server or
60       in a hardware authentication device that has to be plugged into the
61       machine.
62
63       The tpm2 pin is different in this regard, since a key is wrapped by a
64       TPM2 chip that is always present in the machine. This does not mean
65       that there are not use cases for this pin, but it is important to
66       understand the fact that an attacker that has access to both the
67       encrypted data and the local TPM2 chip will be able to decrypt the
68       data.
69

CONFIG

71       This command uses the following configuration properties:
72
73       •   hash (string) : Hash algorithm used in the computation of the
74           object name (default: sha256)
75
76               It must be one of the following:
77
78           •   sha1
79
80           •   sha256
81
82           •   sha384
83
84           •   sha512
85
86           •   sm3_256
87
88       •   key (string) : Algorithm type for the generated key (default: ecc)
89
90               It must be one of the following:
91
92           •   rsa
93
94           •   keyedhash
95
96           •   ecc
97
98           •   symcipher
99
100       •   pcr_bank (string) : PCR algorithm bank to use for policy (default:
101           sha1)
102
103               It must be one of the following:
104
105           •   sha1
106
107           •   sha256
108
109       •   pcr_ids (string) : Comma separated list of PCR used for policy. If
110           not present, no policy is used
111
112       •   pcr_digest (string) : Binary PCR hashes encoded in base64. If not
113           present, the hash values are looked up
114

SEE ALSO

116       clevis-decrypt(1)
117
118
119
120                                  07/19/2023             CLEVIS-ENCRYPT-TPM(1)
Impressum