clevis-encrypt-sss.1 2.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071
  1. .\" Automatically generated by Pandoc 1.19.1
  2. .\"
  3. .TH "CLEVIS\-ENCRYPT\-SSS" "1" "September 2017" "" ""
  4. .hy
  5. .SH NAME
  6. .PP
  7. clevis\-encrypt\-sss \-\- Encrypts using a Shamir\[aq]s Secret Sharing
  8. policy
  9. .SH SYNOPSIS
  10. .PP
  11. \f[C]clevis\ encrypt\ sss\f[] CONFIG < PT > JWE
  12. .SH OVERVIEW
  13. .PP
  14. The \f[C]clevis\ encrypt\ sss\f[] command encrypts using a Shamir\[aq]s
  15. Secret Sharing policy.
  16. Its only argument is the JSON configuration object.
  17. .PP
  18. Shamir\[aq]s Secret Sharing (SSS) provides a way to mix pins together to
  19. create sophisticated unlocking and high availability policies.
  20. SSS is a thresholding scheme.
  21. It creates a key and divides it into a number of pieces.
  22. Each piece is encrypted using another pin (possibly even SSS
  23. recursively).
  24. Additionally, you define the threshold \f[C]t\f[].
  25. If at least \f[C]t\f[] pieces can be decrypted, then the encryption key
  26. can be recovered and decryption can succeed.
  27. .PP
  28. For example, let\[aq]s create a high\-availability setup using Tang:
  29. .IP
  30. .nf
  31. \f[C]
  32. $\ cfg=\[aq]{"t":1,"pins":{"tang":[{"url":...},{"url":...}]}}\[aq]
  33. $\ clevis\ encrypt\ sss\ "$cfg"\ <\ PT\ >\ JWE
  34. \f[]
  35. .fi
  36. .PP
  37. In this policy, we are declaring that we have a threshold of 1, but that
  38. there are multiple key fragments encrypted using different Tang servers.
  39. Since our threshold is 1, so long as any of the Tang servers are
  40. available, decryption will succeed.
  41. As always, decryption is simply:
  42. .IP
  43. .nf
  44. \f[C]
  45. $\ clevis\ decrypt\ <\ JWE\ >\ PT
  46. \f[]
  47. .fi
  48. .SH CONFIG
  49. .PP
  50. This command uses the following configuration properties:
  51. .IP \[bu] 2
  52. \f[C]t\f[] (integer) : Number of pins required for decryption (REQUIRED)
  53. .IP \[bu] 2
  54. \f[C]pins\f[] (object) : Pins used for encrypting fragments (REQUIRED)
  55. .PP
  56. The format of the \f[C]pins\f[] property is as follows:
  57. .IP
  58. .nf
  59. \f[C]
  60. {PIN:CFG,...}\ OR\ {PIN:[CFG,CFG,...],...}
  61. \f[]
  62. .fi
  63. .PP
  64. When the list version of the format is used, multiple pins of that type
  65. will receive key fragments.
  66. .SH SEE ALSO
  67. .PP
  68. \f[C]clevis\-encrypt\-http\f[](1), \f[C]clevis\-encrypt\-tang\f[](1),
  69. \f[C]clevis\-decrypt\f[](1)
  70. .SH AUTHORS
  71. Nathaniel McCallum <npmccallum@redhat.com>.