Repository files navigation

Tang is a server for binding data to network presence.

This sounds fancy, but the concept is simple. You have some data, but you onlywant it to be available when the system containing the data is on a certain,usually secure, network. This is where Tang comes in.

First, the client gets a list of the Tang server's advertised asymmetric keys.This can happen online by a simple HTTP GET. Alternatively, since the keys areasymmetric, the public key list can be distributed out of band.

Second, the client uses one of these public keys to generate a unique,cryptographically strong encryption key. The data is then encrypted using thiskey. Once the data is encrypted, the key is discarded. Some small metadata isproduced as part of this operation which the client should store in aconvenient location. This process of encrypting data is the provisioning step.

Third, when the client is ready to access its data, it simply loads themetadata produced in the provisioning step and performs an HTTP POST in orderto recover the encryption key. This process is the recovery step.

Tang provides an easy and secure alternative to key escrows.

Before Tang, automated decryption usually took the form of generating a key,encrypting data with it and then storing the key in a remote server. Thisremote server is called a key escrow.

The concept of key escrow is simple, but managing it can be complex.

Key escrows are stateful by nature. And since they store live data (theencryption keys), they must be surrounded by a sophisticated backup policy.This backup policy also needs to be carefully secured, otherwise improperaccess to the keys could be obtained. Further, since keys are transferred overthe wire, typically SSL/TLS is used. SSL/TLS is a large protocol, with acorresponding large attack surface; resulting in attacks like Heartbleed. Evenfurther, escrows require a comprehensive authentication policy. Without thisany user on the network can fetch any key. Often this is deployed using X.509certificates, which bring their own complexity.

In contrast, Tang is stateless and doesn't require TLS or authentication. Tangalso has limited knowledge. Unlike escrows, where the server has knowledge ofevery key ever used, Tang never sees a single client key. Tang never gains anyidentifying information from the client.

Tang requires two other software libraries:

1. jose >= 8 -https://github.com/latchset/jose
2. Either:
   • llhttp -https://github.com/nodejs/llhttp
   • http_parser >= 2.8 -https://github.com/nodejs/http-parser

http_parser is unmaintained, but llhttp is not availalbe in alldistributions - notably Debian and CentOS.

Tang is packaged for Fedora. This package should be used as it containsadditional settings (such as SETGID directories) out of the box. To install it:

$ sudo dnf install tang

If you really want to build from source on Fedora, you will need the followingpackages:

1. llhttp -llhttp-devel
2. systemd -systemd (desirable but not strictly required)
3. jose -jose,libjose-devel
4. curl -curl (only needed for running tests)
5. socat -socat (only needed for running tests)

Tang is also capable of running on devices without systemd even for exampleOpenWrt (see:this PR).Instead of using systemd for socket activation you can use another daemon forspawning services like xinetd. As of version 12 tang can also be run as astandalone server without a separate socket listener.

An example of configuration file for Tang using xinetd can be found in theunits/ directory as 'tangdx'. Using that will also require installing thewrapper from the 'units/' directroy 'tangdw' in '/usr/libexec/tangdw'.

Tang is also capable of running on FreeBSD Unix variants. It is available inthe ports tree and package system. As root you can install it with:

# pkg install tang# service tangd enable# service tangd start

Tang can be installed on OPNsense by enabling the FreeBSD package repositoriesand then installing. There are some extra steps to minimize the installation.

As root enable the FreeBSD repository, download tang, jose, and llhttp.Then disable the FreeBSD repository to prevent installing extraneousdependencies not needed by tang. And finally install the downloaded packagesand start the server:

# vi /usr/local/etc/pkg/repos/FreeBSD.conf (set enabled to yes)# pkg download tang jose llhttp# vi /usr/local/etc/pkg/repos/FreeBSD.conf (set enabled back to no)# pkg install /var/cache/pkg/tang-*.pkg /var/cache/pkg/jose-*.pkg /var/cache/pkg/llhttp-*.pkg# service tangd enable# service tangd start

Tang is also available as aDockerContainer.

Care should be taken to ensure that, when deploying in a container cluster,that the Tang keys are not stored on the same physical medium that you wish toprotect.

Building Tang is fairly straightforward:

$ mkdir build && cd build$ meson setup .. --prefix=/usr$ ninja$ sudo ninja install

You can even run the tests if you'd like:

$ meson test

The build is simple and differs only sligtly from the general instructions.

(as root) # pkg install jose git meson pkgconf jansson asciidoc llhttp socat$ mkdir build && cd build$ meson setup .. --prefix=/usr/local$ ninja$ meson test # if you want to run the tests(as root) # ninja install(as root) # mkdir -m 0700 /var/db/tang

Once built it does not require the many packages above, but still requiresjose and llhttp.

Once installed, starting a Tang server is simple:

$ sudo systemctl enable tangd.socket --now

This command will enable Tang for startup at boot and will additionally startit immediately. During the first startup, your initial signing and exchangekeys will be generated automatically.

That's it! You're up and running!

It is important to periodically rotate your keys. This is a simple three stepprocess. In this example, we will rotate only a signing key; but all key typesshould be rotated.

First, generate the new keys (see jose documentation for more options):

$ sudo jose jwk gen -i '{"alg":"ES512"}' -o /var/db/tang/newsig.jwk$ sudo jose jwk gen -i '{"alg":"ECMR"}' -o /var/db/tang/newexc.jwk

Second, disable advertisement of the previous key:

$ sudo mv /var/db/tang/oldsig.jwk /var/db/tang/.oldsig.jwk

Third, after some reasonable period of time you may delete the old keys. Youshould only delete the old keys when you are sure that no client require themanymore. You have been warned.

Tang relies on the JSON Object Signing and Encryption (JOSE) standards.All messages in the Tang protocol are valid JOSE objects. Because of this,you can easily write your own trivial Tang clients using off-the-shelf JOSElibraries and/or command-line utilities. However, this also implies thatcomprehending the Tang protocol will require a basic understanding of JOSEobjects.

All Tang messages are transported using a simple HTTP REST API.

The advertisement reply message contains a JWS-signed JWKSet.

The (outer) JWS contains signatures using all of the advertised signing JWKs.

The (inner) JWKSet contains all of the advertised public JWKs. This includesall advertised signing, encryption and exchange JWKs.

Typically, a client will perform "Trust On First Use" in order to trust theserver's advertisement. However, once the client trusts at least one signingJWK, further advertisements can be requested using that signing JWK. Thisallows clients to upgrade their chain of trust.

Tang implements the McCallum-Relyea exchange as described below.

The basic idea of a McCallum-Relyea exchange is that the client performs anECDH key exchange in order to produce the binding key, but then discards itsown private key so that the Tang server is the only party that can reconstitutethe binding key. Additionally, a third, ephemeral key is used to blind theclient's public key and the binding key so that only the client can unblindthem. In short, blinding makes the recovery request and responseindistinguishable from random to both eavesdroppers and the Tang server itself.

The POST request and reply bodies are JWK objects.

The client selects one of the Tang server's exchange keys (sJWK; identifiedby the use ofderiveKey in thesJWK'skey_ops attribute). The clientgenerates a new (random) JWK (cJWK). The client performs its half of astandard ECDH exchange producingdJWK which it uses to encrypt the data.Afterwards, it discardsdJWK and the private key fromcJWK.

The client then storescJWK for later use in the recovery step. Generallyspeaking, the client may also store other data, such as the URL of the Tangserver or the trusted advertisement signing keys.

Expressed mathematically (capital = private key):

s = g * S # sJWK (Server operation)c = g * C # cJWKK = s * C # dJWK

To recoverdJWK after discarding it, the client generates a third ephemeralkey (eJWK). UsingeJWK, the client performs elliptic curve group additionofeJWK andcJWK, producingxJWK. The client POSTsxJWK to the server.

The server then performs its half of the ECDH key exchange usingxJWK andsJWK, producingyJWK. The server returnsyJWK to the client.

The client then performs half of an ECDH key exchange betweeneJWK andsJWK, producingzJWK. SubtractingzJWK fromyJWK producesdJWK again.

Expressed mathematically (capital = private key):

e = g * E # eJWKx = c + e # xJWKy = x * S # yJWK (Server operation)z = s * E # zJWKK = y - z # dJWK

To understand this algorithm, let us consider it without the ephemeraleJWK.The math in this example depicts a standard ECDH.

s = g * S # sJWK (Server advertisement)c = g * C # cJWK (Client provisioning)K = s * C # dJWK (Client provisioning)K = c * S # dJWK (Server recovery)

In the above case, the provisioning step is identical and the recovery stepdoes not useeJWK. Here, it becomes obvious that the client could simply sendits own public key (cJWK) to the server and receive backdJWK.

This example has a serious problem, however: both the identity of the client(cJWK) and its secure decryption key (dJWK) are leaked to both the serverand any eavesdroppers. To overcome this problem, we use the ephemeral key(eJWK) to blind both values.

Let's think about the security of this system.

So long as the client discards its private key, the client cannot recoverdJWK without the Tang server. This is fundamentally the same assumption usedby Diffie-Hellman (and ECDH).

There are thus three avenues of attack which we will consider in turn:

1. Man-in-the-Middle
2. Compromise the client to gain access tocJWK
3. Compromise the server to gain access tosJWK's private key

In the first case, the eavesdropper in this case sees the client sendxJWKand receiveyJWK. Since, these packets are blinded byeJWK, only the partythat can unblind these values is the client itself (since only it haseJWK'sprivate key). Thus, the MitM attack fails.

In the second case, it is of utmost importance that the client protectcJWKfrom prying eyes. This may include device permissions, filesystem permissions,security frameworks (such as SELinux) or even the use of hardware encryptionsuch as a TPM. How precisely this is accomplished is an exercise left to theclient implementation.

In the third case, the Tang server must protect the private key forsJWK.In this implementation, access is controlled by filesystem permissions andthe service's policy. An alternative implementation might use hardwarecryptography (for example, an HSM) to protect the private key.