clevis-encrypt-tang.1 2.4 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. .\" Automatically generated by Pandoc 1.19.1
  2. .\"
  3. .TH "CLEVIS\-ENCRYPT\-TANG" "1" "September 2017" "" ""
  4. .hy
  5. .SH NAME
  6. .PP
  7. clevis\-encrypt\-tang \-\- Encrypts using a Tang binding server policy
  8. .SH SYNOPSIS
  9. .PP
  10. \f[C]clevis\ encrypt\ tang\f[] CONFIG < PT > JWE
  11. .SH OVERVIEW
  12. .PP
  13. The \f[C]clevis\ encrypt\ tang\f[] command encrypts using a Tang binding
  14. server policy.
  15. Its only argument is the JSON configuration object.
  16. .PP
  17. Clevis provides support for the Tang network binding server.
  18. Tang provides a stateless, lightweight alternative to escrows.
  19. Encrypting data using the Tang pin works like this:
  20. .IP
  21. .nf
  22. \f[C]
  23. $\ clevis\ encrypt\ tang\ \[aq]{"url":"http://tang.srv"}\[aq]\ <\ PT\ >\ JWE
  24. The\ advertisement\ contains\ the\ following\ signing\ keys:
  25. _OsIk0T\-E2l6qjfdDiwVmidoZjA
  26. Do\ you\ wish\ to\ trust\ these\ keys?\ [ynYN]\ y
  27. \f[]
  28. .fi
  29. .PP
  30. To decrypt the data, just pass it to the \f[C]clevis\ decrypt\f[]
  31. command:
  32. .IP
  33. .nf
  34. \f[C]
  35. $\ clevis\ decrypt\ <\ JWE\ >\ PT
  36. \f[]
  37. .fi
  38. .PP
  39. As you can see above, Tang utilizes a trust\-on\-first\-use workflow.
  40. If you already know the thumbprint of a trusted key, you can specify it
  41. in the configuration at encryption time:
  42. .IP
  43. .nf
  44. \f[C]
  45. $\ cfg=\[aq]{"url":"http://tang.srv","thp":"_OsIk0T\-E2l6qjfdDiwVmidoZjA"}\[aq]
  46. $\ clevis\ encrypt\ tang\ "$cfg"\ <\ PT\ >\ JWE
  47. \f[]
  48. .fi
  49. .PP
  50. Obtaining the thumbprint of a trusted signing key is easy.
  51. If you have access to the Tang server\[aq]s database directory, simply
  52. do:
  53. .IP
  54. .nf
  55. \f[C]
  56. $\ jose\ jwk\ thp\ \-i\ $DBDIR/$SIG.jwk\
  57. \f[]
  58. .fi
  59. .PP
  60. Tang can also perform entirely offline encryption if you pre\-share the
  61. server advertisement.
  62. You can fetch the advertisement with a simple command (just be careful
  63. your network isn\[aq]t compromised!):
  64. .IP
  65. .nf
  66. \f[C]
  67. $\ curl\ \-f\ $URL/adv\ >\ adv.jws
  68. \f[]
  69. .fi
  70. .PP
  71. Once you have the advertisement file, just provide it:
  72. .IP
  73. .nf
  74. \f[C]
  75. $\ clevis\ encrypt\ tang\ \[aq]{"url":...,"adv":"adv.jws"}\[aq]\ <\ PT\ >\ JWE
  76. \f[]
  77. .fi
  78. .SH CONFIG
  79. .PP
  80. This command uses the following configuration properties:
  81. .IP \[bu] 2
  82. \f[C]url\f[] (string) : The base URL of the Tang server (REQUIRED)
  83. .IP \[bu] 2
  84. \f[C]thp\f[] (string) : The thumbprint of a trusted signing key
  85. .IP \[bu] 2
  86. \f[C]adv\f[] (string) : A filename containing a trusted advertisement
  87. .IP \[bu] 2
  88. \f[C]adv\f[] (object) : A trusted advertisement (raw JSON)
  89. .SH SEE ALSO
  90. .PP
  91. \f[C]clevis\-decrypt\f[](1)
  92. .SH AUTHORS
  93. Nathaniel McCallum <npmccallum@redhat.com>.