clevis(1)

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 to
13       define a policy at encryption time that must be satisfied for the data
14       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

TANG BINDING

22       Clevis provides support for the Tang network binding server. Tang
23       provides a stateless, lightweight alternative to escrows. Encrypting
24       data using the Tang pin works much like our HTTP pin above:
25
26           $ clevis encrypt tang '{"url":"http://tang.srv"}' < PT > JWE
27           The advertisement contains the following signing keys:
28
29           _OsIk0T-E2l6qjfdDiwVmidoZjA
30
31           Do you wish to trust these keys? [ynYN] y
32
33       As you can see above, Tang utilizes a trust-on-first-use workflow.
34       Alternatively, Tang can perform entirely offline encryption if you
35       pre-share the server advertisement. Decryption, too works like our
36       first example:
37
38           $ clevis decrypt < JWE > PT
39
40       For more information, see clevis-encrypt-tang(1).
41

TPM2 BINDING

43       Clevis provides support to encrypt a key in a Trusted Platform Module
44       2.0 (TPM2) chip. The cryptographically-strong, random key used for
45       encryption is encrypted using the TPM2 chip, and then at decryption
46       time is decrypted using the TPM2 to allow clevis to decrypt the secret
47       stored in the JWE.
48
49       Encrypting data using the tpm2 pin works the same than the pins
50       mentioned above:
51
52           $ clevis encrypt tpm2 '{}' < PT > JWE
53
54       The pin has reasonable defaults for its configuration, but a different
55       hierarchy, hash, and key algorithms can be chosen if the defaults used
56       are not suitable.
57
58       Decryption also works similar to other pins, only the JWE needs to be
59       provided:
60
61           $ clevis decrypt < JWE > PT
62
63       Note that like other pins no configuration is used for decryption, this
64       is due clevis storing the public and private keys to unseal the TPM2
65       encrypted object in the JWE so clevis can fetch that information from
66       there.
67
68       For more information see clevis-encrypt-tpm2(1).
69

SHAMIR’S SECRET SHARING

71       Clevis provides a way to mix pins together to create sophisticated
72       unlocking and high availability policies. This is accomplished by using
73       an algorithm called Shamir’s Secret Sharing (SSS).
74
75       SSS is a thresholding scheme. It creates a key and divides it into a
76       number of pieces. Each piece is encrypted using another pin (possibly
77       even SSS recursively). Additionally, you define the threshold t. If at
78       least t pieces can be decrypted, then the encryption key can be
79       recovered and decryption can succeed.
80
81       For example, let’s create a high-availability setup using Tang:
82
83           $ cfg='{"t":1,"pins":{"tang":[{"url":...},{"url":...}]}}'
84           $ clevis encrypt sss "$cfg" < PT > JWE
85
86       In this policy, we are declaring that we have a threshold of 1, but
87       that there are multiple key fragments encrypted using different Tang
88       servers. Since our threshold is 1, so long as any of the Tang servers
89       are available, decryption will succeed. As always, decryption is
90       simply:
91
92           $ clevis decrypt < JWE > PT
93
94       For more information, see clevis-encrypt-tang(1).
95

LUKS BINDING

97       Clevis can be used to bind an existing LUKS volume to its automation
98       policy. This is accomplished with a simple command:
99
100           $ clevis luks bind -d /dev/sda tang '{"url":...}'
101
102       This command performs four steps:
103
104        1. Creates a new key with the same entropy as the LUKS master key.
105
106        2. Encrypts the new key with Clevis.
107
108        3. Stores the Clevis JWE in the LUKS header.
109
110        4. Enables the new key for use with LUKS.
111
112       This disk can now be unlocked with your existing password as well as
113       with the Clevis policy. Clevis provides two unlockers for LUKS volumes.
114       First, we provide integration with Dracut to automatically unlock your
115       root volume during early boot. Second, we provide integration with
116       UDisks2 to automatically unlock your removable media in your desktop
117       session.
118
119       For more information, see clevis-luks-bind(1).
120