{"id":13530691,"url":"https://github.com/latchset/tang","last_synced_at":"2025-04-01T18:32:12.683Z","repository":{"id":3004557,"uuid":"46134608","full_name":"latchset/tang","owner":"latchset","description":"Tang binding daemon","archived":false,"fork":false,"pushed_at":"2025-02-28T12:16:26.000Z","size":443,"stargazers_count":543,"open_issues_count":36,"forks_count":59,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-02-28T17:58:20.169Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/latchset.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-11-13T16:47:53.000Z","updated_at":"2025-02-28T12:16:30.000Z","dependencies_parsed_at":"2024-01-03T04:13:08.994Z","dependency_job_id":"9d845ff2-f7a4-4c11-9c79-21a9b4384b69","html_url":"https://github.com/latchset/tang","commit_stats":{"total_commits":208,"total_committers":19,"mean_commits":"10.947368421052632","dds":"0.23557692307692313","last_synced_commit":"7c0d86f5ce6a2b60bd059e87f5235b5c29e5bec9"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/latchset%2Ftang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/latchset%2Ftang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/latchset%2Ftang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/latchset%2Ftang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/latchset","download_url":"https://codeload.github.com/latchset/tang/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246691693,"owners_count":20818555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T07:00:53.618Z","updated_at":"2025-04-01T18:32:12.283Z","avatar_url":"https://github.com/latchset.png","language":"C","funding_links":[],"categories":["DevSecOps","C","Identity, signing and provenance","others"],"sub_categories":["Policy enforcement","Supply chain beyond libraries","策略执行"],"readme":"[![build](https://github.com/latchset/tang/workflows/build/badge.svg)](https://github.com/latchset/tang/actions)\n[![coverage](https://codecov.io/gh/latchset/tang/branch/master/graph/badge.svg)](https://codecov.io/gh/latchset/tang)\n\n# Tang\n\n## Welcome to Tang!\nTang is a server for binding data to network presence.\n\nThis sounds fancy, but the concept is simple. You have some data, but you only\nwant it to be available when the system containing the data is on a certain,\nusually secure, network. This is where Tang comes in.\n\nFirst, the client gets a list of the Tang server's advertised asymmetric keys.\nThis can happen online by a simple HTTP GET. Alternatively, since the keys are\nasymmetric, the public key list can be distributed out of band.\n\nSecond, the client uses one of these public keys to generate a unique,\ncryptographically strong encryption key. The data is then encrypted using this\nkey. Once the data is encrypted, the key is discarded. Some small metadata is\nproduced as part of this operation which the client should store in a\nconvenient location. This process of encrypting data is the provisioning step.\n\nThird, when the client is ready to access its data, it simply loads the\nmetadata produced in the provisioning step and performs an HTTP POST in order\nto recover the encryption key. This process is the recovery step.\n\n#### Tang Versus Key Escrow: Ease of Use and Simple Security\n\nTang provides an easy and secure alternative to key escrows.\n\nBefore Tang, automated decryption usually took the form of generating a key,\nencrypting data with it and then storing the key in a remote server. This\nremote server is called a key escrow.\n\nThe concept of key escrow is simple, but managing it can be complex.\n\nKey escrows are stateful by nature. And since they store live data (the\nencryption keys), they must be surrounded by a sophisticated backup policy.\nThis backup policy also needs to be carefully secured, otherwise improper\naccess to the keys could be obtained. Further, since keys are transferred over\nthe wire, typically SSL/TLS is used. SSL/TLS is a large protocol, with a\ncorresponding large attack surface; resulting in attacks like Heartbleed. Even\nfurther, escrows require a comprehensive authentication policy. Without this\nany user on the network can fetch any key. Often this is deployed using X.509\ncertificates, which bring their own complexity.\n\nIn contrast, Tang is stateless and doesn't require TLS or authentication. Tang\nalso has limited knowledge. Unlike escrows, where the server has knowledge of\nevery key ever used, Tang never sees a single client key. Tang never gains any\nidentifying information from the client.\n\n|                |   Escrow   |   Tang   |\n|---------------:|:----------:|:--------:|\n|      Stateless |     No     |    Yes   |\n|          X.509 |  Required  | Optional |\n|        SSL/TLS |  Required  | Optional |\n| Authentication |  Required  | Optional |\n|      Anonymous |     No     |    Yes   |\n\n## Getting Started\n### Dependencies\n\nTang requires two other software libraries:\n\n1. jose \u003e= 8 - https://github.com/latchset/jose\n2. Either:\n   - llhttp - https://github.com/nodejs/llhttp\n   - http_parser \u003e= 2.8 - https://github.com/nodejs/http-parser\n\nhttp_parser is unmaintained, but llhttp is not availalbe in all\ndistributions - notably Debian and CentOS.\n\n#### Fedora\n\nTang is packaged for Fedora. This package should be used as it contains\nadditional settings (such as SETGID directories) out of the box. To install it:\n\n    $ sudo dnf install tang\n\nIf you really want to build from source on Fedora, you will need the following\npackages:\n\n1. llhttp - ``llhttp-devel``\n2. systemd - ``systemd`` (desirable but not strictly required)\n3. jose - ``jose``, ``libjose-devel``\n4. curl - ``curl`` (only needed for running tests)\n5. socat - ``socat`` (only needed for running tests)\n\n#### OpenWrt\n\nTang is also capable of running on devices without systemd even for example\nOpenWrt (see: [this PR](https://github.com/openwrt/packages/pull/5447)).\nInstead of using systemd for socket activation you can use another daemon for\nspawning services like xinetd. As of version 12 tang can also be run as a\nstandalone server without a separate socket listener.\n\nAn example of configuration file for Tang using xinetd can be found in the\n`units/` directory as 'tangdx'.  Using that will also require installing the\nwrapper from the 'units/' directroy 'tangdw' in '/usr/libexec/tangdw'.\n\n#### FreeBSD\n\nTang is also capable of running on FreeBSD Unix variants. It is available in\nthe ports tree and package system.  As root you can install it with:\n\n    # pkg install tang\n    # service tangd enable\n    # service tangd start\n\n#### OPNsense\n\nTang can be installed on OPNsense by enabling the FreeBSD package repositories\nand then installing. There are some extra steps to minimize the installation.\n\nAs root enable the FreeBSD repository, download tang, jose, and llhttp.\nThen disable the FreeBSD repository to prevent installing extraneous\ndependencies not needed by tang. And finally install the downloaded packages\nand start the server:\n\n    # vi /usr/local/etc/pkg/repos/FreeBSD.conf (set enabled to yes)\n    # pkg download tang jose llhttp\n    # vi /usr/local/etc/pkg/repos/FreeBSD.conf (set enabled back to no)\n    # pkg install /var/cache/pkg/tang-*.pkg /var/cache/pkg/jose-*.pkg /var/cache/pkg/llhttp-*.pkg\n    # service tangd enable\n    # service tangd start\n\n#### Docker Container\n\nTang is also available as a [Docker\nContainer](https://gitlab.com/AdrianKoshka/tang-docker-container/).\n\nCare should be taken to ensure that, when deploying in a container cluster,\nthat the Tang keys are not stored on the same physical medium that you wish to\nprotect.\n\n### Building and Installing from Source\n\nBuilding Tang is fairly straightforward:\n\n    $ mkdir build \u0026\u0026 cd build\n    $ meson setup .. --prefix=/usr\n    $ ninja\n    $ sudo ninja install\n\nYou can even run the tests if you'd like:\n\n    $ meson test\n\n#### FreeBSD\n\nThe build is simple and differs only sligtly from the general instructions.\n\n    (as root) # pkg install jose git meson pkgconf jansson asciidoc llhttp socat\n    $ mkdir build \u0026\u0026 cd build\n    $ meson setup .. --prefix=/usr/local\n    $ ninja\n    $ meson test # if you want to run the tests\n    (as root) # ninja install\n    (as root) # mkdir -m 0700 /var/db/tang\n\nOnce built it does not require the many packages above, but still requires\njose and llhttp. \n\n### Server Enablement\n\nOnce installed, starting a Tang server is simple:\n\n    $ sudo systemctl enable tangd.socket --now\n\nThis command will enable Tang for startup at boot and will additionally start\nit immediately. During the first startup, your initial signing and exchange\nkeys will be generated automatically.\n\nThat's it! You're up and running!\n\n### Key Rotation\n\nIt is important to periodically rotate your keys. This is a simple three step\nprocess. In this example, we will rotate only a signing key; but all key types\nshould be rotated.\n\nFirst, generate the new keys (see jose documentation for more options):\n\n    $ sudo jose jwk gen -i '{\"alg\":\"ES512\"}' -o /var/db/tang/newsig.jwk\n    $ sudo jose jwk gen -i '{\"alg\":\"ECMR\"}' -o /var/db/tang/newexc.jwk\n\nSecond, disable advertisement of the previous key:\n\n    $ sudo mv /var/db/tang/oldsig.jwk /var/db/tang/.oldsig.jwk\n\nThird, after some reasonable period of time you may delete the old keys. You\nshould only delete the old keys when you are sure that no client require them\nanymore. You have been warned.\n\n## Tang Protocol\n\nTang relies on the JSON Object Signing and Encryption (JOSE) standards.\nAll messages in the Tang protocol are valid JOSE objects. Because of this,\nyou can easily write your own trivial Tang clients using off-the-shelf JOSE\nlibraries and/or command-line utilities. However, this also implies that\ncomprehending the Tang protocol will require a basic understanding of JOSE\nobjects.\n\nAll Tang messages are transported using a simple HTTP REST API.\n\n| Method   | Path         | Operation                                     |\n|---------:|:-------------|:----------------------------------------------|\n|    `GET` | `/adv`       | Fetch public keys                             |\n|    `GET` | `/adv/{kid}` | Fetch public keys using specified signing key |\n|   `POST` | `/rec/{kid}` | Perform recovery using specified exchange key |\n\n### Advertisement\n\nThe advertisement reply message contains a JWS-signed JWKSet.\n\nThe (outer) JWS contains signatures using all of the advertised signing JWKs.\n\nThe (inner) JWKSet contains all of the advertised public JWKs. This includes\nall advertised signing, encryption and exchange JWKs.\n\nTypically, a client will perform \"Trust On First Use\" in order to trust the\nserver's advertisement. However, once the client trusts at least one signing\nJWK, further advertisements can be requested using that signing JWK. This\nallows clients to upgrade their chain of trust.\n\n### Binding\n\nTang implements the McCallum-Relyea exchange as described below.\n\nThe basic idea of a McCallum-Relyea exchange is that the client performs an\nECDH key exchange in order to produce the binding key, but then discards its\nown private key so that the Tang server is the only party that can reconstitute\nthe binding key. Additionally, a third, ephemeral key is used to blind the\nclient's public key and the binding key so that only the client can unblind\nthem. In short, blinding makes the recovery request and response\nindistinguishable from random to both eavesdroppers and the Tang server itself.\n\nThe POST request and reply bodies are JWK objects.\n\n#### Provisioning\n\nThe client selects one of the Tang server's exchange keys (`sJWK`; identified\nby the use of `deriveKey` in the `sJWK`'s `key_ops` attribute). The client\ngenerates a new (random) JWK (`cJWK`). The client performs its half of a\nstandard ECDH exchange producing `dJWK` which it uses to encrypt the data.\nAfterwards, it discards `dJWK` and the private key from `cJWK`.\n\nThe client then stores `cJWK` for later use in the recovery step. Generally\nspeaking, the client may also store other data, such as the URL of the Tang\nserver or the trusted advertisement signing keys.\n\nExpressed mathematically (capital = private key):\n\n    s = g * S # sJWK (Server operation)\n    c = g * C # cJWK\n    K = s * C # dJWK\n\n#### Recovery\n\nTo recover `dJWK` after discarding it, the client generates a third ephemeral\nkey (`eJWK`). Using `eJWK`, the client performs elliptic curve group addition\nof `eJWK` and `cJWK`, producing `xJWK`. The client POSTs `xJWK` to the server.\n\nThe server then performs its half of the ECDH key exchange using `xJWK` and\n`sJWK`, producing `yJWK`. The server returns `yJWK` to the client.\n\nThe client then performs half of an ECDH key exchange between `eJWK` and\n`sJWK`, producing `zJWK`. Subtracting `zJWK` from `yJWK` produces `dJWK` again.\n\nExpressed mathematically (capital = private key):\n\n    e = g * E # eJWK\n    x = c + e # xJWK\n    y = x * S # yJWK (Server operation)\n    z = s * E # zJWK\n    K = y - z # dJWK\n\n##### Understanding the Algorithm\n\nTo understand this algorithm, let us consider it without the ephemeral `eJWK`.\nThe math in this example depicts a standard ECDH.\n\n    s = g * S # sJWK (Server advertisement)\n    c = g * C # cJWK (Client provisioning)\n    K = s * C # dJWK (Client provisioning)\n\n    K = c * S # dJWK (Server recovery)\n\nIn the above case, the provisioning step is identical and the recovery step\ndoes not use `eJWK`. Here, it becomes obvious that the client could simply send\nits own public key (`cJWK`) to the server and receive back `dJWK`.\n\nThis example has a serious problem, however: both the identity of the client\n(`cJWK`) and its secure decryption key (`dJWK`) are leaked to both the server\nand any eavesdroppers. To overcome this problem, we use the ephemeral key\n(`eJWK`) to blind both values.\n\n#### Security Considerations\n\nLet's think about the security of this system.\n\nSo long as the client discards its private key, the client cannot recover\n`dJWK` without the Tang server. This is fundamentally the same assumption used\nby Diffie-Hellman (and ECDH).\n\nThere are thus three avenues of attack which we will consider in turn:\n\n1. Man-in-the-Middle\n2. Compromise the client to gain access to `cJWK`\n3. Compromise the server to gain access to `sJWK`'s private key\n\nIn the first case, the eavesdropper in this case sees the client send `xJWK`\nand receive `yJWK`. Since, these packets are blinded by `eJWK`, only the party\nthat can unblind these values is the client itself (since only it has `eJWK`'s\nprivate key). Thus, the MitM attack fails.\n\nIn the second case, it is of utmost importance that the client protect `cJWK`\nfrom prying eyes. This may include device permissions, filesystem permissions,\nsecurity frameworks (such as SELinux) or even the use of hardware encryption\nsuch as a TPM. How precisely this is accomplished is an exercise left to the\nclient implementation.\n\nIn the third case, the Tang server must protect the private key for `sJWK`.\nIn this implementation, access is controlled by filesystem permissions and\nthe service's policy. An alternative implementation might use hardware\ncryptography (for example, an HSM) to protect the private key.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flatchset%2Ftang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flatchset%2Ftang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flatchset%2Ftang/lists"}