clevis/doc/clevis.1

.\" Automatically generated by Pandoc 1.19.1
.\"
.TH "CLEVIS" "1" "Sepember 2017" "" ""
.hy
.SH NAME
.PP
clevis \-\- Automated decryption policy framework
.SH SYNOPSIS
.PP
\f[C]clevis\f[] COMMAND [OPTIONS]
.SH OVERVIEW
.PP
Clevis is a framework for automated decryption policy.
It allows you to define a policy at encryption time that must be
satisfied for the data to decrypt.
Once this policy is met, the data is decrypted.
.PP
Clevis is pluggable.
Our plugins are called pins.
The job of a pin is to take a policy as its first argument and plaintext
on standard input and to encrypt the data so that it can be
automatically decrypted if the policy is met.
Lets walk through an example.
.SH HTTP ESCROW
.PP
When using the HTTP pin, we create a new, cryptographically\-strong,
random key.
This key is stored in a remote HTTP escrow server (using a simple PUT or
POST).
Then at decryption time, we attempt to fetch the key back again in order
to decrypt our data.
So, for our configuration we need to pass the URL to the key location:
.IP
.nf
\f[C]
$\ clevis\ encrypt\ http\ \[aq]{"url":"https://escrow.srv/1234"}\[aq]\ <\ PT\ >\ JWE
\f[]
.fi
.PP
To decrypt the data, simply provide the ciphertext (JWE):
.IP
.nf
\f[C]
$\ clevis\ decrypt\ <\ JWE\ >\ PLAINTEXT
\f[]
.fi
.PP
Notice that we did not pass any configuration during decryption.
The decrypt command extracted the URL (and possibly other configuration)
from the JWE object, fetched the encryption key from the escrow and
performed decryption.
.PP
For more information, see \f[C]clevis\-encrypt\-http\f[](1).
.SH TANG BINDING
.PP
Clevis provides support for the Tang network binding server.
Tang provides a stateless, lightweight alternative to escrows.
Encrypting data using the Tang pin works much like our HTTP pin above:
.IP
.nf
\f[C]
$\ clevis\ encrypt\ tang\ \[aq]{"url":"http://tang.srv"}\[aq]\ <\ PT\ >\ JWE
The\ advertisement\ contains\ the\ following\ signing\ keys:

_OsIk0T\-E2l6qjfdDiwVmidoZjA

Do\ you\ wish\ to\ trust\ these\ keys?\ [ynYN]\ y
\f[]
.fi
.PP
As you can see above, Tang utilizes a trust\-on\-first\-use workflow.
Alternatively, Tang can perform entirely offline encryption if you
pre\-share the server advertisement.
Decryption, too works like our first example:
.IP
.nf
\f[C]
$\ clevis\ decrypt\ <\ JWE\ >\ PT
\f[]
.fi
.PP
For more information, see \f[C]clevis\-encrypt\-tang\f[](1).
.SH SHAMIR\[aq]S SECRET SHARING
.PP
Clevis provides a way to mix pins together to create sophisticated
unlocking and high availability policies.
This is accomplished by using an algorithm called Shamir\[aq]s Secret
Sharing (SSS).
.PP
SSS is a thresholding scheme.
It creates a key and divides it into a number of pieces.
Each piece is encrypted using another pin (possibly even SSS
recursively).
Additionally, you define the threshold \f[C]t\f[].
If at least \f[C]t\f[] pieces can be decrypted, then the encryption key
can be recovered and decryption can succeed.
.PP
For example, let\[aq]s create a high\-availability setup using Tang:
.IP
.nf
\f[C]
$\ cfg=\[aq]{"t":1,"pins":{"tang":[{"url":...},{"url":...}]}}\[aq]
$\ clevis\ encrypt\ sss\ "$cfg"\ <\ PT\ >\ JWE
\f[]
.fi
.PP
In this policy, we are declaring that we have a threshold of 1, but that
there are multiple key fragments encrypted using different Tang servers.
Since our threshold is 1, so long as any of the Tang servers are
available, decryption will succeed.
As always, decryption is simply:
.IP
.nf
\f[C]
$\ clevis\ decrypt\ <\ JWE\ >\ PT
\f[]
.fi
.PP
For more information, see \f[C]clevis\-encrypt\-tang\f[](1).
.SH LUKS BINDING
.PP
Clevis can be used to bind an existing LUKS volume to its automation
policy.
This is accomplished with a simple command:
.IP
.nf
\f[C]
$\ clevis\ luks\ bind\ \-d\ /dev/sda\ tang\ \[aq]{"url":...}\[aq]
\f[]
.fi
.PP
This command performs four steps:
.IP "1." 3
Creates a new key with the same entropy as the LUKS master key.
.IP "2." 3
Encrypts the new key with Clevis.
.IP "3." 3
Stores the Clevis JWE in the LUKS header with LUKSMeta.
.IP "4." 3
Enables the new key for use with LUKS.
.PP
This disk can now be unlocked with your existing password as well as
with the Clevis policy.
Clevis provides two unlockers for LUKS volumes.
First, we provide integration with Dracut to automatically unlock your
root volume during early boot.
Second, we provide integration with UDisks2 to automatically unlock your
removable media in your desktop session.
.PP
For more information, see \f[C]clevis\-luks\-bind\f[](1).
.SH SEE ALSO
.PP
\f[C]clevis\-encrypt\-http\f[](1), \f[C]clevis\-encrypt\-tang\f[](1),
\f[C]clevis\-encrypt\-sss\f[](1), \f[C]clevis\-luks\-bind\f[](1),
\f[C]clevis\-decrypt\f[](1)
.SH AUTHORS
Nathaniel McCallum <npmccallum@redhat.com>.