From 13af02641c300dc6349fa16bffb4e01827a698db Mon Sep 17 00:00:00 2001
From: Sarah Jamie Lewis <sarah@openprivacy.ca>
Date: Fri, 29 Jan 2021 18:47:49 -0800
Subject: [PATCH] Better README

---
 README.md  | 65 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 src/lib.rs |  7 +++---
 2 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index ef8d28e..76b97b0 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,67 @@
 # fuzzymetatag
 
-Experimental Rust implementation of https://eprint.iacr.org/2021/089 using Ristretto.
+Anonymous messaging systems (and other privacy-preserving applications) often require a mechanism for one party
+to learn that another party has messaged them.
 
-A tag is a probabilistic cryptographic structure. When constructed for a given FuzzyMetaPublicKey it will pass the FuzzyMetaDetectionKey::test 100% of the time. For other public keys it will pass the test with probability gamma related to the security parameter of the system. This system provides the following security properties:
+Many schemes rely on a bandwidth-intensive "download everything and attempt-decryption" approach. Others rely on a trusted
+3rd party to provide the service.
 
- * Correctness: Valid tags for a public key for a key pair always validate when tested against the secret key
- * Fuzziness: Invalid matches should produce false positives with probability p related to the security property (γ)
- * Security: An adversarial server with access to Test oracle (i.e. the detection key) is unable to distinguish false positives from true positives. (Detection Ambiguity)
+It would be awesome if we could get an untrusted server to do the work for us without compromising metadata-resistance!
+
+fuzzymetatag is a probabilistic cryptographic structure to do just that! Specifically it provides the following
+properties:
+
+ * Correctness: Valid tags constructed for a specific public key will always validate when tested using the detection key
+ * Fuzziness: Invalid tags will produce false positives with probability _p_ related to the security property (_γ_)
+ * Security: An adversarial server with access to the detection key is unable to distinguish false positives from true positives. (Detection Ambiguity)
+
+## Security (hic sunt dracones)
+
+This crate provides an experimental implementation of the `FMD2` scheme described in ["Fuzzy Message Detection"](https://eprint.iacr.org/2021/089). Using
+Ristretto as the prime order group.
+
+This code has not undergone any significant review.
+
+Further, the properties provided by this system are highly dependent on selecting a good security parameter _γ_ for
+your system. There is no one-size-fits-all approach.
+
+If _γ_ is too low, then the probability of false positives will be very high.
+
+If _γ_ is too high, then an adversarial server will be able to link messages to recipients with low probability. 
 
 
+## Usage
+
+Generate a key pair: 
+
+    let gamma = 3;
+    let key = FuzzyMetaTagKeyPair::generate(gamma);
+
+`key.public_key` can be given to parties who you want to be able to communicate with you over a specific anonymous
+messaging service / privacy-preserving application.
+
+`key.detection_key` can be given to untrusted _adversarial_ servers.
+
+`gamma` is security property (_γ_) in the system. For a given gamma, a tag generated for a specific public key will
+validate against a random public key with probability 2^-gamma. The actual value of gamma needed to protect the metadata
+of a given application is specific to that application, the number of parties involved, the number of messages involved etc.
+
+## Generating Tags
+
+    let tag = public_key.flag()
+
+This tag can be attached to a message in a metadata resistant system.
+
+## Verifying Tags
+
+An adversarial server can test a given tag against a detection key:
+
+    if detection_key.test(tag) {
+        // the message attached to this tag *might* be for the party associated with the detection key
+    } else {
+        // the message attached to this tag is definitely *not* for the party associated with the detection key.
+    }
+
+ 
+
 
diff --git a/src/lib.rs b/src/lib.rs
index 0256705..131051d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -17,9 +17,10 @@ use std::ops::{Add, Mul, Sub};
 /// it will pass the `FuzzyMetaDetectionKey::test` 100% of the time. For other public keys
 /// it will pass the test with probability `gamma` related to the security parameter of the system.
 /// This system provides the following security properties:
-/// - Correctness: Valid tags for a public key for a key pair always validate when tested against the secret key
-/// - Fuzziness: Invalid matches should produce false positives with probability p related to the security property (γ)
-/// - Security: An adversarial server with access to Test oracle (i.e. the detection key) is unable to distinguish false positives from true positives. (Detection Ambiguity)
+/// * Correctness: Valid tags constructed for a specific public key will always validate when tested using the detection key
+/// * Fuzziness: Invalid tags will produce false positives with probability _p_ related to the security property (_γ_)
+/// * Security: An adversarial server with access to the detection key is unable to distinguish false positives from true positives. (Detection Ambiguity)
+
 #[derive(Debug)]
 pub struct FuzzyMetaTag {
     u: RistrettoPoint,