tang.8.adoc 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143
  1. tang(8)
  2. =======
  3. :doctype: manpage
  4. == NAME
  5. tang - Network-Based Cryptographic Binding Server
  6. == OVERVIEW
  7. Tang is a service for binding cryptographic keys to network presence. It
  8. offers a secure, stateless, anonymous alternative to key escrow services.
  9. The Tang project arose as a tool to help the automation of decryption.
  10. Existing mechanisms predominantly use key escrow systems where a client
  11. encrypts some data with a symmetric key and stores the symmetric key in a
  12. remote server for later retrieval. The desired goal of this setup is that the
  13. client can automatically decrypt the data when it is able to contact the
  14. escrow server and fetch the key.
  15. However, escrow servers have many additional requirements, including
  16. authentication (so that clients can't get keys they aren't supposed to have)
  17. and transport encryption (so that attackers listening on the network can't
  18. eavesdrop on the keys in transit).
  19. Tang avoids this complexity. Instead of storing a symmetric key remotely,
  20. the client performs an asymmetric key exchange with the Tang server. Since
  21. the Tang server doesn't store or transport symmetric keys, neither
  22. authentication nor encryption are required. Thus, Tang is completely stateless
  23. and zero-configuration. Further, clients can be completely anonymous.
  24. Tang does not provide a client. But it does export a simple REST API and
  25. it transfers only standards compliant JSON Object Signing and Encryption
  26. (JOSE) objects, allowing you to create your own clients using off the shelf
  27. components. For an off-the-shelf automated encryption framework with support
  28. for Tang, see the Clevis project. For the full technical details of the Tang
  29. protocol, see the Tang project's homepage.
  30. == GETTING STARTED
  31. Getting a Tang server up and running is simple:
  32. $ sudo systemctl enable tangd.socket --now
  33. That's it. The server is now running with a fresh set of cryptographic keys
  34. and will automatically start on the next reboot.
  35. == CONFIGURATION
  36. Tang intends to be a minimal network service and therefore does not have any
  37. configuration. To adjust the network settings, you can override the
  38. *tangd.socket* unit file using the standard systemd mechanisms. See
  39. link:systemd.unit.5.adoc[*systemd.unit*(5)] and link:systemd.socket.5.adoc[*systemd.socket*(5)] for more information.
  40. == KEY ROTATION
  41. In order to preserve the security of the system over the long run, you need to
  42. periodically rotate your keys. The precise interval at which you should rotate
  43. depends upon your application, key sizes and institutional policy. For some
  44. common recommendations, see: https://www.keylength.com.
  45. To rotate keys, first we need to generate new keys in the key database
  46. directory. This is typically */var/db/tang*. For example, you can create
  47. new signature and exchange keys with the following commands:
  48. # DB=/var/db/tang
  49. # jose jwk gen -i '{"alg":"ES512"}' -o $DB/new_sig.jwk
  50. # jose jwk gen -i '{"alg":"ECMR"}' -o $DB/new_exc.jwk
  51. Next, rename the old keys to have a leading *.* in order to hide them from
  52. advertisement:
  53. # mv $DB/old_sig.jwk $DB/.old_sig.jwk
  54. # mv $DB/old_exc.jwk $DB/.old_exc.jwk
  55. Tang will immediately pick up all changes. No restart is required.
  56. At this point, new client bindings will pick up the new keys and old clients
  57. can continue to utilize the old keys. Once you are sure that all the old
  58. clients have been migrated to use the new keys, you can remove the old keys.
  59. Be aware that removing the old keys while clients are still using them can
  60. result in data loss. You have been warned.
  61. == HIGH PERFORMANCE
  62. The Tang protocol is extremely fast. However, in the default setup we
  63. use systemd socket activation to start one process per connection. This
  64. imposes a performance overhead. For most deployments, this is still probably
  65. quick enough, given that Tang is extremely lightweight. But for larger
  66. deployments, greater performance can be achieved.
  67. Our recommendation for achieving higher throughput is to proxy traffic to Tang
  68. through your existing web services using a connection pool. Since there is one
  69. process per connection, keeping a number of connections open in this setup
  70. will enable effective parallelism since there are no internal locks in Tang.
  71. For Apache, this is possible using the *ProxyPass* directive of the *mod_proxy*
  72. module.
  73. == HIGH AVAILABILITY
  74. Tang provides two methods for building a high availability deployment.
  75. 1. Client redundancy (recommended)
  76. 2. Key sharing with DNS round-robin
  77. While it may be tempting to share keys between Tang servers, this method
  78. should be avoided. Sharing keys increases the risk of key compromise and
  79. requires additional automation infrastructure.
  80. Instead, clients should be coded with the ability to bind to multiple Tang
  81. servers. In this setup, each Tang server will have its own keys and clients
  82. will be able to decrypt by contacting a subset of these servers.
  83. Clevis already supports this workflow through its *sss* plugin.
  84. However, if you still feel that key sharing is the right deployment strategy,
  85. Tang will do nothing to stop you. Just (securely!) transfer all the contents
  86. of the database directory to all your servers. Make sure you don't forget the
  87. unadvertised keys! Then set up DNS round-robin so that clients will be load
  88. balanced across your servers.
  89. == COMMANDS
  90. The Tang server provides no public commands.
  91. == AUTHOR
  92. Nathaniel McCallum <npmccallum@redhat.com>
  93. == SEE ALSO
  94. link:systemd.unit.5.adoc[*systemd.unit*(5)],
  95. link:systemd.socket.5.adoc[*systemd.socket*(5)],
  96. link:jose-jwk-gen.1.adoc[*jose-jwk-gen*(1)],
  97. link:tang-show-keys.1.adoc[*tang-show-keys*(1)]
  98. == FURTHER READING
  99. * Clevis : https://github.com/latchset/clevis
  100. * Tang : https://github.com/latchset/tang
  101. * JOSE : https://datatracker.ietf.org/wg/jose/charter/
  102. * mod_proxy : https://httpd.apache.org/docs/2.4/mod/mod_proxy.html