Publishing v0.4.0-pre.1 (#72)

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0-pre.1 (April 1, 2022)
+* Updated to be in sync with draft-irtf-cfrg-voprf-09, with
+  the addition of the POPRF mode
+* Added support for running the API without performing allocations
+* Revamped the way the Group trait was used, so as to be more easily
+  extendable to other groups
+* Added common traits for each public-facing struct, including serde
+  support
+
 ## 0.3.0 (October 25, 2021)
 
 * Updated to be in sync with draft-irtf-cfrg-voprf-08

Cargo.toml

@@ -9,7 +9,7 @@ name = "voprf"
 readme = "README.md"
 repository = "https://github.com/novifinancial/voprf/"
 rust-version = "1.57"
-version = "0.3.0"
+version = "0.4.0-pre.1"
 
 [features]
 alloc = []

README.md

@@ -16,7 +16,7 @@ Installation
 Add the following line to the dependencies of your `Cargo.toml`:
 
 ```
-voprf = "0.3"
+voprf = "0.4.0-pre.1"
 ```
 
 ### Minimum Supported Rust Version

src/ciphersuite.rs

@@ -21,7 +21,7 @@ where
         IsLess<U256> + IsLessOrEqual<<Self::Hash as BlockSizeUser>::BlockSize>,
 {
     /// The ciphersuite identifier as dictated by
-    /// <https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html>
+    /// <https://datatracker.ietf.org/doc/draft-irtf-cfrg-voprf/>
     const ID: u16;
 
     /// A finite cyclic group along with a point representation that allows some

src/common.rs

@@ -153,7 +153,7 @@ where
     <CS::Hash as OutputSizeUser>::OutputSize:
         IsLess<U256> + IsLessOrEqual<<CS::Hash as BlockSizeUser>::BlockSize>,
 {
-    // https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html#section-3.3.2.2-1
+    // https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-09.html#section-2.2.1
 
     let (m, z) = compute_composites::<CS, _, _>(Some(k), b, cs, ds, mode)?;
 
@@ -216,7 +216,7 @@ where
     <CS::Hash as OutputSizeUser>::OutputSize:
         IsLess<U256> + IsLessOrEqual<<CS::Hash as BlockSizeUser>::BlockSize>,
 {
-    // https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html#section-3.3.4.1-2
+    // https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-09.html#section-2.2.2
     let (m, z) = compute_composites::<CS, _, _>(None, b, cs, ds, mode)?;
     let t2 = (a * &proof.s_scalar) + &(b * &proof.c_scalar);
     let t3 = (m * &proof.s_scalar) + &(z * &proof.c_scalar);
@@ -285,7 +285,7 @@ where
     <CS::Hash as OutputSizeUser>::OutputSize:
         IsLess<U256> + IsLessOrEqual<<CS::Hash as BlockSizeUser>::BlockSize>,
 {
-    // https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html#section-3.3.2.3-2
+    // https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-09.html#section-2.2.1
 
     let elem_len = <CS::Group as Group>::ElemLen::U16.to_be_bytes();
 
@@ -430,7 +430,7 @@ where
 }
 
 /// Generates the contextString parameter as defined in
-/// <https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html>
+/// <https://datatracker.ietf.org/doc/draft-irtf-cfrg-voprf/>
 pub(crate) fn create_context_string<CS: CipherSuite>(mode: Mode) -> GenericArray<u8, U11>
 where
     <CS::Hash as OutputSizeUser>::OutputSize:

src/lib.rs

@@ -8,20 +8,17 @@
 //! An implementation of a verifiable oblivious pseudorandom function (VOPRF)
 //!
 //! Note: This implementation is in sync with
-//! [draft-irtf-cfrg-voprf-08](https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html),
+//! [draft-irtf-cfrg-voprf-09](https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-09.html),
 //! but this specification is subject to change, until the final version
 //! published by the IETF.
 //!
 //! # Overview
 //!
 //! A verifiable oblivious pseudorandom function is a protocol that is evaluated
-//! between a client and a server. They must first agree on a collection of
+//! between a client and a server. They must first agree on a finite cyclic
-//! primitives to be kept consistent throughout protocol execution. These
+//! group along with a point representation.
-//! include:
-//! - a finite cyclic group along with a point representation, and
-//! - a hashing function.
 //!
-//! We will use the following choices in this example:
+//! We will use the following choice in this example:
 //!
 //! ```ignore
 //! type CipherSuite = voprf::Ristretto255;
@@ -29,19 +26,22 @@
 //!
 //! ## Modes of Operation
 //!
-//! VOPRF can be used in two modes:
+//! VOPRF can be used in three modes:
 //! - [Base Mode](#base-mode), which corresponds to a normal OPRF evaluation
 //!   with no support for the verification of the OPRF outputs
 //! - [Verifiable Mode](#verifiable-mode), which corresponds to an OPRF
 //!   evaluation where the outputs can be verified against a server public key
+//!   (VOPRF)
+//! - [Partially Oblivious Verifiable Mode](#metadata), which corresponds to a
+//!   VOPRF, where a public input can be supplied to the PRF computation
 //!
-//! In either mode, the protocol begins with a client blinding, followed by a
+//! In all of these modes, the protocol begins with a client blinding, followed
-//! server evaluation, and finishes with a client finalization.
+//! by a server evaluation, and finishes with a client finalization.
 //!
 //! ## Base Mode
 //!
-//! In base mode, a [OprfClient] interacts with a [OprfServer]
+//! In base mode, an [OprfClient] interacts with an [OprfServer]
-//! to compute the output of the VOPRF.
+//! to compute the output of the OPRF.
 //!
 //! ### Server Setup
 //!
@@ -65,8 +65,8 @@
 //! ### Client Blinding
 //!
 //! In the first step, the client chooses an input, and runs
-//! [OprfClient::blind] to produce a [OprfClientBlindResult],
+//! [OprfClient::blind] to produce an [OprfClientBlindResult],
-//! which consists of a [BlindedElement] to be sent to the server and a
+//! which consists of a [BlindedElement] to be sent to the server and an
 //! [OprfClient] which must be persisted on the client for the final
 //! step of the VOPRF protocol.
 //!
@@ -340,7 +340,7 @@
 //! let messages: Vec<_> = messages.collect();
 //! ```
 //!
-//! If `alloc` is available, [VoprfServer::batch_evaluate] can be called
+//! If `alloc` is available, `VoprfServer::batch_evaluate` can be called
 //! to avoid having to collect output manually:
 //!
 //! ```
@@ -419,16 +419,19 @@
 //!
 //! ## Metadata
 //!
-//! The optional metadata parameter included in the protocol allows clients and
+//! The optional metadata parameter included in the POPRF mode allows clients
-//! servers (of either mode) to cryptographically bind additional data to the
+//! and servers to cryptographically bind additional data to the
 //! VOPRF output. This metadata is known to both parties at the start of the
 //! protocol, and is inserted under the server's evaluate step and the client's
 //! finalize step. This metadata can be constructed with some type of
 //! higher-level domain separation to avoid cross-protocol attacks or related
 //! issues.
 //!
-//! A custom metadata can be specified, for example, by:
+//! The API for POPRF mode is similar to VOPRF mode, except that a [PoprfServer]
-//! `Some(b"custom metadata")`.
+//! and [PoprfClient] are used, and that each of the functions accept an
+//! additional (and optional) info parameter which represents the public input.
+//! See <https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-09.html#name-poprf-public-input>
+//! for more detailed information on how this public input should be used.
 //!
 //! # Features
 //!

src/poprf.rs

@@ -319,7 +319,7 @@ where
         Ok(PoprfServerBatchEvaluateResult { messages, proof })
     }
 
-    /// Alternative version of [`batch_evaluate`](Self::batch_evaluate) without
+    /// Alternative version of `batch_evaluate` without
     /// memory allocation. Returned [`PreparedEvaluationElement`] have to
     /// be [`collect`](Iterator::collect)ed and passed into
     /// [`batch_evaluate_finish`](Self::batch_evaluate_finish).

src/voprf.rs

@@ -310,7 +310,7 @@ where
         Ok(VoprfServerBatchEvaluateResult { messages, proof })
     }
 
-    /// Alternative version of [`batch_evaluate`](Self::batch_evaluate) without
+    /// Alternative version of `batch_evaluate` without
     /// memory allocation. Returned [`PreparedEvaluationElement`] have to be
     /// [`collect`](Iterator::collect)ed and passed into
     /// [`batch_evaluate_finish`](Self::batch_evaluate_finish).