1TANG(8)                                                                TANG(8)
2
3
4

NAME

6       tang - Network-Based Cryptographic Binding Server
7

OVERVIEW

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
13       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
20       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
25       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
32       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

GETTING STARTED

41       Getting a Tang server up and running is simple:
42
43           $ sudo systemctl enable tangd.socket --now
44
45       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

CONFIGURATION

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

KEY ROTATION

56       In order to preserve the security of the system over the long run, you
57       need to periodically rotate your keys. The precise interval at which
58       you should rotate depends upon your application, key sizes and
59       institutional policy. For some common recommendations, see:
60       https://www.keylength.com.
61
62       There is a convenience script to deal with this. See
63       tangd-rotate-keys(1) for more information. This can also be performed
64       manually as described below.
65
66       To rotate keys, first we need to generate new keys in the key database
67       directory. This is typically /var/db/tang. For example, you can create
68       new signature and exchange keys with the following commands:
69
70           # DB=/var/db/tang
71           # jose jwk gen -i '{"alg":"ES512"}' -o $DB/new_sig.jwk
72           # jose jwk gen -i '{"alg":"ECMR"}' -o $DB/new_exc.jwk
73
74       Next, rename the old keys to have a leading . in order to hide them
75       from advertisement:
76
77           # mv $DB/old_sig.jwk $DB/.old_sig.jwk
78           # mv $DB/old_exc.jwk $DB/.old_exc.jwk
79
80       Tang will immediately pick up all changes. No restart is required.
81
82       At this point, new client bindings will pick up the new keys and old
83       clients can continue to utilize the old keys. Once you are sure that
84       all the old clients have been migrated to use the new keys, you can
85       remove the old keys. Be aware that removing the old keys while clients
86       are still using them can result in data loss. You have been warned.
87

HIGH PERFORMANCE

89       The Tang protocol is extremely fast. However, in the default setup we
90       use systemd socket activation to start one process per connection. This
91       imposes a performance overhead. For most deployments, this is still
92       probably quick enough, given that Tang is extremely lightweight. But
93       for larger deployments, greater performance can be achieved.
94
95       Our recommendation for achieving higher throughput is to proxy traffic
96       to Tang through your existing web services using a connection pool.
97       Since there is one process per connection, keeping a number of
98       connections open in this setup will enable effective parallelism since
99       there are no internal locks in Tang.
100
101       For Apache, this is possible using the ProxyPass directive of the
102       mod_proxy module.
103

HIGH AVAILABILITY

105       Tang provides two methods for building a high availability deployment.
106
107        1. Client redundancy (recommended)
108
109        2. Key sharing with DNS round-robin
110
111       While it may be tempting to share keys between Tang servers, this
112       method should be avoided. Sharing keys increases the risk of key
113       compromise and requires additional automation infrastructure.
114
115       Instead, clients should be coded with the ability to bind to multiple
116       Tang servers. In this setup, each Tang server will have its own keys
117       and clients will be able to decrypt by contacting a subset of these
118       servers.
119
120       Clevis already supports this workflow through its sss plugin.
121
122       However, if you still feel that key sharing is the right deployment
123       strategy, Tang will do nothing to stop you. Just (securely!) transfer
124       all the contents of the database directory to all your servers. Make
125       sure you don’t forget the unadvertised keys! Then set up DNS
126       round-robin so that clients will be load balanced across your servers.
127

COMMANDS

129       The Tang server provides no public commands.
130

AUTHOR

132       Nathaniel McCallum <npmccallum@redhat.com>
133

SEE ALSO

135       systemd.unit(5), systemd.socket(5), jose-jwk-gen(1), tang-show-keys(1),
136       tangd-rotate-keys(1)
137

FURTHER READING

139       •   Clevis : https://github.com/latchset/clevis
140
141       •   Tang : https://github.com/latchset/tang
142
143       •   JOSE : https://datatracker.ietf.org/wg/jose/charter/
144
145       •   mod_proxy : https://httpd.apache.org/docs/2.4/mod/mod_proxy.html
146
147
148
149                                  01/22/2022                           TANG(8)
Impressum