updated readme with a better system description

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "fuzzytags"
 description = "a probabilistic cryptographic structure for metadata resistant tagging"
-version = "0.1.0"
+version = "0.1.1"
 repository = "https://git.openprivacy.ca/openprivacy/fuzzytags"
 authors = ["Sarah Jamie Lewis <sarah@openprivacy.ca>"]
 edition = "2018"

README.md

@@ -4,16 +4,18 @@ Anonymous messaging systems (and other privacy-preserving applications) often re
 to learn that another party has messaged them.
 
 Many schemes rely on a bandwidth-intensive "download everything and attempt-decryption" approach. Others rely on a trusted
-3rd party to provide the service.
+3rd party, or non-collusion assumptions, to provide a "private" service.
 
-It would be awesome if we could get an untrusted server to do the work for us without compromising metadata-resistance!
+It would be awesome if we could get an **untrusted**, **adversarial** server to do the work for us without compromising metadata-resistance!
 
-**fuzzytags** is a probabilistic cryptographic structure to do just that! Specifically it provides the following
-properties:
+**fuzzytags** is an experimental probabilistic cryptographic tagging structure to do just that! 
 
- * 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)
+Specifically **fuzzytags** provides the following properties:
+
+ * Correctness: Valid tags constructed for a specific public key will always validate when tested using a derived detection key.
+ * Fuzziness: Tags will produce false positives with probability _p_ related to the security property (_γ_) when tested against detection keys they
+ were not intended for.
+ * 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)
 
@@ -32,6 +34,36 @@ If _p_ is too high, then an adversarial server will be able to link messages to
 Likewise a large _γ_ means higher bandwidth costs, but a small _γ_ reveals more of the secret keys to the server and
 increases false positives. 
 
+## More Detailed System Description
+
+There exists a metadata resistant application that uses untrusted servers to mediate communication between parties. 
+
+Each party can be identified with a set of cryptographic identifiers and there exists methods in or external to the system
+to distribute keys securely and authentically.
+
+Now, instead of each party adopting a download-everything approach to metadata privacy (or invoking non-collusion
+or other assumptions) we can leverage fuzzytags to reduce the number of messages downloaded from the server by each party
+while maintaining a formalized concept of metadata privacy.
+
+Every party generates a `FuzzyTagKeyPair`, consisting of a `FuzzyTagSecretKey` and a `FuzzyTagPublicKey`. These keys will
+be generated with a parameter _γ_ that relates to the minimum false-positive probability 2^-γ.
+
+When submitting messages to the server for an intended **recipient**, the **sender** will generate a new tag
+from the  **recipients** `FuzzyTagPublicKey`.
+
+All parties will `extract` a `FuzzyTagDetectionKey` from their key pair. This key will be of length `n` and provide
+a false positive detection probability of  0 <= 2^-n <= 2^-γ. This detection key can be given to an adversarial server.
+
+When fetching new messages from the adversarial server, the server first runs a `test` of the tag of the message against
+the parties' detection key. If the tag passes the test, the message (along with the tag) is provided to the **recipient**.
+
+Finally, the **recipient** runs their own `test` of the tag against an extracted detection key such that 
+`FuzzyTagSecretKey == FuzzyTagDetectionKey` i.e. the probability of a false positive will be 2^-n == 2^-γ. This will
+produce a subset of messages likely intended for the **recipient**, with a smaller probability of false positives.
+
+Alternatively the **recipient**  can simply try and decrypt every message in the subset of messages that the server
+provided them (depending on the efficiency of the decryption method).
+
 ## Usage
 
 Generate a key pair: 
@@ -48,16 +80,18 @@ messaging service / privacy-preserving application.
 validate against a random public key with a maximum probability of 2^-gamma.
 
 ## Generating Tags
+
+Once in possession of a public key, a party in a metadata resistant app can use it to generate tags:
     
       let tag = public_key.generate_tag();
 
-This tag can be attached to a message in a metadata resistant system.
+These tags can then be attached to a message in a metadata resistant system.
 
-## Verifying Tags
+## Testing Tags
 
 First it is necessary to extract a detection key for a given false positive probability 0 <= 2^-n <= 2^-γ.
 
-This extracted key can then be given to an adversarial server can test a given tag against a detection key e.g.:
+This extracted key can then be given to an adversarial server. The server can then test a given tag against the detection key e.g.:
 
     let detection_key = key.extract(5);
     if detection_key.test_tag(tag) {