clevis.1.adoc 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123
  1. CLEVIS(1)
  2. =========
  3. :doctype: manpage
  4. == NAME
  5. clevis - Automated decryption policy framework
  6. == SYNOPSIS
  7. *clevis* COMMAND [OPTIONS]
  8. == OVERVIEW
  9. Clevis is a framework for automated decryption policy. It allows you to define
  10. a policy at encryption time that must be satisfied for the data to decrypt.
  11. Once this policy is met, the data is decrypted.
  12. Clevis is pluggable. Our plugins are called pins. The job of a pin is to
  13. take a policy as its first argument and plaintext on standard input and to
  14. encrypt the data so that it can be automatically decrypted if the policy is
  15. met. Lets walk through an example.
  16. == TANG BINDING
  17. Clevis provides support for the Tang network binding server. Tang provides
  18. a stateless, lightweight alternative to escrows. Encrypting data using the Tang
  19. pin works much like our HTTP pin above:
  20. $ clevis encrypt tang '{"url":"http://tang.srv"}' < PT > JWE
  21. The advertisement contains the following signing keys:
  22. _OsIk0T-E2l6qjfdDiwVmidoZjA
  23. Do you wish to trust these keys? [ynYN] y
  24. As you can see above, Tang utilizes a trust-on-first-use workflow.
  25. Alternatively, Tang can perform entirely offline encryption if you pre-share
  26. the server advertisement. Decryption, too works like our first example:
  27. $ clevis decrypt < JWE > PT
  28. For more information, see link:clevis-encrypt-tang.1.adoc[*clevis-encrypt-tang*(1)].
  29. == TPM2 BINDING
  30. Clevis provides support to encrypt a key in a Trusted Platform Module 2.0 (TPM2)
  31. chip. The cryptographically-strong, random key used for encryption is encrypted
  32. using the TPM2 chip, and then at decryption time is decrypted using the TPM2 to
  33. allow clevis to decrypt the secret stored in the JWE.
  34. Encrypting data using the tpm2 pin works the same than the pins mentioned above:
  35. $ clevis encrypt tpm2 '{}' < PT > JWE
  36. The pin has reasonable defaults for its configuration, but a different hierarchy,
  37. hash, and key algorithms can be chosen if the defaults used are not suitable.
  38. Decryption also works similar to other pins, only the JWE needs to be provided:
  39. $ clevis decrypt < JWE > PT
  40. Note that like other pins no configuration is used for decryption, this is due
  41. clevis storing the public and private keys to unseal the TPM2 encrypted object
  42. in the JWE so clevis can fetch that information from there.
  43. For more information see link:clevis-encrypt-tpm2.1.adoc[*clevis-encrypt-tpm2*(1)].
  44. == SHAMIR'S SECRET SHARING
  45. Clevis provides a way to mix pins together to create sophisticated unlocking
  46. and high availability policies. This is accomplished by using an algorithm
  47. called Shamir's Secret Sharing (SSS).
  48. SSS is a thresholding scheme. It creates a key and divides it into a number of
  49. pieces. Each piece is encrypted using another pin (possibly even SSS
  50. recursively). Additionally, you define the threshold *t*. If at least *t*
  51. pieces can be decrypted, then the encryption key can be recovered and
  52. decryption can succeed.
  53. For example, let's create a high-availability setup using Tang:
  54. $ cfg='{"t":1,"pins":{"tang":[{"url":...},{"url":...}]}}'
  55. $ clevis encrypt sss "$cfg" < PT > JWE
  56. In this policy, we are declaring that we have a threshold of 1, but that there
  57. are multiple key fragments encrypted using different Tang servers. Since our
  58. threshold is 1, so long as any of the Tang servers are available, decryption
  59. will succeed. As always, decryption is simply:
  60. $ clevis decrypt < JWE > PT
  61. For more information, see link:clevis-encrypt-tang.1.adoc[*clevis-encrypt-tang*(1)].
  62. == LUKS BINDING
  63. Clevis can be used to bind an existing LUKS volume to its automation policy.
  64. This is accomplished with a simple command:
  65. $ clevis luks bind -d /dev/sda tang '{"url":...}'
  66. This command performs four steps:
  67. 1. Creates a new key with the same entropy as the LUKS master key.
  68. 2. Encrypts the new key with Clevis.
  69. 3. Stores the Clevis JWE in the LUKS header.
  70. 4. Enables the new key for use with LUKS.
  71. This disk can now be unlocked with your existing password as well as with
  72. the Clevis policy. Clevis provides two unlockers for LUKS volumes. First,
  73. we provide integration with Dracut to automatically unlock your root volume
  74. during early boot. Second, we provide integration with UDisks2 to
  75. automatically unlock your removable media in your desktop session.
  76. For more information, see link:clevis-luks-bind.1.adoc[*clevis-luks-bind*(1)].
  77. == SEE ALSO
  78. link:clevis-encrypt-tang.1.adoc[*clevis-encrypt-tang*(1)],
  79. link:clevis-encrypt-tpm2.1.adoc[*clevis-encrypt-tpm2*(1)],
  80. link:clevis-encrypt-sss.1.adoc[*clevis-encrypt-sss*(1)],
  81. link:clevis-luks-bind.1.adoc[*clevis-luks-bind*(1)],
  82. link:clevis-decrypt.1.adoc[*clevis-decrypt*(1)]