Merge branch 'release/0.6.0'

Author: hdevalence

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zkp"
-version = "0.5.0"
+version = "0.6.0"
 authors = ["Henry de Valence <hdevalence@hdevalence.ca>"]
 license = "CC0-1.0"
 repository = "https://github.com/hdevalence/zkp"
@@ -13,24 +13,26 @@ exclude = [
 ]
 
 [dependencies]
-sha2 = "0.8"
 merlin = "1"
 rand = "0.6"
 serde = "1.0"
 serde_derive = "1.0"
-
-[dev-dependencies]
-bincode = "1"
+failure = "0.1.5"
+failure_derive = "0.1.5"
 
 [dependencies.curve25519-dalek]
 features = ["serde", "nightly", "alloc"]
 version = "1"
-default-features = false
+
+[dev-dependencies]
+bincode = "1"
+sha2 = "0.8"
 
 [features]
 default = ["u64_backend"]
 u32_backend = ["curve25519-dalek/u32_backend"]
 u64_backend = ["curve25519-dalek/u64_backend"]
-avx2_backend = ["curve25519-dalek/avx2_backend"]
+simd_backend = ["curve25519-dalek/simd_backend"]
 nightly = ["curve25519-dalek/nightly"]
 bench = [ ]
+debug-transcript = ["merlin/debug-transcript"]

README.md

@@ -1,34 +1,103 @@
-# zkp
+# zkp: a toolkit for Schnorr proofs
 
-This crate has an experimental zero-knowledge proof compiler
-implemented using Rust macros.
+This crate has a toolkit for Schnorr-style zero-knowledge proofs,
+instantiated using the ristretto255 group.
 
-It provides a DSL resembling Camenisch-Stadler notation for proving
-statements about discrete logarithms in the Decaf group on
-Curve25519, as implemented in
-[`curve25519-dalek`](https://github.com/isislovecruft/curve25519-dalek).
-Note that both the Decaf implementation in `curve25519-dalek`, *as
-well as this library*, are currently **UNFINISHED, UNREVIEWED, AND
-EXPERIMENTAL**.  (I haven't actually checked carefully that the
-proofs are sound, for instance...)
+It provides two levels of API:
 
-## Warning
+* a higher-level, declarative API based around the `define_proof` macro,
+  which provides an embedded DSL for specifying proof statements in
+  Camenisch-Stadler-like notation:
+  ```
+  define_proof! {
+    vrf_proof,   // Name of the module for generated implementation
+    "VRF",       // Label for the proof statement
+    (x),         // Secret variables
+    (A, G, H),   // Public variables unique to each proof
+    (B) :        // Public variables common between proofs
+    A = (x * B), // Statements to prove
+    G = (x * H) 
+    }
+  ```
+  This expands into a module containing an implementation of proving,
+  verification, and batch verification.  Proving uses constant-time
+  implementations, and the proofs have a derived implementation of
+  (memory-safe) serialization and deserialization via Serde.
 
-This code has **not** yet received sufficient peer review by other qualified
-cryptographers to be considered in any way, shape, or form, safe.
+* a lower-level, imperative API inspired by [Bellman][bellman], which
+  provides a constraint system for Schnorr-style statements.  This
+  allows programmable construction of proof statements at runtime.  The
+  higher-level `define_proof` macro expands into an invocation of the
+  lower-level API.
+  The lower-level API is contained in the `toolbox` module.
 
-**USE AT YOUR OWN RISK**
+# Examples
 
-## Documentation
+Examples of how to use the API can be found in the library's `tests`
+directory.
 
-Extensive documentation is available [here](https://docs.rs/zkp).
+Currently, the examples include:
 
-# Pre-Release TODOs
+* Specification of an "anonymous credential presentation with 10 hidden
+  attributes" proof from CMZ'13.  Depending on the backend selection, the
+  generated implementation is between 20 to 40 times faster than the benchmark
+  numbers reported in that paper.
 
-* don't use any yolocrypto features (i.e. stabilise decaf in curve25519-dalek)
-* make sure proofs are sound
-* make a CONTRIBUTING.md
+* A transcript-based signature and VRF construction with an auto-generated
+  implementation.  This includes an example of using the online interactive
+  composition [described in the Merlin blog post][merlin_blog] to provide chained
+  signatures with a counterparty.
 
-# Future TODOs
+* An example of using the lower-level constraint system API.
 
-* ???
+
+# Use and features
+
+To enable the `define_proof` macro, import the crate like so:
+```
+#[macro_use]
+extern crate zkp;
+```
+
+#### Nightly features
+
+The `nightly` feature enables nightly-specific features.  It is required
+to build the documentation.
+
+#### Backend selection
+
+`zkp` provides the following pass-through features to select a
+`curve25519-dalek` backend:
+
+* `u32_backend`
+* `u64_backend`
+* `simd_backend`
+
+#### Transcript debugging
+
+The `debug-transcript` feature is for development and testing, and
+prints a log of the data fed into the proof transcript.
+
+#### Autogenerated benchmarks
+
+The `define_proof` macro builds benchmarks for the generated proof
+statements, but because these are generated in the client crate (where
+the macro expansion happens), they need an extra step to be enabled.
+
+**To enable generated benchmarks in your crate, do the following**:
+
+* Add a `bench` feature to your crate's `Cargo.toml`;
+* Add `#[cfg_attr(feature = "bench", feature(test))]` to your crate's
+  `lib.rs` or `main.rs`, to enable Rust's nightly-only benchmark
+  feature.
+
+# WARNING
+
+**THIS IMPLEMENTATION IS NOT YET READY FOR PRODUCTION USE**
+
+While I expect the 1.0 version to be largely unchanged from the current
+code, for now there are no stability guarantees on the proofs, so they
+should not yet be deployed.
+
+[bellman]: https://github.com/zkcrypto/bellman
+[merlin_blog]: https://medium.com/@hdevalence/merlin-flexible-composable-transcripts-for-zero-knowledge-proofs-28d9fda22d9a