2018-08-11 09:48:50 -07:00
# threshold_crypto
2018-07-30 15:52:21 -07:00
2018-07-31 07:10:56 -07:00
[![Build Status ](https://travis-ci.org/poanetwork/threshold_crypto.svg?branch=master )](https://travis-ci.org/poanetwork/threshold_crypto)
2018-07-31 07:06:55 -07:00
2018-08-11 09:48:50 -07:00
A pairing-based threshold cryptosystem for collaborative decryption and
signatures.
2018-08-12 12:46:31 -07:00
2018-08-28 11:43:54 -07:00
The `threshold_crypto` crate provides constructors for encrypted message handling. It utilizes the [`pairing` ](https://crates.io/crates/pairing ) elliptic curve library to create and enable reconstruction of public and private key shares.
2018-08-12 12:46:31 -07:00
2018-08-11 09:48:50 -07:00
In a network environment, messages are signed and encrypted, and key and
signature shares are distributed to network participants. A message can be
decrypted and authenticated only with cooperation from at least `threshold +
1` nodes.
## Usage
`Cargo.toml` :
```toml
[dependencies]
rand = "0.4"
threshold_crypto = { version = "0.1", git = "https://github.com/poanetwork/threshold_crypto" }
```
`main.rs` :
```rust
extern crate rand;
extern crate threshold_crypto;
use threshold_crypto::SecretKey;
/// Very basic secret key usage.
fn main() {
let sk0: SecretKey = rand::random();
let sk1: SecretKey = rand::random();
let pk0 = sk0.public_key();
let msg0 = b"Real news";
let msg1 = b"Fake news";
assert!(pk0.verify(& sk0.sign(msg0), msg0));
assert!(!pk0.verify(& sk1.sign(msg0), msg0)); // Wrong key.
assert!(!pk0.verify(& sk0.sign(msg1), msg0)); // Wrong message.
}
```
2018-09-03 11:41:28 -07:00
### Testing
Run tests using the following command:
```
2018-10-08 02:25:15 -07:00
$ cargo test
2018-09-03 11:41:28 -07:00
```
2018-08-28 11:43:54 -07:00
### Examples
2018-08-11 09:48:50 -07:00
Run examples from the [`examples` ](examples ) directory using:
2018-08-12 12:46:31 -07:00
```
2018-10-08 02:25:15 -07:00
$ cargo run --example < example name >
2018-08-12 12:46:31 -07:00
```
2018-08-11 09:48:50 -07:00
Also see the
[distributed_key_generation ](https://github.com/poanetwork/threshold_crypto/blob/d81953b55d181311c2a4eed2b6c34059fcf3fdae/src/poly.rs#L967 )
test.
2018-08-28 11:43:54 -07:00
## Application Details
2018-08-30 02:06:03 -07:00
The basic usage outline is:
2018-08-28 11:43:54 -07:00
* choose a threshold value `t`
* create a key set
* distribute `N` secret key shares among the participants
2018-08-30 02:06:03 -07:00
* publish the public master key
2018-08-28 11:43:54 -07:00
A third party can now encrypt a message to the public master key
2018-08-11 09:48:50 -07:00
and any set of `t + 1` participants *(but no fewer!)* can collaborate to
2018-08-28 11:43:54 -07:00
decrypt it. Also, any set of `t + 1` participants can collaborate to sign a message,
producing a signature that is verifiable with the public master key.
2018-08-11 09:48:50 -07:00
2018-08-30 02:06:03 -07:00
In this system, a signature is unique and independent of
2018-08-28 11:43:54 -07:00
the set of participants that produced it. If `S1` and `S2` are
2018-08-11 09:48:50 -07:00
signatures for the same message, produced by two different sets of `t + 1`
2018-08-28 11:43:54 -07:00
secret key share holders, both signatures will be valid AND
equal. This is useful in some applications, for example a message signature can serve as a pseudorandom number unknown to anyone until `t + 1` participants agree to reveal it.
In its simplest form, threshold_crypto requires a trusted dealer to
produce and distribute the secret key shares. However, keys can be produced so that only the corresponding participant knows their secret in the end. This crate
2018-08-11 09:48:50 -07:00
includes the basic tools to implement such a *Distributed Key Generation*
scheme.
2018-08-28 11:43:54 -07:00
A major application for this library is within a distributed network that
2018-08-11 09:48:50 -07:00
must tolerate up to `t` adversarial (malicious or faulty) nodes. Because `t +
1` nodes are required to sign or reveal information, messages can be trusted
by third-parties as representing the consensus of the network.
2018-08-29 13:12:46 -07:00
## Performance
Benchmarking functionality is kept in the [`benches` directory ](benches ). You
can run the benchmarks with the following command:
```
$ RUSTFLAGS="-C target_cpu=native" cargo bench
```
We use the [`criterion` ](https://crates.io/crates/criterion ) benchmarking library.
2018-08-11 09:48:50 -07:00
## License
Licensed under either of:
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Contributing
See the [CONTRIBUTING ](CONTRIBUTING.md ) document for contribution, testing and
pull request protocol.
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 as above, without any additional terms or
conditions.