Add sha2 feature with oid subfeature enabled (#255)

We seem to be running into a lot of people who are having trouble with
PKCS#1 v1.5 signatures because the failure mode for the `oid` feature of
the `sha2` crate being disabled is fairly unscrutable.

See #234, #253, and the semi-related tracking issue for #238.

If `rsa` has a `sha2` feature, we can always ensure `oid` is enabled,
and this can be used in code examples. It also means users don't need
two crates to create/verify PKCS#1 v1.5 signatures.

RSA is used commonly enough with the SHA2 family that this integration
probably makes sense.

Cargo.toml

@@ -26,6 +26,12 @@ pkcs8 = { version = "0.9", default-features = false, features = ["alloc"] }
 signature = { version = "2", default-features = false , features = ["digest", "rand_core"] }
 zeroize = { version = "1", features = ["alloc"] }
 
+[dependencies.sha2]
+version = "0.10.6"
+optional = true
+default-features = false
+features = ["oid"]
+
 [dependencies.serde_crate]
 package = "serde"
 optional = true
@@ -59,7 +65,7 @@ pkcs5 = ["pkcs8/encryption"]
 getrandom = ["rand_core/getrandom"]
 
 [package.metadata.docs.rs]
-features = ["std", "pem", "serde", "expose-internals"]
+features = ["std", "pem", "serde", "expose-internals", "sha2"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [profile.dev]

src/lib.rs

@@ -54,11 +54,15 @@
 //! ```
 //!
 //! ## PKCS#1 v1.5 signatures
-//! ```
+//!
+//! Note: requires `sha2` feature of `rsa` crate is enabled.
+//!
+#![cfg_attr(feature = "sha2", doc = "```")]
+#![cfg_attr(not(feature = "sha2"), doc = "```ignore")]
 //! use rsa::RsaPrivateKey;
 //! use rsa::pkcs1v15::{SigningKey, VerifyingKey};
 //! use rsa::signature::{Keypair, RandomizedSigner, SignatureEncoding, Verifier};
-//! use sha2::{Digest, Sha256};
+//! use rsa::sha2::{Digest, Sha256};
 //!
 //! let mut rng = rand::thread_rng();
 //!
@@ -224,6 +228,8 @@ mod raw;
 
 pub use pkcs1;
 pub use pkcs8;
+#[cfg(feature = "sha2")]
+pub use sha2;
 
 pub use crate::{
     key::{PublicKey, PublicKeyParts, RsaPrivateKey, RsaPublicKey},

src/pkcs1v15.rs

@@ -412,7 +412,11 @@ impl<D> SigningKey<D>
 where
     D: Digest,
 {
-    /// Create a new signing key from the give RSA private key.
+    /// Create a new signing key from the give RSA private key with an empty prefix.
+    ///
+    /// ## Note: unprefixed signatures are uncommon
+    ///
+    /// In most cases you'll want to use [`SigningKey::new_with_prefix`].
     pub fn new(key: RsaPrivateKey) -> Self {
         Self {
             inner: key,
@@ -587,7 +591,11 @@ impl<D> VerifyingKey<D>
 where
     D: Digest,
 {
-    /// Create a new verifying key from an RSA public key.
+    /// Create a new verifying key from an RSA public key with an empty prefix.
+    ///
+    /// ## Note: unprefixed signatures are uncommon
+    ///
+    /// In most cases you'll want to use [`SigningKey::new_with_prefix`].
     pub fn new(key: RsaPublicKey) -> Self {
         Self {
             inner: key,