1CLEVIS(1)                                                            CLEVIS(1)
2
3
4

NAME

6       clevis -- Automated decryption policy framework
7

SYNOPSIS

9       clevis COMMAND [OPTIONS]
10

OVERVIEW

12       Clevis  is  a framework for automated decryption policy.  It allows you
13       to define a policy at encryption time that must be  satisfied  for  the
14       data to decrypt.  Once this policy is met, the data is decrypted.
15
16       Clevis is pluggable.  Our plugins are called pins.  The job of a pin is
17       to take a policy as its first argument and plaintext on standard  input
18       and  to  encrypt  the data so that it can be automatically decrypted if
19       the policy is met.  Lets walk through an example.
20

HTTP ESCROW

22       When using the HTTP pin, we  create  a  new,  cryptographically-strong,
23       random key.  This key is stored in a remote HTTP escrow server (using a
24       simple PUT or POST).  Then at decryption time, we attempt to fetch  the
25       key back again in order to decrypt our data.  So, for our configuration
26       we need to pass the URL to the key location:
27
28              $ clevis encrypt http '{"url":"https://escrow.srv/1234"}' < PT > JWE
29
30       To decrypt the data, simply provide the ciphertext (JWE):
31
32              $ clevis decrypt < JWE > PLAINTEXT
33
34       Notice that we did not pass any configuration during  decryption.   The
35       decrypt  command  extracted  the URL (and possibly other configuration)
36       from the JWE object, fetched the encryption key  from  the  escrow  and
37       performed decryption.
38
39       For more information, see clevis-encrypt-http(1).
40

TANG BINDING

42       Clevis provides support for the Tang network binding server.  Tang pro‐
43       vides a stateless, lightweight alternative to escrows.  Encrypting data
44       using the Tang pin works much like our HTTP pin above:
45
46              $ clevis encrypt tang '{"url":"http://tang.srv"}' < PT > JWE
47              The advertisement contains the following signing keys:
48
49              _OsIk0T-E2l6qjfdDiwVmidoZjA
50
51              Do you wish to trust these keys? [ynYN] y
52
53       As you can see above, Tang utilizes a trust-on-first-use workflow.  Al‐
54       ternatively, Tang  can  perform  entirely  offline  encryption  if  you
55       pre-share  the  server  advertisment.   Decryption,  too works like our
56       first example:
57
58              $ clevis decrypt < JWE > PT
59
60       For more information, see clevis-encrypt-tang(1).
61

TPM2 BINDING

63       Clevis provides support to encrypt a key in a Trusted  Platform  Module
64       2.0 (TPM2) chip.  The cryptographically-strong, random key used for en‐
65       cryption is encrypted using the TPM2 chip, and then at decryption  time
66       is  decrypted  using  the  TPM2  to  allow clevis to decrypt the secret
67       stored in the JWE.
68
69       Encrypting data using the tpm2 pin works the same than  the  pins  men‐
70       tioned above:
71
72              $ clevis encrypt tpm2 '{}' < PT > JWE
73
74       The  pin has reasonable defaults for its configuration, but a different
75       hierarchy, hash, and key algorithms can be chosen if the defaults  used
76       are not suitable.
77
78       Decryption  also  works similar to other pins, only the JWE needs to be
79       provided:
80
81              $ clevis decrypt < JWE > PT
82
83       Note that like other pins no configuration is used for decryption, this
84       is  due  clevis  storing the public and private keys to unseal the TPM2
85       encrypted object in the JWE so clevis can fetch that  information  from
86       there.
87
88       For more information see clevis-encrypt-tpm2(1).
89

SHAMIR'S SECRET SHARING

91       Clevis  provides a way to mix pins together to create sophisticated un‐
92       locking and high availability policies.  This is accomplished by  using
93       an algorithm called Shamir's Secret Sharing (SSS).
94
95       SSS  is  a thresholding scheme.  It creates a key and divides it into a
96       number of pieces.  Each piece is encrypted using another pin  (possibly
97       even  SSS  recursively).  Additionally, you define the threshold t.  If
98       at least t pieces can be decrypted, then the encryption key can be  re‐
99       covered and decryption can succeed.
100
101       For example, let's create a high-availability setup using Tang:
102
103              $ cfg='{"t":1,"pins":{"tang":[{"url":...},{"url":...}]}}'
104              $ clevis encrypt sss "$cfg" < PT > JWE
105
106       In  this  policy,  we  are declaring that we have a threshold of 1, but
107       that there are multiple key fragments encrypted  using  different  Tang
108       servers.   Since our threshold is 1, so long as any of the Tang servers
109       are available, decryption will succeed.  As always, decryption is  sim‐
110       ply:
111
112              $ clevis decrypt < JWE > PT
113
114       For more information, see clevis-encrypt-tang(1).
115

LUKS BINDING

117       Clevis  can  be  used to bind an existing LUKS volume to its automation
118       policy.  This is accomplished with a simple command:
119
120              $ clevis luks bind -d /dev/sda tang '{"url":...}'
121
122       This command performs four steps:
123
124       1. Creates a new key with the same entropy as the LUKS master key.
125
126       2. Encrypts the new key with Clevis.
127
128       3. Stores the Clevis JWE in the LUKS header with LUKSMeta.
129
130       4. Enables the new key for use with LUKS.
131
132       This disk can now be unlocked with your existing password  as  well  as
133       with  the  Clevis  policy.  Clevis provides two unlockers for LUKS vol‐
134       umes.  First, we provide integration with Dracut to  automatically  un‐
135       lock  your  root volume during early boot.  Second, we provide integra‐
136       tion with UDisks2 to automatically unlock your removable media in  your
137       desktop session.
138
139       For more information, see clevis-luks-bind(1).
140

SEE ALSO

142       clevis-encrypt-http(1), clevis-encrypt-tang(1), clevis-encrypt-tpm2(1),
143       clevis-encrypt-sss(1), clevis-luks-bind(1), clevis-decrypt(1)
144

AUTHORS

146       Nathaniel McCallum <npmccallum@redhat.com>.
147
148
149
150                                 Sepember 2017                       CLEVIS(1)
Impressum