signature crate: 1.0 stabilization proposal

.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/signature.rs

@@ -29,7 +29,7 @@ pub trait Signature: AsRef<[u8]> + Debug + Sized {
 /// - `H`: hash (a.k.a. digest) function
 /// - `m`: message
 ///
-/// For signature types that implement this trait, when the `signature_derive`
+/// 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`.

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,16 @@ 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 often
+/// depends critically on the input being a random oracle as opposed to a
+/// value an attacker can choose and solve for. This is enforced at the API
+/// level by taking a [`Digest`] instance in order to better resist misuse.
+#[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;