remove use of "hashes" from examples and doccomments

This is a little annoying; the library has a Message type for
ECDSA signing which is supposed to be a secure hash digest,
but we provide no methods for producing such a digest. So
our examples are necessarily a little wonky.

Before this commit we would use `bitcoin_hashes` to hash some
arbitrary data. This isn't really wise (signing unstructured
data or using hashes that aren't domain-separated) but it was
shaped similarly to proper usage.

Now we just hardcode the "output" of hash functions and convert
that. I added some comments to help.

Author: apoelstra

examples/sign_verify.rs

@@ -1,17 +1,29 @@
-extern crate hashes;
+//! Signing and Verification Example
+//!
+//! In this example we directly sign the "output of a hash function"
+//! as represented by a 32-byte array. In practice, when signing with
+//! the ECDSA API, you should not sign an arbitrary hash like this,
+//! whether it is typed as a `[u8; 32]` or a `sha2::Sha256` or whatever.
+//!
+//! Instead, you should have a dedicated signature hash type, which has
+//! constructors ensuring that it represents an (ideally) domain-separated
+//! hash of the data you intend to sign. This type should implement
+//! `Into<Message>` so it can be passed to `sign_ecdsa` as a message.
+//!
+//! An example of such a type is `bitcoin::LegacySighash` from rust-bitcoin.
+//!
+
 extern crate secp256k1;
 
-use hashes::{sha256, Hash};
 use secp256k1::{ecdsa, Error, Message, PublicKey, Secp256k1, SecretKey, Signing, Verification};
 
 fn verify<C: Verification>(
     secp: &Secp256k1<C>,
-    msg: &[u8],
+    msg_digest: [u8; 32],
     sig: [u8; 64],
     pubkey: [u8; 33],
 ) -> Result<bool, Error> {
-    let msg = sha256::Hash::hash(msg);
-    let msg = Message::from_digest(msg.to_byte_array());
+    let msg = Message::from_digest(msg_digest);
     let sig = ecdsa::Signature::from_compact(&sig)?;
     let pubkey = PublicKey::from_slice(&pubkey)?;
 
@@ -20,11 +32,10 @@ fn verify<C: Verification>(
 
 fn sign<C: Signing>(
     secp: &Secp256k1<C>,
-    msg: &[u8],
+    msg_digest: [u8; 32],
     seckey: [u8; 32],
 ) -> Result<ecdsa::Signature, Error> {
-    let msg = sha256::Hash::hash(msg);
-    let msg = Message::from_digest(msg.to_byte_array());
+    let msg = Message::from_digest(msg_digest);
     let seckey = SecretKey::from_byte_array(seckey)?;
     Ok(secp.sign_ecdsa(msg, &seckey))
 }
@@ -40,11 +51,11 @@ fn main() {
         2, 29, 21, 35, 7, 198, 183, 43, 14, 208, 65, 139, 14, 112, 205, 128, 231, 245, 41, 91, 141,
         134, 245, 114, 45, 63, 82, 19, 251, 210, 57, 79, 54,
     ];
-    let msg = b"This is some message";
+    let msg_digest = *b"this must be secure hash output.";
 
-    let signature = sign(&secp, msg, seckey).unwrap();
+    let signature = sign(&secp, msg_digest, seckey).unwrap();
 
     let serialize_sig = signature.serialize_compact();
 
-    assert!(verify(&secp, msg, serialize_sig, pubkey).unwrap());
+    assert!(verify(&secp, msg_digest, serialize_sig, pubkey).unwrap());
 }

examples/sign_verify_recovery.rs

@@ -1,17 +1,14 @@
-extern crate hashes;
 extern crate secp256k1;
 
-use hashes::{sha256, Hash};
 use secp256k1::{ecdsa, Error, Message, PublicKey, Secp256k1, SecretKey, Signing, Verification};
 
 fn recover<C: Verification>(
     secp: &Secp256k1<C>,
-    msg: &[u8],
+    msg_digest: [u8; 32],
     sig: [u8; 64],
     recovery_id: u8,
 ) -> Result<PublicKey, Error> {
-    let msg = sha256::Hash::hash(msg);
-    let msg = Message::from_digest(msg.to_byte_array());
+    let msg = Message::from_digest(msg_digest);
     let id = ecdsa::RecoveryId::try_from(i32::from(recovery_id))?;
     let sig = ecdsa::RecoverableSignature::from_compact(&sig, id)?;
 
@@ -20,11 +17,10 @@ fn recover<C: Verification>(
 
 fn sign_recovery<C: Signing>(
     secp: &Secp256k1<C>,
-    msg: &[u8],
+    msg_digest: [u8; 32],
     seckey: [u8; 32],
 ) -> Result<ecdsa::RecoverableSignature, Error> {
-    let msg = sha256::Hash::hash(msg);
-    let msg = Message::from_digest(msg.to_byte_array());
+    let msg = Message::from_digest(msg_digest);
     let seckey = SecretKey::from_byte_array(seckey)?;
     Ok(secp.sign_ecdsa_recoverable(msg, &seckey))
 }
@@ -41,11 +37,11 @@ fn main() {
         134, 245, 114, 45, 63, 82, 19, 251, 210, 57, 79, 54,
     ])
     .unwrap();
-    let msg = b"This is some message";
+    let msg_digest = *b"this must be secure hash output.";
 
-    let signature = sign_recovery(&secp, msg, seckey).unwrap();
+    let signature = sign_recovery(&secp, msg_digest, seckey).unwrap();
 
     let (recovery_id, serialize_sig) = signature.serialize_compact();
 
-    assert_eq!(recover(&secp, msg, serialize_sig, recovery_id.to_u8()), Ok(pubkey));
+    assert_eq!(recover(&secp, msg_digest, serialize_sig, recovery_id.to_u8()), Ok(pubkey));
 }

src/lib.rs

@@ -28,15 +28,23 @@
 //! trigger any assertion failures in the upstream library.
 //!
 //! ```rust
-//! # #[cfg(all(feature = "rand", feature = "hashes", feature = "std"))] {
+//! # #[cfg(all(feature = "rand", feature = "std"))] {
 //! use secp256k1::rand;
 //! use secp256k1::{Secp256k1, Message};
 //! use secp256k1::hashes::{sha256, Hash};
 //!
+//! // Our message to sign. We explicitly obtain a hash and convert it to a
+//! // `Message`. In a real application, we would produce a signature hash
+//! // type, e.g. `bitcoin::LegacySigHash`, which is convertible to `Message`
+//! // and can be passed directly to `sign_ecdsa`.
+//! const HELLO_WORLD_SHA2: [u8; 32] = [
+//!     0x31, 0x5f, 0x5b, 0xdb, 0x76, 0xd0, 0x78, 0xc4, 0x3b, 0x8a, 0xc0, 0x06, 0x4e, 0x4a, 0x01, 0x64,
+//!     0x61, 0x2b, 0x1f, 0xce, 0x77, 0xc8, 0x69, 0x34, 0x5b, 0xfc, 0x94, 0xc7, 0x58, 0x94, 0xed, 0xd3,
+//! ];
+//!
 //! let secp = Secp256k1::new();
 //! let (secret_key, public_key) = secp.generate_keypair(&mut rand::rng());
-//! let digest = sha256::Hash::hash("Hello World!".as_bytes());
-//! let message = Message::from_digest(digest.to_byte_array());
+//! let message = Message::from_digest(HELLO_WORLD_SHA2);
 //!
 //! let sig = secp.sign_ecdsa(message, &secret_key);
 //! assert!(secp.verify_ecdsa(&sig, message, &public_key).is_ok());
@@ -46,13 +54,19 @@
 //! If the "global-context" feature is enabled you have access to an alternate API.
 //!
 //! ```rust
-//! # #[cfg(all(feature = "global-context", feature = "hashes", feature = "rand", feature = "std"))] {
+//! # #[cfg(all(feature = "global-context", feature = "rand", feature = "std"))] {
 //! use secp256k1::{rand, generate_keypair, Message};
 //! use secp256k1::hashes::{sha256, Hash};
 //!
+//! // See previous example regarding this constant.
+//! const HELLO_WORLD_SHA2: [u8; 32] = [
+//!     0x31, 0x5f, 0x5b, 0xdb, 0x76, 0xd0, 0x78, 0xc4, 0x3b, 0x8a, 0xc0, 0x06, 0x4e, 0x4a, 0x01, 0x64,
+//!     0x61, 0x2b, 0x1f, 0xce, 0x77, 0xc8, 0x69, 0x34, 0x5b, 0xfc, 0x94, 0xc7, 0x58, 0x94, 0xed, 0xd3,
+//! ];
+//!
 //! let (secret_key, public_key) = generate_keypair(&mut rand::rng());
 //! let digest = sha256::Hash::hash("Hello World!".as_bytes());
-//! let message = Message::from_digest(digest.to_byte_array());
+//! let message = Message::from_digest(HELLO_WORLD_SHA2);
 //!
 //! let sig = secret_key.sign_ecdsa(message);
 //! assert!(sig.verify(message, &public_key).is_ok());