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