# Tangy Lib

## Description

Tangy-lib is a library implementation of the Tang server, written in rust.

The Tang protocol allows clients to store secrets which can only be recovered when they have access to the Tang server. For example, the Clevis tools allows the automated decryption of LUKS partitions when the encrypted device is connected to the local network that Tang is accessible on.

See the original Tang project for a complete description: https://github.com/latchset/tang

Fraser Tweedale's 2020 Linux Conference Australia talk on "Clevis and Tang: securing your secrets at rest" is a great resource:

[![Clevis and Tang: securing your secrets at rest](https://img.youtube.com/vi/Dk6ZuydQt9I/0.jpg)](https://www.youtube.com/watch?v=Dk6ZuydQt9I)


## Installation

Installation via cargo:

``` bash
cargo add tangy-lib
```

Or directly using in the dependencies section of Cargo.toml:

``` toml
[dependencies]
tangy-lib = "0.1"
```

## Usage

Tangy-lib has an initialization method which can take a local directory or vector of JWK string as input:

``` rust
use tangy_lib::{KeySource, TangyLib};
let mut tangy = TangyLib::init(KeySource::LocalDir(&dir_path)).unwrap();
// or
let mut tangy = TangyLib::init(KeySource::Vector(&vec_of_keys)).unwrap();
```

If the `LocalDir` does not contain a key set, a new key set is generated and saved to that folder.

The local directory and vector load methods will process the keys and generate errors if a JWK cannot be loaded or if some keys are missing an `std::io::Error` is returned with kind set to `std::io::ErrorKind::Unsupported` or `std::io::ErrorKind::NotFound`. 

If `init` returns `Ok` then everything else should work.

Tang uses `advertise` and `recovery` stages, to generate an adversise response and then recovery response:

``` rust
use tangy_lib::{KeySource, TangyLib};
let mut tangy = TangyLib::init(KeySource::LocalDir(&dir_path));
let adv = tangy.adv(None).unwrap();
let rec = tangy.rec(&kid, &data).unwrap();
```

Where the parameter passed to `adv` is a thumbprint of which signing key to use, often set to None which will use all signing keys. If the signing key is set but not found `adv` will return `Err(std::io::Error)` with ErrorKind set to std::io::ErrorKind::NotFound.

For recovery the thumbprint of the Elliptic Curve Message Recovery (ECMR) key, and the data is public key generated by the client in JWK format.

A key creation mechanism is provided:

``` rust
let keys : Vec<String> = tangy_lib::create_new_key_set();
```

It creates ES512 and ECMR keys.

## Credits

The original authors of [Tang](https://github.com/latchset/tang) are [Latchset](https://github.com/latchset/). Tang is based on the protocol described by Nathaniel McCallum and Robert Relyea (https://marc.info/?m=144173814525805).


## License

Apache-2.0 or MIT - you decide!

## How to Contribute

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed (Apache-2.0 and MIT), without any additional terms or conditions.