signature crate: 1.0 stabilization proposal

The motivation for 1.0 stabilization of the `signature` crate is the
upcoming 1.0 release of `ed25519-dalek`. In order to promote Ed25519
interoperability, it would be great if `ed25519-dalek` could use the
traits from this crate along with the `ed25519::Signature` type from the
`ed25519` crate.

To get there, I think we need to do a 1.0 release of this crate, as well
as the `ed25519` crate.

The main impediment towards doing so is the `digest` crate is presently
stuck at v0.8. It would be nice to be able to continue upgrading it,
especially to a 1.0 release, but that would otherwise be a semver
breaking change.

To allow agility around `digest`, and `signatory_derive` which depends
on it, this commit places access to both under the `digest-preview` and
`derive-preview` Cargo features respectively, and calls them out as
not covered under SemVer and subject to change, but breaking changes
will be done with a minor version bump.

Author: tarcieri

.travis.yml

@@ -7,6 +7,10 @@ rust:
   - beta
   - nightly
 
+env:
+  global:
+    - RUSTFLAGS="-D warnings"
+
 script:
   - cargo test --verbose --release
   - cargo test --verbose --all-features --release

ecdsa/Cargo.toml

@@ -10,4 +10,4 @@ categories = ["cryptography", "no-std"]
 keywords = ["crypto", "ecc", "ecdsa", "signature", "signing"]
 
 [dependencies]
-signature = { version = "0.3", path = "../signature-crate" }
+signature = { version = "1.0.0-pre", path = "../signature-crate" }

ed25519/Cargo.toml

@@ -12,7 +12,7 @@ categories    = ["cryptography", "no-std"]
 keywords      = ["crypto", "curve25519", "ecc", "signature", "signing"]
 
 [dependencies]
-signature = { version = "0.3", path = "../signature-crate", default-features = false }
+signature = { version = "1.0.0-pre", path = "../signature-crate", default-features = false }
 
 [features]
 default = ["alloc"]

ed25519/src/lib.rs

@@ -38,7 +38,7 @@ impl Signature {
 
     /// Return the inner byte array
     pub fn to_bytes(&self) -> [u8; SIGNATURE_LENGTH] {
-        self.0.clone()
+        self.0
     }
 }
 

signature-crate/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name          = "signature"
 description   = "Traits for cryptographic signature algorithms (e.g. ECDSA, Ed25519)"
-version       = "0.3.0" # Also update html_root_url in lib.rs when bumping this
+version       = "1.0.0-pre" # Also update html_root_url in lib.rs when bumping this
 authors       = ["RustCrypto Developers"]
 license       = "Apache-2.0 OR MIT"
 documentation = "https://docs.rs/signature"
@@ -20,6 +20,11 @@ hex-literal = "0.2"
 sha2 = { version = "0.8", default-features = false }
 
 [features]
-default = ["digest", "std"]
-alloc   = []
-std     = ["alloc"]
+default = ["std"]
+alloc = []
+derive-preview = ["digest-preview", "signature_derive"]
+digest-preview = ["digest"]
+std = ["alloc"]
+
+[package.metadata.docs.rs]
+all-features = true

signature-crate/README.md

@@ -14,9 +14,21 @@ Support is also planned for the [`ecdsa`][3] and [`rsa`][4] crates.
 
 [Documentation][docs-link]
 
-## Requirements
+## Minimum Supported Rust Version
 
-- Rust **1.36+**
+All crates in this repository support Rust **1.36** or higher.
+
+Minimum supported Rust version can be changed in the future, but it will be
+done with a minor version bump.
+
+## SemVer Policy
+
+- All on-by-default features of this library are covered by SemVer
+- MSRV is considered exempt from SemVer as noted above
+- The off-by-default features `derive-preview` and `digest-preview` are
+  unstable "preview" features which are also considered exempt from SemVer.
+  Breaking changes to these features will, like MSRV, be done with a minor
+  version bump.
 
 ## License
 

signature-crate/src/lib.rs

@@ -1,6 +1,22 @@
 //! Traits which provide generic, object-safe APIs for generating and verifying
 //! digital signatures, which provide message authentication using public-key
 //! cryptography.
+//!
+//! ## Minimum Supported Rust Version
+//!
+//! Rust **1.36** or higher.
+//!
+//! Minimum supported Rust version can be changed in the future, but it will be
+//! done with a minor version bump.
+//!
+//! ## SemVer Policy
+//!
+//! - All on-by-default features of this library are covered by SemVer
+//! - MSRV is considered exempt from SemVer as noted above
+//! - The off-by-default features `derive-preview` and `digest-preview` are
+//!   unstable "preview" features which are also considered exempt from SemVer.
+//!   Breaking changes to these features will, like MSRV, be done with a minor
+//!   version bump.
 
 #![no_std]
 #![forbid(unsafe_code)]
@@ -14,16 +30,16 @@ extern crate alloc;
 #[macro_use]
 extern crate std;
 
-#[cfg(feature = "signature_derive")]
+#[cfg(feature = "derive-preview")]
 #[allow(unused_imports)]
 #[macro_use]
 extern crate signature_derive;
 
-#[cfg(feature = "signature_derive")]
+#[cfg(feature = "derive-preview")]
 #[doc(hidden)]
 pub use signature_derive::{Signer, Verifier};
 
-#[cfg(feature = "digest")]
+#[cfg(feature = "digest-preview")]
 pub use digest;
 
 mod error;

signature-crate/src/signer.rs

@@ -1,6 +1,6 @@
 //! Traits for generating digital signatures
 
-#[cfg(feature = "digest")]
+#[cfg(feature = "digest-preview")]
 use crate::digest::Digest;
 use crate::{error::Error, Signature};
 
@@ -21,7 +21,10 @@ pub trait Signer<S: Signature> {
 }
 
 /// Sign the given prehashed message `Digest` using `Self`.
-#[cfg(feature = "digest")]
+///
+/// This trait is only available when the `digest-preview` cargo feature is
+/// enabled.
+#[cfg(feature = "digest-preview")]
 pub trait DigestSigner<D, S>
 where
     D: Digest,

signature-crate/src/verifier.rs

@@ -1,6 +1,6 @@
 //! Trait for verifying digital signatures
 
-#[cfg(feature = "digest")]
+#[cfg(feature = "digest-preview")]
 use crate::digest::Digest;
 use crate::{error::Error, Signature};
 
@@ -15,7 +15,13 @@ pub trait Verifier<S: Signature> {
 
 /// Verify the provided signature for the given prehashed message `Digest`
 /// is authentic.
-#[cfg(feature = "digest")]
+///
+/// This trait is only available when the `digest-preview` cargo feature is
+/// enabled.
+///
+/// It accepts a [`Digest`] instance, as opposed to a raw digest byte array,
+/// as the security of signature algorithms built on hash functions
+#[cfg(feature = "digest-preview")]
 pub trait DigestVerifier<D, S>
 where
     D: Digest,

signature-crate/tests/signature_derive.rs

@@ -1,5 +1,5 @@
 /// "Tests" for code generated by `signature_derive`
-#[cfg(all(test, feature = "signature_derive"))]
+#[cfg(all(test, feature = "derive-preview"))]
 mod tests {
     use digest::{generic_array::GenericArray, Digest};
     use hex_literal::hex;