[WIP] signature v2.0.0-pre

This commit contains the first breaking changes to the `signature` crate
made since its initial 1.0 stabilization. Planning for these changes
occurred in #237.

The following changes have been made:

- The `Signature` trait has been renamed to `SignatureEncoding`. The
  `Signature` bound on `*Signer` and `*Verifier` traits has been
  removed, meaning there are no longer any mandatory trait bounds on the
  signature paramters at all.

- The `AsRef<[u8]>` bound formerly found on the `Signature` crate has
  been replaced with an associated `Repr` type, inspired by the
  `group::GroupEncoding` trait. This means signature types no longer
  need to retain a serialized form, and can parse the bag-of-bytes
  representation to something more convenient, which is useful for e.g.
  batch verification.

- The `std` feature is no longer enabled by default, which matches the
  other RustCrypto/traits crates.

- The `derive-preview` and `hazmat-preview` features have been
  stabilized.

- The former `Keypair` trait has been renamed to `KeypairRef`, and the
  signature generic parameter removed. A new `Keypair` trait has been
  added which returns an owned instance of the associated
  `VerifyingKey`, and a blanket impl of `Keypair` for `KeypairRef` has
  been added. This addresses the issues described in #1124.

Author: tarcieri

.github/workflows/signature.yml

@@ -37,10 +37,11 @@ jobs:
           override: true
           profile: minimal
       - run: cargo build --target ${{ matrix.target }} --release --no-default-features
-      - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features derive-preview
+      - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features derive
       - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features digest-preview
-      - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features hazmat-preview
+      - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features hazmat
       - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features rand-preview
+      - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features derive,digest-preview,hazmat,rand-preview
 
   minimal-versions:
     uses: RustCrypto/actions/.github/workflows/minimal-versions.yml@master
@@ -83,4 +84,4 @@ jobs:
           override: true
           profile: minimal
       - run: cargo test --release
-        working-directory: signature/derive
+        working-directory: signature/derive

signature/Cargo.toml

@@ -22,14 +22,13 @@ hex-literal = "0.3"
 sha2 = { version = "0.10", default-features = false }
 
 [features]
-default = ["std"]
 std = []
 
+derive = ["signature_derive"]
+
 # Preview features are unstable and exempt from semver.
 # See https://docs.rs/signature/latest/signature/#unstable-features for more information.
-derive-preview = ["digest-preview", "signature_derive"]
 digest-preview = ["digest"]
-hazmat-preview = []
 rand-preview = ["rand_core"]
 
 [package.metadata.docs.rs]

signature/README.md

@@ -1,4 +1,4 @@
-# RustCrypto: Digital Signature Algorithms
+# [RustCrypto]: Digital Signature Algorithms
 
 [![crate][crate-image]][crate-link]
 [![Docs][docs-image]][docs-link]
@@ -8,14 +8,10 @@
 [![Project Chat][chat-image]][chat-link]
 
 This crate contains traits which provide generic, object-safe APIs for
-generating and verifying [digital signatures][1].
+generating and verifying [digital signatures].
 
-Used by the [`ecdsa`][2] and [`ed25519`][3] crates, with forthcoming support
-in the [`rsa`][4] crate.
-
-See also the [Signatory][5] crate for trait wrappers for using these traits
-with many popular Rust cryptography crates, including `ed25519-dalek`, *ring*,
-`secp256k1-rs`, and `sodiumoxide`.
+Used by the [`dsa`], [`ecdsa`], [`ed25519`], and [`rsa`] crates maintained by
+the [RustCrypto] organization, as well as [`ed25519-dalek`].
 
 [Documentation][docs-link]
 
@@ -63,10 +59,11 @@ dual licensed as above, without any additional terms or conditions.
 [chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
 [chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260048-signatures
 
-[//]: # (general links)
+[//]: # (links)
 
-[1]: https://en.wikipedia.org/wiki/Digital_signature
-[2]: https://github.com/RustCrypto/signatures/tree/master/ecdsa
-[3]: https://github.com/RustCrypto/signatures/tree/master/ed25519
-[4]: https://github.com/RustCrypto/RSA
-[5]: https://docs.rs/signatory
+[digital signatures]: https://en.wikipedia.org/wiki/Digital_signature
+[`dsa`]: https://github.com/RustCrypto/signatures/tree/master/dsa
+[`ecdsa`]: https://github.com/RustCrypto/signatures/tree/master/ecdsa
+[`ed25519`]: https://github.com/RustCrypto/signatures/tree/master/ed25519
+[`ed25519-dalek`]: https://github.com/dalek-cryptography/ed25519-dalek
+[`rsa`]: https://github.com/RustCrypto/RSA

signature/derive/src/lib.rs

@@ -129,7 +129,7 @@ fn emit_digest_signer_impl(input: DeriveInput) -> TokenStream2 {
 
     let mut params = DeriveParams::new(input);
     params.add_bound(&d_ident, parse_quote!(::signature::digest::Digest));
-    params.add_bound(&s_ident, parse_quote!(::signature::Signature));
+    params.add_param(&s_ident);
     params.add_bound(
         &Ident::new("Self", Span::call_site()),
         parse_quote!(::signature::hazmat::PrehashSigner<#s_ident>),
@@ -167,7 +167,7 @@ fn emit_digest_verifier_impl(input: DeriveInput) -> TokenStream2 {
 
     let mut params = DeriveParams::new(input);
     params.add_bound(&d_ident, parse_quote!(::signature::digest::Digest));
-    params.add_bound(&s_ident, parse_quote!(::signature::Signature));
+    params.add_param(&s_ident);
     params.add_bound(
         &Ident::new("Self", Span::call_site()),
         parse_quote!(::signature::hazmat::PrehashVerifier<#s_ident>),
@@ -235,14 +235,7 @@ impl DeriveParams {
     /// Add a generic parameter with the given bound.
     fn add_bound(&mut self, name: &Ident, bound: TraitBound) {
         if name != "Self" {
-            self.impl_generics.push(TypeParam {
-                attrs: vec![],
-                ident: name.clone(),
-                colon_token: None,
-                bounds: Default::default(),
-                eq_token: None,
-                default: None,
-            });
+            self.add_param(name);
         }
 
         let type_path = parse_quote!(#name);
@@ -261,6 +254,18 @@ impl DeriveParams {
             .predicates
             .push(WherePredicate::Type(predicate_type))
     }
+
+    /// Add a generic parameter without a bound.
+    fn add_param(&mut self, name: &Ident) {
+        self.impl_generics.push(TypeParam {
+            attrs: vec![],
+            ident: name.clone(),
+            colon_token: None,
+            bounds: Default::default(),
+            eq_token: None,
+            default: None,
+        });
+    }
 }
 
 #[cfg(test)]
@@ -345,7 +350,6 @@ mod tests {
                 impl<C: EllipticCurve, __D, __S> ::signature::DigestSigner<__D, __S> for MySigner<C>
                 where
                     __D: ::signature::digest::Digest,
-                    __S: ::signature::Signature,
                     Self: ::signature::hazmat::PrehashSigner<__S>
                 {
                     fn try_sign_digest(&self, digest: __D) -> ::signature::Result<__S> {
@@ -374,7 +378,6 @@ mod tests {
                 impl<C: EllipticCurve, __D, __S> ::signature::DigestVerifier<__D, __S> for MyVerifier<C>
                 where
                     __D: ::signature::digest::Digest,
-                    __S: ::signature::Signature,
                     Self: ::signature::hazmat::PrehashVerifier<__S>
                 {
                     fn verify_digest(&self, digest: __D, signature: &__S) -> ::signature::Result<()> {

signature/src/encoding.rs

@@ -0,0 +1,21 @@
+//! Encoding support.
+
+use crate::{Error, Result};
+
+/// Support for decoding/encoding signatures as bytes.
+pub trait SignatureEncoding:
+    Clone + Sized + for<'a> TryFrom<&'a [u8], Error = Error> + Into<Self::Repr>
+{
+    /// Byte representation of a signature.
+    type Repr: 'static + AsRef<[u8]> + AsMut<[u8]> + Clone + Default + Send + Sync;
+
+    /// Decode signature from its byte representation.
+    fn from_bytes(bytes: &Self::Repr) -> Result<Self> {
+        Self::try_from(bytes.as_ref())
+    }
+
+    /// Encode signature as its byte representation.
+    fn to_bytes(&self) -> Self::Repr {
+        self.clone().into()
+    }
+}

signature/src/error.rs

@@ -22,11 +22,8 @@ pub type Result<T> = core::result::Result<T, Error>;
 ///
 /// [BB'06]: https://en.wikipedia.org/wiki/Daniel_Bleichenbacher
 #[derive(Default)]
+#[non_exhaustive]
 pub struct Error {
-    /// Prevent from being instantiated as `Error {}` when the `std` feature
-    /// is disabled
-    _private: (),
-
     /// Source of the error (if applicable).
     #[cfg(feature = "std")]
     source: Option<Box<dyn std::error::Error + Send + Sync + 'static>>,
@@ -50,7 +47,6 @@ impl Error {
         source: impl Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
     ) -> Self {
         Self {
-            _private: (),
             source: Some(source.into()),
         }
     }

signature/src/hazmat.rs

@@ -10,13 +10,13 @@
 //! feature is semi-unstable and not subject to regular 1.x SemVer guarantees.
 //! However, any breaking changes will be accompanied with a minor version bump.
 
-use crate::{Error, Signature};
+use crate::Error;
 
 #[cfg(feature = "rand-preview")]
 use crate::rand_core::{CryptoRng, RngCore};
 
 /// Sign the provided message prehash, returning a digital signature.
-pub trait PrehashSigner<S: Signature> {
+pub trait PrehashSigner<S> {
     /// Attempt to sign the given message digest, returning a digital signature
     /// on success, or an error if something went wrong.
     ///
@@ -35,7 +35,7 @@ pub trait PrehashSigner<S: Signature> {
 /// Sign the provided message prehash using the provided external randomness source, returning a digital signature.
 #[cfg(feature = "rand-preview")]
 #[cfg_attr(docsrs, doc(cfg(feature = "rand-preview")))]
-pub trait RandomizedPrehashSigner<S: Signature> {
+pub trait RandomizedPrehashSigner<S> {
     /// Attempt to sign the given message digest, returning a digital signature
     /// on success, or an error if something went wrong.
     ///
@@ -56,7 +56,7 @@ pub trait RandomizedPrehashSigner<S: Signature> {
 }
 
 /// Verify the provided message prehash using `Self` (e.g. a public key)
-pub trait PrehashVerifier<S: Signature> {
+pub trait PrehashVerifier<S> {
     /// Use `Self` to verify that the provided signature for a given message
     /// `prehash` is authentic.
     ///

signature/src/keypair.rs

@@ -1,17 +1,29 @@
 //! Signing keypairs.
 
-use crate::Signature;
-
 /// Signing keypair with an associated verifying key.
 ///
 /// This represents a type which holds both a signing key and a verifying key.
-pub trait Keypair<S: Signature>: AsRef<Self::VerifyingKey> {
+pub trait Keypair {
     /// Verifying key type for this keypair.
-    type VerifyingKey;
+    type VerifyingKey: Clone;
 
     /// Get the verifying key which can verify signatures produced by the
     /// signing key portion of this keypair.
-    fn verifying_key(&self) -> &Self::VerifyingKey {
-        self.as_ref()
+    fn verifying_key(&self) -> Self::VerifyingKey;
+}
+
+/// Signing keypair with an associated verifying key.
+///
+/// This represents a type which holds both a signing key and a verifying key.
+pub trait KeypairRef: AsRef<Self::VerifyingKey> {
+    /// Verifying key type for this keypair.
+    type VerifyingKey: Clone;
+}
+
+impl<K: KeypairRef> Keypair for K {
+    type VerifyingKey = <Self as KeypairRef>::VerifyingKey;
+
+    fn verifying_key(&self) -> Self::VerifyingKey {
+        self.as_ref().clone()
     }
 }

signature/src/lib.rs

@@ -43,24 +43,14 @@
 //! ## Implementation
 //!
 //! To accomplish the above goals, the [`Signer`] and [`Verifier`] traits
-//! provided by this are generic over a [`Signature`] return value, and use
-//! generic parameters rather than associated types. Notably, they use such
-//! a parameter for the return value, allowing it to be inferred by the type
-//! checker based on the desired signature type.
-//!
-//! The [`Signature`] trait is bounded on `AsRef<[u8]>`, enforcing that
-//! signature types are thin wrappers around a "bag-of-bytes"
-//! serialization. Inspiration for this approach comes from the Ed25519
-//! signature system, which was based on the observation that past
-//! systems were not prescriptive about how signatures should be represented
-//! on-the-wire, and that lead to a proliferation of different wire formats
-//! and confusion about which ones should be used. This crate aims to provide
-//! similar simplicity by minimizing the number of steps involved to obtain
-//! a serializable signature.
+//! provided by this are generic over a signature value, and use generic
+//! parameters rather than associated types. Notably, they use such a parameter
+//! for the return value, allowing it to be inferred by the type checker based
+//! on the desired signature type.
 //!
 //! ## Alternatives considered
 //!
-//! This crate is based on over two years of exploration of how to encapsulate
+//! This crate is based on many years of exploration of how to encapsulate
 //! digital signature systems in the most flexible, developer-friendly way.
 //! During that time many design alternatives were explored, tradeoffs
 //! compared, and ultimately the provided API was selected.
@@ -73,10 +63,7 @@
 //! - "Bag-of-bytes" serialization precludes signature providers from using
 //!   their own internal representation of a signature, which can be helpful
 //!   for many reasons (e.g. advanced signature system features like batch
-//!   verification). Alternatively each provider could define its own signature
-//!   type, using a marker trait to identify the particular signature algorithm,
-//!   have `From` impls for converting to/from `[u8; N]`, and a marker trait
-//!   for identifying a specific signature algorithm.
+//!   verification).
 //! - Associated types, rather than generic parameters of traits, could allow
 //!   more customization of the types used by a particular signature system,
 //!   e.g. using custom error types.
@@ -121,7 +108,7 @@
 //!   [`DigestSigner`] and [`DigestVerifier`], the `derive-preview` feature
 //!   can be used to derive [`Signer`] and [`Verifier`] traits which prehash
 //!   the input message using the [`PrehashSignature::Digest`] algorithm for
-//!   a given [`Signature`] type. When the `derive-preview` feature is enabled
+//!   a given signature type. When the `derive-preview` feature is enabled
 //!   import the proc macros with `use signature::{Signer, Verifier}` and then
 //!   add a `derive(Signer)` or `derive(Verifier)` attribute to the given
 //!   digest signer/verifier type. Enabling this feature also enables `digest`
@@ -146,10 +133,10 @@
 #[cfg(feature = "std")]
 extern crate std;
 
-#[cfg(all(feature = "signature_derive", not(feature = "derive-preview")))]
+#[cfg(all(feature = "signature_derive", not(feature = "derive")))]
 compile_error!(
     "The `signature_derive` feature should not be enabled directly. \
-    Use the `derive-preview` feature instead."
+    Use the `derive` feature instead."
 );
 
 #[cfg(all(feature = "digest", not(feature = "digest-preview")))]
@@ -168,28 +155,28 @@ compile_error!(
 #[cfg_attr(docsrs, doc(cfg(feature = "hazmat-preview")))]
 pub mod hazmat;
 
+mod encoding;
 mod error;
 mod keypair;
-mod signature;
 mod signer;
 mod verifier;
 
-#[cfg(feature = "derive-preview")]
-#[cfg_attr(docsrs, doc(cfg(feature = "derive-preview")))]
+#[cfg(feature = "digest-preview")]
+mod prehash_signature;
+
+pub use crate::{encoding::*, error::*, keypair::*, signer::*, verifier::*};
+
+#[cfg(feature = "derive")]
+#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
 pub use signature_derive::{Signer, Verifier};
 
-#[cfg(all(feature = "derive-preview", feature = "digest-preview"))]
-#[cfg_attr(
-    docsrs,
-    doc(cfg(all(feature = "derive-preview", feature = "digest-preview")))
-)]
+#[cfg(all(feature = "derive", feature = "digest-preview"))]
+#[cfg_attr(docsrs, doc(cfg(all(feature = "derive", feature = "digest-preview"))))]
 pub use signature_derive::{DigestSigner, DigestVerifier};
 
 #[cfg(feature = "digest-preview")]
-pub use digest;
+pub use {crate::prehash_signature::*, digest};
 
 #[cfg(feature = "rand-preview")]
 #[cfg_attr(docsrs, doc(cfg(feature = "rand-preview")))]
 pub use rand_core;
-
-pub use crate::{error::*, keypair::*, signature::*, signer::*, verifier::*};

signature/src/prehash_signature.rs

@@ -0,0 +1,32 @@
+//! `PrehashSignature` trait.
+
+/// For intra-doc link resolution.
+#[allow(unused_imports)]
+use crate::{
+    signer::{DigestSigner, Signer},
+    verifier::{DigestVerifier, Verifier},
+};
+
+/// Marker trait for `Signature` types computable as `𝐒(𝐇(𝒎))`
+/// i.e. ones which prehash a message to be signed as `𝐇(𝒎)`
+///
+/// Where:
+///
+/// - `𝐒`: signature algorithm
+/// - `𝐇`: hash (a.k.a. digest) function
+/// - `𝒎`: message
+///
+/// This approach is relatively common in signature schemes based on the
+/// [Fiat-Shamir heuristic].
+///
+/// For signature types that implement this trait, when the `derive-preview`
+/// Cargo feature is enabled a custom derive for [`Signer`] is available for any
+/// types that impl [`DigestSigner`], and likewise for deriving [`Verifier`] for
+/// types which impl [`DigestVerifier`].
+///
+/// [Fiat-Shamir heuristic]: https://en.wikipedia.org/wiki/Fiat%E2%80%93Shamir_heuristic
+#[cfg_attr(docsrs, doc(cfg(feature = "digest")))]
+pub trait PrehashSignature {
+    /// Preferred `Digest` algorithm to use when computing this signature type.
+    type Digest: digest::Digest;
+}