1CLEVIS-ENCRYPT-TPM2(1)                                  CLEVIS-ENCRYPT-TPM2(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 Mod‐
13       ule 2.0 (TPM2) chip.  Its only argument is the JSON  configuration  ob‐
14       ject.
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  de‐
18       cryption 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  Regis‐
38       ters  (PCR)  state.  That way the data can only be unsealed if the PCRs
39       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  re‐
59       motely  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 ma‐
61       chine.
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 un‐
66       derstand the fact that an attacker that has access to both the encrypt‐
67       ed data and the local TPM2 chip will be able to decrypt the data.
68

CONFIG

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

SEE ALSO

115       clevis-decrypt(1)
116

AUTHORS

118       Javier Martinez Canillas <javierm@redhat.com>.
119
120
121
122                                 November 2017          CLEVIS-ENCRYPT-TPM2(1)