1CLEVIS(1) CLEVIS(1)
2
6 clevis -- Automated decryption policy framework
7
9 clevis COMMAND [OPTIONS]
10
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 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
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 $ clevis encrypt http '{"url":"https://escrow.srv/1234"}' < PT > JWE
29 To decrypt the data, simply provide the ciphertext (JWE):
31 $ clevis decrypt < JWE > PLAINTEXT
33 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 For more information, see clevis-encrypt-http(1).
40
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 $ clevis encrypt tang '{"url":"http://tang.srv"}' < PT > JWE
47 The advertisement contains the following signing keys:
48 _OsIk0T-E2l6qjfdDiwVmidoZjA
50 Do you wish to trust these keys? [ynYN] y
52 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 $ clevis decrypt < JWE > PT
59 For more information, see clevis-encrypt-tang(1).
61
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 Encrypting data using the tpm2 pin works the same than the pins men‐
70 tioned above:
71 $ clevis encrypt tpm2 '{}' < PT > JWE
73 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 Decryption also works similar to other pins, only the JWE needs to be
79 provided:
80 $ clevis decrypt < JWE > PT
82 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 For more information see clevis-encrypt-tpm2(1).
89
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 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 For example, let's create a high-availability setup using Tang:
102 $ cfg='{"t":1,"pins":{"tang":[{"url":...},{"url":...}]}}'
104 $ clevis encrypt sss "$cfg" < PT > JWE
105 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 $ clevis decrypt < JWE > PT
113 For more information, see clevis-encrypt-tang(1).
115
117 Clevis can be used to bind an existing LUKS volume to its automation
118 policy. This is accomplished with a simple command:
119 $ clevis luks bind -d /dev/sda tang '{"url":...}'
121 This command performs four steps:
123 1. Creates a new key with the same entropy as the LUKS master key.
125 2. Encrypts the new key with Clevis.
127 3. Stores the Clevis JWE in the LUKS header with LUKSMeta.
129 4. Enables the new key for use with LUKS.
131 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 For more information, see clevis-luks-bind(1).
140
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
146 Nathaniel McCallum <npmccallum@redhat.com>.
147 Sepember 2017 CLEVIS(1)