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 suppossed 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       To rotate keys, first we need to generate new keys in the key database
63       directory. This is typically /var/db/tang. For example, you can create
64       new signature and exchange keys with the following commands:
65
66           # DB=/var/db/tang
67           # jose jwk gen -i '{"alg":"ES512"}' -o $DB/new_sig.jwk
68           # jose jwk gen -i '{"alg":"ECMR"}' -o $DB/new_exc.jwk
69
70       Next, rename the old keys to have a leading . in order to hide them
71       from advertisement:
72
73           # mv $DB/old_sig.jwk $DB/.old_sig.jwk
74           # mv $DB/old_exc.jwk $DB/.old_exc.jwk
75
76       Tang will immediately pick up all changes. No restart is required.
77
78       At this point, new client bindings will pick up the new keys and old
79       clients can continue to utilize the old keys. Once you are sure that
80       all the old clients have been migrated to use the new keys, you can
81       remove the old keys. Be aware that removing the old keys while clients
82       are still using them can result in data loss. You have been warned.
83

HIGH PERFORMANCE

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

HIGH AVAILABILITY

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

COMMANDS

125       The Tang server provides no public commands.
126

AUTHOR

128       Nathaniel McCallum <npmccallum@redhat.com>
129

SEE ALSO

131       systemd.unit(5), systemd.socket(5), jose-jwk-gen(1), tang-show-keys(1)
132

FURTHER READING

134       ·   Clevis : https://github.com/latchset/clevis
135
136       ·   Tang : https://github.com/latchset/tang
137
138       ·   JOSE : https://datatracker.ietf.org/wg/jose/charter/
139
140       ·   mod_proxy : https://httpd.apache.org/docs/2.4/mod/mod_proxy.html
141
142
143
144                                  02/03/2019                           TANG(8)
Impressum