Make digest optional (#446)

As proposed in #442 this makes `digest` an
optional feature that is not covered by the
SemVer public API stability guarantees.

Co-authored-by: Michael Rosenberg <michael@mrosenberg.pub>

CHANGELOG.md

@@ -5,6 +5,7 @@ major series.
 
 ## 4.x series
 
+* Make `digest` an optional feature
 * Make `rand_core` an optional feature
 * Add target u32/u64 backend overrides
 * Migrate documentation to docs.rs hosted

Cargo.toml

@@ -25,7 +25,7 @@ exclude = [
 
 [package.metadata.docs.rs]
 rustdoc-args = ["--html-in-header", "docs/assets/rustdoc-include-katex-header.html", "--cfg", "docsrs"]
-features = ["serde", "simd_backend", "rand_core"]
+features = ["serde", "simd_backend", "rand_core", "digest"]
 
 [badges]
 travis-ci = { repository = "dalek-cryptography/curve25519-dalek", branch = "master"}
@@ -45,7 +45,7 @@ harness = false
 [dependencies]
 cfg-if = "1"
 rand_core = { version = "0.6", default-features = false, optional = true }
-digest = { version = "0.10", default-features = false }
+digest = { version = "0.10", default-features = false, optional = true }
 subtle = { version = "^2.2.1", default-features = false }
 serde = { version = "1.0", default-features = false, optional = true, features = ["derive"] }
 # The original packed_simd package was orphaned, see

Makefile

@@ -1,4 +1,4 @@
-FEATURES := simd_backend serde rand_core
+FEATURES := simd_backend serde rand_core digest
 
 doc:
 	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --cfg docsrs

src/edwards.rs

@@ -101,7 +101,9 @@ use core::ops::{Add, Neg, Sub};
 use core::ops::{AddAssign, SubAssign};
 use core::ops::{Mul, MulAssign};
 
+#[cfg(feature = "digest")]
 use digest::{generic_array::typenum::U64, Digest};
+
 use subtle::Choice;
 use subtle::ConditionallyNegatable;
 use subtle::ConditionallySelectable;
@@ -534,6 +536,7 @@ impl EdwardsPoint {
         CompressedEdwardsY(s)
     }
 
+    #[cfg(feature = "digest")]
     /// Maps the digest of the input bytes to the curve. This is NOT a hash-to-curve function, as
     /// it produces points with a non-uniform distribution. Rather, it performs something that
     /// resembles (but is not) half of the
@@ -1683,7 +1686,7 @@ mod test {
     //     https://github.com/signalapp/libsignal-protocol-c/ //
     ////////////////////////////////////////////////////////////
 
-    #[cfg(feature = "alloc")]
+    #[cfg(all(feature = "alloc", feature = "digest"))]
     fn test_vectors() -> Vec<Vec<&'static str>> {
         vec![
             vec![
@@ -1731,7 +1734,7 @@ mod test {
 
     #[test]
     #[allow(deprecated)]
-    #[cfg(feature = "alloc")]
+    #[cfg(all(feature = "alloc", feature = "digest"))]
     fn elligator_signal_test_vectors() {
         for vector in test_vectors().iter() {
             let input = hex::decode(vector[0]).unwrap();

src/lib.rs

@@ -36,6 +36,7 @@ extern crate alloc;
 #[macro_use]
 extern crate std;
 
+#[cfg(feature = "digest")]
 pub use digest;
 
 // Internal macros. Must come first!

src/ristretto.rs

@@ -168,7 +168,9 @@ use core::ops::{Mul, MulAssign};
 #[cfg(feature = "rand_core")]
 use rand_core::{CryptoRng, RngCore};
 
+#[cfg(feature = "digest")]
 use digest::generic_array::typenum::U64;
+#[cfg(feature = "digest")]
 use digest::Digest;
 
 use crate::constants;
@@ -689,6 +691,7 @@ impl RistrettoPoint {
         RistrettoPoint::from_uniform_bytes(&uniform_bytes)
     }
 
+    #[cfg(feature = "digest")]
     /// Hash a slice of bytes into a `RistrettoPoint`.
     ///
     /// Takes a type parameter `D`, which is any `Digest` producing 64
@@ -705,7 +708,8 @@ impl RistrettoPoint {
     ///
     /// # Example
     ///
-    /// ```
+    #[cfg_attr(feature = "digest", doc = "```")]
+    #[cfg_attr(not(feature = "digest"), doc = "```ignore")]
     /// # use curve25519_dalek::ristretto::RistrettoPoint;
     /// use sha2::Sha512;
     ///
@@ -726,6 +730,7 @@ impl RistrettoPoint {
         RistrettoPoint::from_hash(hash)
     }
 
+    #[cfg(feature = "digest")]
     /// Construct a `RistrettoPoint` from an existing `Digest` instance.
     ///
     /// Use this instead of `hash_from_bytes` if it is more convenient

src/scalar.rs

@@ -82,15 +82,14 @@
 //! ```
 //!
 //! There is also a constructor that reduces a \\(512\\)-bit integer,
-//! [`Scalar::from_bytes_mod_order_wide`](struct.Scalar.html#method.from_bytes_mod_order_wide).
+//! [`Scalar::from_bytes_mod_order_wide`].
 //!
 //! To construct a `Scalar` as the hash of some input data, use
-//! [`Scalar::hash_from_bytes`](struct.Scalar.html#method.hash_from_bytes),
-//! which takes a buffer, or
-//! [`Scalar::from_hash`](struct.Scalar.html#method.from_hash),
-//! which allows an IUF API.
+//! [`Scalar::hash_from_bytes`], which takes a buffer, or
+//! [`Scalar::from_hash`], which allows an IUF API.
 //!
-//! ```
+#![cfg_attr(feature = "digest", doc = "```")]
+#![cfg_attr(not(feature = "digest"), doc = "```ignore")]
 //! # fn main() {
 //! use sha2::{Digest, Sha512};
 //! use curve25519_dalek::scalar::Scalar;
@@ -108,12 +107,16 @@
 //! # }
 //! ```
 //!
+//! See also `Scalar::hash_from_bytes` and `Scalar::from_hash` that
+//! reduces a \\(512\\)-bit integer, if the optional `digest` feature
+//! has been enabled.
+//!
 //! Finally, to create a `Scalar` with a specific bit-pattern
 //! (e.g., for compatibility with X/Ed25519
 //! ["clamping"](https://github.com/isislovecruft/ed25519-dalek/blob/f790bd2ce/src/ed25519.rs#L349)),
-//! use [`Scalar::from_bits`](struct.Scalar.html#method.from_bits). This
-//! constructs a scalar with exactly the bit pattern given, without any
-//! assurances as to reduction modulo the group order:
+//! use [`Scalar::from_bits`]. This constructs a scalar with exactly
+//! the bit pattern given, without any assurances as to reduction
+//! modulo the group order:
 //!
 //! ```
 //! use curve25519_dalek::scalar::Scalar;
@@ -155,7 +158,9 @@ use cfg_if::cfg_if;
 #[cfg(feature = "rand_core")]
 use rand_core::{CryptoRng, RngCore};
 
+#[cfg(feature = "digest")]
 use digest::generic_array::typenum::U64;
+#[cfg(feature = "digest")]
 use digest::Digest;
 
 use subtle::Choice;
@@ -595,6 +600,7 @@ impl Scalar {
         Scalar::from_bytes_mod_order_wide(&scalar_bytes)
     }
 
+    #[cfg(feature = "digest")]
     /// Hash a slice of bytes into a scalar.
     ///
     /// Takes a type parameter `D`, which is any `Digest` producing 64
@@ -604,7 +610,8 @@ impl Scalar {
     ///
     /// # Example
     ///
-    /// ```
+    #[cfg_attr(feature = "digest", doc = "```")]
+    #[cfg_attr(not(feature = "digest"), doc = "```ignore")]
     /// # use curve25519_dalek::scalar::Scalar;
     /// use sha2::Sha512;
     ///
@@ -624,6 +631,7 @@ impl Scalar {
         Scalar::from_hash(hash)
     }
 
+    #[cfg(feature = "digest")]
     /// Construct a scalar from an existing `Digest` instance.
     ///
     /// Use this instead of `hash_from_bytes` if it is more convenient