Update documentation, configure avx2

This commit is contained in:
Sarah Jamie Lewis 2021-05-22 12:39:04 -07:00
parent 2d73a43d7f
commit 84778a8030
6 changed files with 107 additions and 82 deletions

View File

@ -12,12 +12,13 @@ keywords = ["fuzzytags","privacy","metadata-resistance","ristretto","cryptograph
[dependencies]
hex = "0.4.2"
rand = "0.7.3"
curve25519-dalek = {version="3.0.0", features=["serde"]}
rand_core = "0.6.0"
rand ="0.8.3"
curve25519-dalek = { package = "curve25519-dalek-ng", version="4.0.1", features=["serde"]}
sha3 = "0.9.1"
serde = {version="1.0.123", features=["derive"]}
bit-vec = {version="0.6.3"}
brute-force = {version="0.1.0", features=["curve25519"], optional=true}
brute-force = {path="./brute-force", version="0.1.1", features=["curve25519"], optional=true}
rayon = {version="1.5.0", optional=true}
[dev-dependencies]
@ -35,4 +36,5 @@ harness = false
[features]
entangled = ["brute-force"]
bulk_verify = ["rayon"]
bulk_verify = ["rayon"]
simd = ["curve25519-dalek/simd_backend"]

View File

@ -88,7 +88,9 @@ provided them (depending on the efficiency of the decryption method).
A party first needs to generate `RootSecret`
use fuzzytags::RootSecret;
let secret = RootSecret::<24>::generate();
use rand::rngs::OsRng;
let mut rng = OsRng::default();
let secret = RootSecret::<24>::generate(&mut rng);
From the secret detection key a party can derive a `DetectionKey` which can be given to adversarial server to
fuzzily detect tags on behalf of the party.
@ -105,12 +107,12 @@ Once in possession of a tagging key, a party in a metadata resistant app can use
use fuzzytags::RootSecret;
use rand::rngs::OsRng;
let secret = RootSecret::<24>::generate();
let mut rng = OsRng::default();
let secret = RootSecret::<24>::generate(&mut rng);
let tagging_key = secret.tagging_key();
// Give public key to a another party...
// and then they can do...
let mut rng = OsRng::default();
let tag = tagging_key.generate_tag(&mut rng);
These tags can then be attached to a message in a metadata resistant system.
@ -123,14 +125,14 @@ This extracted key can then be given to an adversarial server. The server can th
use fuzzytags::RootSecret;
use rand::rngs::OsRng;
let secret = RootSecret::<24>::generate();
let mut rng = OsRng::default();
let secret = RootSecret::<24>::generate(&mut rng);
let tagging_key = secret.tagging_key();
// extract a detection key
let detection_key = secret.extract_detection_key(5);
// Give the tagging key to a another party...
// and then they can do...
let mut rng = OsRng::default();
let tag = tagging_key.generate_tag(&mut rng);
// The server can now do this:
@ -150,8 +152,8 @@ opens up applications like **multiple broadcast** and **deniable sending**.
use fuzzytags::{RootSecret, TaggingKey};
use rand::rngs::OsRng;
let mut rng = OsRng::default();
let secret_1 = RootSecret::<24>::generate();
let secret_2 = RootSecret::<24>::generate();
let secret_1 = RootSecret::<24>::generate(&mut rng);
let secret_2 = RootSecret::<24>::generate(&mut rng);
let tagging_key_1 = secret_1.tagging_key(); // give this to a sender
let tagging_key_2 = secret_2.tagging_key(); // give this to a sender
// Will validate for detection keys derived from both secret_1 and secret_2 up
@ -170,7 +172,7 @@ of different approaches e.g.:
use rand::rngs::OsRng;
let mut rng = OsRng::default();
let secret = RootSecret::<24>::generate();
let secret = RootSecret::<24>::generate(&mut rng);
let tagging_key = secret.tagging_key();
// Give public key to a another party...
@ -191,6 +193,14 @@ We use [criterion](https://crates.io/crates/criterion) for benchmarking, and ben
Results will be in `target/criterion/report/index.html`.
### AVX2
This crate has support for the avx2 under the feature `simd`, to take advantage of this feature it is
necessary to build with `RUSTFLAGS="-C target_feature=+avx2"` e.g.
`env RUSTFLAGS="-C target_feature=+avx2" cargo test --release --features "bulk_verify,entangled,simd"`
This results in a 40%+ performance improvements on the provided benchmarks.
## Credits and Contributions

View File

@ -1,18 +1,20 @@
use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
use fuzzytags::{RootSecret, TaggingKey};
use std::time::Duration;
use rand::rngs::OsRng;
fn benchmark_entangled(c: &mut Criterion) {
let mut group = c.benchmark_group("entangling");
group.measurement_time(Duration::new(5000, 0));
group.sample_size(50);
let secret_key_1 = RootSecret::<24>::generate();
let secret_key_2 = RootSecret::<24>::generate();
let public_key_1 = secret_key_1.tagging_key();
let public_key_2 = secret_key_2.tagging_key();
for p in [4, 8, 16, 20, 24].iter() {
group.measurement_time(Duration::new(10, 0));
group.sample_size(10);
let mut rng = OsRng::default();
for p in [24].iter() {
let secret_key_1 = RootSecret::<24>::generate(&mut rng);
let secret_key_2 = RootSecret::<24>::generate(&mut rng);
let public_key_1 = secret_key_1.tagging_key();
let public_key_2 = secret_key_2.tagging_key();
group.bench_with_input(BenchmarkId::from_parameter(p), p, |b, _gamma| {
b.iter(|| TaggingKey::generate_entangled_tag(vec![public_key_1.clone(), public_key_2.clone()], *p))
b.iter(|| TaggingKey::generate_entangled_tag(vec![public_key_1.clone(), public_key_2.clone()], &mut rng, *p))
});
}
}

View File

@ -7,8 +7,8 @@ fn benchmark_generate_tag(c: &mut Criterion) {
let mut group = c.benchmark_group("generate_tags");
group.measurement_time(Duration::new(10, 0));
group.sample_size(1000);
let secret_key = RootSecret::<24>::generate();
let mut rng = OsRng::default();
let secret_key = RootSecret::<24>::generate(&mut rng);
let public_key = secret_key.tagging_key();
for p in [5, 10, 15].iter() {
group.bench_with_input(BenchmarkId::from_parameter(p), p, |b, _gamma| {
@ -21,9 +21,10 @@ fn benchmark_test_tag(c: &mut Criterion) {
let mut group = c.benchmark_group("test_tags");
group.measurement_time(Duration::new(10, 0));
group.sample_size(1000);
let secret_key = RootSecret::<24>::generate();
let mut rng = OsRng::default();
let secret_key = RootSecret::<24>::generate(&mut rng);
for p in [5, 10, 15, 24].iter() {
let detection_key = secret_key.extract_detection_key(*p);
group.bench_with_input(BenchmarkId::from_parameter(p), p, |b, _gamma| {

1
brute-force Submodule

@ -0,0 +1 @@
Subproject commit 51e3b4d549a439e512509c080e2f1fbb1d3e7aa4

View File

@ -1,6 +1,5 @@
#![deny(missing_docs)]
#![feature(external_doc)]
#![feature(const_generics)]
#![doc(include = "../README.md")]
#![doc(include = "../ANONYMITY.md")]
#![doc(html_logo_url = "https://git.openprivacy.ca/openprivacy/fuzzytags/media/branch/trunk/FuzzyTags_Logo.png")]
@ -10,8 +9,6 @@ use curve25519_dalek::digest::Digest;
use curve25519_dalek::ristretto::{CompressedRistretto, RistrettoPoint};
use curve25519_dalek::scalar::Scalar;
use curve25519_dalek::traits::MultiscalarMul;
use rand::rngs::OsRng;
use rand::{CryptoRng, RngCore};
use serde::{de::Visitor, Deserialize, Deserializer, Serialize, Serializer};
use sha3::{Sha3_256, Sha3_512};
use std::convert::TryFrom;
@ -32,6 +29,7 @@ use rayon::iter::IntoParallelRefIterator;
use rayon::iter::ParallelIterator;
#[cfg(feature = "bulk_verify")]
use std::sync::mpsc::channel;
use rand_core::{RngCore, CryptoRng};
/// A tag is a probabilistic cryptographic structure. When constructed for a given `TaggingKey`
/// it will pass the `DetectionKey::test_tag` 100% of the time. For other tagging keys
@ -110,14 +108,14 @@ impl<const GAMMA: u8> Tag<{ GAMMA }> {
/// ```
/// use rand::rngs::OsRng;
/// use fuzzytags::RootSecret;
/// let secret = RootSecret::<24>::generate();
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let tagging_key = secret.tagging_key();
/// // extract a detection key
/// let detection_key = secret.extract_detection_key(5);
///
/// // Give tagging key to a another party...
/// // and then they can do...
/// let mut rng = OsRng::default();
/// let tag = tagging_key.generate_tag(&mut rng);
/// let compressed_tag = tag.compress();
/// ```
@ -133,15 +131,15 @@ impl<const GAMMA: u8> Tag<{ GAMMA }> {
/// You probably want to use one of the many serde `deserialize` apis instead (see README)
/// ```
/// use fuzzytags::{RootSecret, Tag};
/// let secret = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let tagging_key = secret.tagging_key();
/// // extract a detection key
/// let detection_key = secret.extract_detection_key(5);
///
/// // Give tagging key to a another party...
/// // and then they can do...
/// use rand::rngs::OsRng;
/// let mut rng = OsRng::default();
/// let tag = tagging_key.generate_tag(&mut rng);
/// let compressed_tag = tag.compress();
/// let decompressed_tag = Tag::decompress(&compressed_tag).unwrap();
@ -211,13 +209,15 @@ impl<const GAMMA: u8> RootSecret<{ GAMMA }> {
/// Example:
/// ```
/// use fuzzytags::{RootSecret};
/// let secret = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// ```
pub fn generate() -> RootSecret<{ GAMMA }> {
let mut rng = OsRng::default();
pub fn generate<R: RngCore + CryptoRng>(rng: &mut R) -> RootSecret<{ GAMMA }> {
let mut secret = vec![];
for _i in 0..GAMMA {
let sk_i = Scalar::random(&mut rng);
let sk_i = Scalar::random(rng);
secret.push(sk_i);
}
RootSecret::<GAMMA> { secret }
@ -230,7 +230,9 @@ impl<const GAMMA: u8> RootSecret<{ GAMMA }> {
/// Example:
/// ```
/// use fuzzytags::{RootSecret};
/// let secret = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let detection_key = secret.extract_detection_key(2);
/// ```
pub fn extract_detection_key(&self, n: usize) -> DetectionKey<{ GAMMA }> {
@ -242,7 +244,9 @@ impl<const GAMMA: u8> RootSecret<{ GAMMA }> {
/// Example:
/// ```
/// use fuzzytags::RootSecret;
/// let secret = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let tagging_key = secret.tagging_key();
/// ```
pub fn tagging_key(&self) -> TaggingKey<{ GAMMA }> {
@ -270,16 +274,6 @@ impl<const GAMMA: u8> RootSecret<{ GAMMA }> {
return hash.0.finalize().as_slice()[0] & 0x01;
}
/// a hash function that takes 3 ristretto points as a parameter and outputs 0 or 1.
fn h(u: RistrettoPoint, h: RistrettoPoint, w: RistrettoPoint) -> u8 {
let mut hash = sha3::Sha3_256::new();
hash.update(&[GAMMA]);
hash.update(u.compress().as_bytes());
hash.update(w.compress().as_bytes());
hash.update(h.compress().as_bytes());
return hash.finalize().as_slice()[0] & 0x01;
}
/// a hash function which takes a ristretto point and a vector of ciphertexts and outputs a
/// ristretto scalar.
fn g(u: RistrettoPoint, points: &BitVec) -> Scalar {
@ -318,7 +312,9 @@ impl<const GAMMA: u8> DetectionKey<{ GAMMA }> {
/// calculate the ideal false positive rate of this detection key
/// ```
/// use fuzzytags::RootSecret;
/// let secret = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let tagging_key = secret.tagging_key();
/// // extract a detection key
/// let detection_key = secret.extract_detection_key(5);
@ -332,15 +328,15 @@ impl<const GAMMA: u8> DetectionKey<{ GAMMA }> {
/// Example:
/// ```
/// use fuzzytags::RootSecret;
/// let secret = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let tagging_key = secret.tagging_key();
/// // extract a detection key
/// let detection_key = secret.extract_detection_key(5);
///
/// // Give tagging key to a another party...
/// // and then they can do...
/// use rand::rngs::OsRng;
/// let mut rng = OsRng::default();
/// let tag = tagging_key.generate_tag(&mut rng);
///
/// // The server can now do this:
@ -403,11 +399,11 @@ impl<const GAMMA: u8> DetectionKey<{ GAMMA }> {
/// ```
/// use fuzzytags::{TaggingKey, DetectionKey};
/// use fuzzytags::RootSecret;
/// let secrets: Vec<RootSecret<24>> = (0..2).map(|_x| RootSecret::<24>::generate()).collect();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secrets: Vec<RootSecret<24>> = (0..2).map(|_x| RootSecret::<24>::generate(&mut rng)).collect();
/// let tagging_keys: Vec<TaggingKey<24>> = secrets.iter().map(|x| x.tagging_key()).collect();
/// // it takes ~15 minutes on a standard desktop to find a length=24 match for 2 parties, so for testing let's keep things light
/// use rand::rngs::OsRng;
/// let mut rng = OsRng::default();
/// let entangled_tag = TaggingKey::generate_entangled_tag(tagging_keys, &mut rng, 16);
/// let detection_keys = secrets.iter().map(|x| x.extract_detection_key(16)).collect();
///
@ -502,10 +498,10 @@ impl<const GAMMA: u8> TaggingKey<{ GAMMA }> {
/// Example:
/// ```
/// use fuzzytags::{RootSecret};
/// let secret = RootSecret::<24>::generate();
/// let tagging_key = secret.tagging_key(); // give this to a sender
/// use rand::rngs::OsRng;
/// let mut rng = OsRng::default();
/// let mut rng = OsRng;
/// let secret = RootSecret::<24>::generate(&mut rng);
/// let tagging_key = secret.tagging_key(); // give this to a sender
/// let tag = tagging_key.generate_tag(&mut rng);
/// ```
pub fn generate_tag<R: RngCore + CryptoRng>(&self, rng: &mut R) -> Tag<{ GAMMA }> {
@ -557,15 +553,15 @@ impl<const GAMMA: u8> TaggingKey<{ GAMMA }> {
/// Example:
/// ```
/// use fuzzytags::{RootSecret, TaggingKey};
/// let secret_1 = RootSecret::<24>::generate();
/// let secret_2 = RootSecret::<24>::generate();
/// use rand::rngs::OsRng;
/// let mut rng = OsRng;
/// let secret_1 = RootSecret::<24>::generate(&mut rng);
/// let secret_2 = RootSecret::<24>::generate(&mut rng);
/// let tagging_key_1 = secret_1.tagging_key(); // give this to a sender
/// let tagging_key_2 = secret_2.tagging_key(); // give this to a sender
/// // Will validate for detection keys derived from both secret_1 and secret_2 up
/// // to n=8
/// // Sender can now do...tag will validate on detection keys of length 8 or lower.
/// use rand::rngs::OsRng;
/// let mut rng = OsRng::default();
/// let tag = TaggingKey::generate_entangled_tag(vec![tagging_key_1,tagging_key_2], &mut rng, 8);
/// ```
pub fn generate_entangled_tag<R: RngCore + CryptoRng>(tagging_keys: Vec<TaggingKey<{ GAMMA }>>, rng: &mut R, length: usize) -> Tag<{ GAMMA }> {
@ -627,15 +623,16 @@ mod tests {
use curve25519_dalek::ristretto::RistrettoPoint;
use curve25519_dalek::scalar::Scalar;
use rand::rngs::OsRng;
use sha3::Digest;
#[test]
fn test_compression() {
let secret = RootSecret::<24>::generate();
let mut rng = OsRng;
let secret = RootSecret::<24>::generate(&mut rng);
let tagging_key = secret.tagging_key();
// Give tagging key to a another party...
// and then they can do...
let mut rng = OsRng::default();
let tag = tagging_key.generate_tag(&mut rng);
let compressed_tag = tag.compress();
let decompressed_tag = Tag::<24>::decompress(&compressed_tag).unwrap();
@ -645,9 +642,8 @@ mod tests {
#[test]
fn test_serialization() {
// generate some new keys...
let secret = RootSecret::<15>::generate();
let mut rng = OsRng::default();
let mut rng = OsRng;
let secret = RootSecret::<15>::generate(&mut rng);
let tag = secret.tagging_key().generate_tag(&mut rng);
let detection_key = secret.extract_detection_key(10);
let serialized_tag = serde_json::to_string(&tag).unwrap();
@ -657,7 +653,7 @@ mod tests {
assert_eq!(true, detection_key.test_tag(&deserialized_tag));
// generate some new keys...
let secret = RootSecret::<24>::generate();
let secret = RootSecret::<24>::generate(&mut rng);
let tag = secret.tagging_key().generate_tag(&mut rng);
let detection_key = secret.extract_detection_key(10);
let serialized_tag = serde_json::to_string(&tag).unwrap();
@ -694,14 +690,16 @@ mod tests {
#[cfg(feature = "entangled")]
fn test_multiple() {
use crate::TaggingKey;
let secrets: Vec<RootSecret<24>> = (0..2).map(|_x| RootSecret::<24>::generate()).collect();
let mut rng = OsRng;
let secrets: Vec<RootSecret<24>> = (0..2).map(|_x| RootSecret::<24>::generate(&mut rng)).collect();
let tagging_keys: Vec<TaggingKey<24>> = secrets.iter().map(|x| x.tagging_key()).collect();
// it takes ~15 minutes on a standard desktop to find a length=24 match for 2 parties, so for testing let's keep things light
let mut rng = OsRng::default();
let entangled_tag = TaggingKey::generate_entangled_tag(tagging_keys, &mut rng, 16);
// it takes ~2 minutes on a standard desktop to find a length=24 match for 2 parties, so for testing let's keep things light
let len = 16;
let entangled_tag = TaggingKey::generate_entangled_tag(tagging_keys, &mut rng, len);
println!("{}", entangled_tag);
for secret in secrets.iter() {
let detection_key = secret.extract_detection_key(16);
let detection_key = secret.extract_detection_key(len);
assert!(detection_key.test_tag(&entangled_tag));
println!("{}", detection_key);
}
@ -711,10 +709,10 @@ mod tests {
#[cfg(feature = "bulk_verify")]
fn test_check_multiple() {
use crate::TaggingKey;
let secrets: Vec<RootSecret<24>> = (0..2).map(|_x| RootSecret::<24>::generate()).collect();
let mut rng = OsRng;
let secrets: Vec<RootSecret<24>> = (0..2).map(|_x| RootSecret::<24>::generate(&mut rng)).collect();
let tagging_keys: Vec<TaggingKey<24>> = secrets.iter().map(|x| x.tagging_key()).collect();
// it takes ~15 minutes on a standard desktop to find a length=24 match for 2 parties, so for testing let's keep things light
let mut rng = OsRng::default();
// it takes ~2 minutes on a standard desktop to find a length=24 match for 2 parties, so for testing let's keep things light
let entangled_tag = TaggingKey::generate_entangled_tag(tagging_keys, &mut rng, 16);
let detection_keys = secrets
.iter()
@ -728,8 +726,8 @@ mod tests {
#[test]
fn correctness() {
let number_of_messages = 100;
let secret = RootSecret::<16>::generate();
let mut rng = OsRng::default();
let mut rng = OsRng;
let secret = RootSecret::<16>::generate(&mut rng);
for i in 0..number_of_messages {
let tag = secret.tagging_key().generate_tag(&mut rng);
println!("{}: {}", i, tag);
@ -756,9 +754,19 @@ mod tests {
tag
}
/// a hash function that takes 3 ristretto points as a parameter and outputs 0 or 1.
fn h(u: RistrettoPoint, h: RistrettoPoint, w: RistrettoPoint) -> u8 {
let mut hash = sha3::Sha3_256::new();
hash.update(&[24]);
hash.update(u.compress().as_bytes());
hash.update(w.compress().as_bytes());
hash.update(h.compress().as_bytes());
return hash.finalize().as_slice()[0] & 0x01;
}
#[test]
fn assert_h_and_pre_post_h() {
let mut rng = OsRng::default();
let mut rng = OsRng;
for _ in 0..100 {
let a = RistrettoPoint::random(&mut rng);
@ -766,7 +774,7 @@ mod tests {
let c = RistrettoPoint::random(&mut rng);
assert_eq!(
RootSecret::<24>::post_h(RootSecret::<24>::pre_h(a, b), c),
RootSecret::<24>::h(a, c, b)
h(a, c, b)
);
}
}
@ -777,7 +785,8 @@ mod tests {
// broadcast, which overall seems like a bad idea...
// Test to make sure that doesn't happen.
fn test_zero_tag() {
let secret = RootSecret::<24>::generate();
let mut rng = OsRng;
let secret = RootSecret::<24>::generate(&mut rng);
let tag = gen_zero_tag_zero();
assert_eq!(false, secret.extract_detection_key(6).test_tag(&tag));
let tag = gen_zero_tag_one();
@ -786,12 +795,12 @@ mod tests {
#[test]
fn false_positives() {
let mut rng = OsRng;
let number_of_messages = 1000;
let secret = RootSecret::<24>::generate();
let secret = RootSecret::<24>::generate(&mut rng);
let mut false_positives = 0;
let mut rng = OsRng::default();
for _i in 0..number_of_messages {
let secret2 = RootSecret::<24>::generate();
let secret2 = RootSecret::<24>::generate(&mut rng);
let tag = secret2.tagging_key().generate_tag(&mut rng);
assert!(secret2.extract_detection_key(3).test_tag(&tag));
if secret.extract_detection_key(3).test_tag(&tag) == true {