Merge branch 'release/0.20.0'

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "curve25519-dalek"
-version = "0.19.0"
+version = "0.20.0"
 authors = ["Isis Lovecruft <isis@patternsinthevoid.net>",
            "Henry de Valence <hdevalence@hdevalence.ca>"]
 readme = "README.md"
@@ -42,23 +42,23 @@ harness = false
 
 [dependencies]
 rand = { version = "0.5", default-features = false }
-byteorder = { version = "1", default-features = false, features = ["i128"] }
+byteorder = { version = "^1.2.3", default-features = false, features = ["i128"] }
 digest = "0.7"
 generic-array = "0.9"
 clear_on_drop = "=0.2.3"
-subtle = { version = "0.7", features = ["generic-impls"], default-features = false }
+subtle = { version = "1", default-features = false }
 serde = { version = "1.0", optional = true }
-packed_simd = { version = "0.1.0", features = ["into_bits"], optional = true }
+packed_simd = { version = "0.3.0", features = ["into_bits"], optional = true }
 
 [build-dependencies]
 rand = { version = "0.5", default-features = false }
-byteorder = { version = "1", default-features = false, features = ["i128"] }
+byteorder = { version = "^1.2.3", default-features = false, features = ["i128"] }
 digest = "0.7"
 generic-array = "0.9"
 clear_on_drop = "=0.2.3"
-subtle = { version = "0.7", features = ["generic-impls"], default-features = false }
+subtle = { version = "1", default-features = false }
 serde = { version = "1.0", optional = true }
-packed_simd = { version = "0.1.0", features = ["into_bits"], optional = true }
+packed_simd = { version = "0.3.0", features = ["into_bits"], optional = true }
 
 [features]
 nightly = ["subtle/nightly", "clear_on_drop/nightly"]

README.md

@@ -26,11 +26,6 @@ prime-order group from a non-prime-order Edwards curve.  This provides the
 speed and safety benefits of Edwards curve arithmetic, without the pitfalls of
 cofactor-related abstraction mismatches.
 
-## Stability
-
-We have recently released a `1.0.0-pre.0` version of `curve25519-dalek` and
-would greatly appreciate testing and feedback on our API and performance.
-
 # Documentation
 
 The semver-stable, public-facing `curve25519-dalek` API is documented
@@ -50,7 +45,7 @@ make doc-internal
 To import `curve25519-dalek`, add the following to the dependencies section of
 your project's `Cargo.toml`:
 ```toml
-curve25519-dalek = "^0.18"
+curve25519-dalek = "0.20"
 ```
 Then import the crate as:
 ```rust,no_run
@@ -147,6 +142,22 @@ cargo bench --no-default-features --features "std avx2_backend"
 Performance is a secondary goal behind correctness, safety, and
 clarity, but we aim to be competitive with other implementations.
 
+# FFI
+
+Unfortunately, we have no plans to add FFI to `curve25519-dalek` directly.  The
+reason is that we use Rust features to provide an API that maintains safety
+invariants, which are not possible to maintain across an FFI boundary.  For
+instance, as described in the _Safety_ section above, invalid points are
+impossible to construct, and this would not be the case if we exposed point
+operations over FFI.
+
+However, `curve25519-dalek` is designed as a *mid-level* API, aimed at
+implementing other, higher-level primitives.  Instead of providing FFI at the
+mid-level, our suggestion is to implement the higher-level primitive (a
+signature, PAKE, ZKP, etc) in Rust, using `curve25519-dalek` as a dependency,
+and have that crate provide a minimal, byte-buffer-oriented FFI specific to
+that primitive.
+
 # Contributing
 
 Please see [CONTRIBUTING.md][contributing].

src/curve_models/mod.rs

@@ -97,7 +97,7 @@
 //! output of an addition or doubling always lies in \\( \mathbb P\^1 \times
 //! \mathbb P\^1\\), and the choice of which formula to use is replaced
 //! by a choice of whether to convert the result to \\( \mathbb P\^2 \\)
-//! or \\(\mathbb P\^2 \\).  However, this tweak is not described in
+//! or \\(\mathbb P\^3 \\).  However, this tweak is not described in
 //! their paper, only in their software.
 //!
 //! Our naming for the `CompletedPoint` (\\(\mathbb P\^1 \times \mathbb

src/ristretto.rs

@@ -242,24 +242,30 @@ impl CompressedRistretto {
             return None;
         }
 
-        // Step 2.  The rest.  (XXX write comments)
+        // Step 2.  Compute (X:Y:Z:T).
         let one = FieldElement::one();
         let ss = s.square();
-        let yden = &one + &ss; // 1 - a*s^2
+        let u1 = &one + &ss;      //  1 - as²    where a=-1
-        let ynum = &one - &ss; // 1 + a*s^2
+        let u2 = &one - &ss;      //  1 + as²
-        let yden_sqr = yden.square();
+        let u1_sqr = u1.square(); // (1 + as²)²
-        let xden_sqr = &(&(-&constants::EDWARDS_D) * &ynum.square()) - &yden_sqr;
 
-        let (ok, invsqrt) = (&xden_sqr * &yden_sqr).invsqrt();
+        // v == ad(1-as²)² - (1+as²)²            where d=-121665/121666
+        let v = &(&(-&constants::EDWARDS_D) * &u2.square()) - &u1_sqr;
 
-        let xden_inv = &invsqrt * &yden;
+        let (ok, I) = (&v * &u1_sqr).invsqrt(); // 1/sqrt(vu1²)
-        let yden_inv = &invsqrt * &(&xden_inv * &xden_sqr);
 
-        let mut x = &(&s + &s) * &xden_inv; // 2*s*xden_inv
+        let Dx = &I * &u1;         // 1/sqrt(v)
-        let x_is_negative = x.is_negative();
+        let Dy = &I * &(&Dx * &v); // 1/u2
-        x.conditional_negate(x_is_negative);
-        let y = &ynum * &yden_inv;
 
+        // x == | 2s/sqrt(v) | == + sqrt(4s²/(ad(1+as²)² - (1-as²)²))
+        let mut x = &(&s + &s) * &Dx;
+        let x_neg = x.is_negative();
+        x.conditional_negate(x_neg);
+
+        // y == (1-as²)/(1+as²)
+        let y = &u2 * &Dy;
+
+        // t == ((1+as²) sqrt(4s²/(ad(1+as²)² - (1-as²)²)))/(1-as²)
         let t = &x * &y;
 
         if ok.unwrap_u8() == 0u8 || t.is_negative().unwrap_u8() == 1u8 || y.is_zero().unwrap_u8() == 1u8 {