diff --git a/signature/Cargo.toml b/signature/Cargo.toml index d1951bf88..21a28883d 100644 --- a/signature/Cargo.toml +++ b/signature/Cargo.toml @@ -20,5 +20,8 @@ rand_core = { version = "0.10", optional = true, default-features = false } alloc = [] rand_core = ["dep:rand_core"] +[lints] +workspace = true + [package.metadata.docs.rs] all-features = true diff --git a/signature/src/error.rs b/signature/src/error.rs index 8a831dea6..846456575 100644 --- a/signature/src/error.rs +++ b/signature/src/error.rs @@ -30,6 +30,7 @@ pub struct Error { impl Error { /// Create a new error with no associated source + #[must_use] pub fn new() -> Self { Self::default() } @@ -90,6 +91,7 @@ impl core::error::Error for Error { None } #[cfg(feature = "alloc")] + #[allow(trivial_casts)] { self.source .as_ref() diff --git a/signature/src/hazmat.rs b/signature/src/hazmat.rs index 075fc489e..eeb84ed83 100644 --- a/signature/src/hazmat.rs +++ b/signature/src/hazmat.rs @@ -1,10 +1,14 @@ //! Hazardous Materials: low-level APIs which can be insecure if misused. //! -//! The traits in this module are not generally recommended, and should only be -//! used in special cases where they are specifically needed. +//! The traits in this module are not generally recommended, and should only be used in special +//! cases where they are specifically needed. //! -//! Using them incorrectly can introduce security vulnerabilities. Please -//! carefully read the documentation before attempting to use them. +//!
+//! Security Warning +//! +//! Using these traits incorrectly can introduce security vulnerabilities. Please carefully read the +//! documentation before attempting to use them. +//!
use crate::Error; @@ -13,36 +17,38 @@ use crate::rand_core::TryCryptoRng; /// Sign the provided message prehash, returning a digital signature. pub trait PrehashSigner { - /// Attempt to sign the given message digest, returning a digital signature - /// on success, or an error if something went wrong. + /// Attempt to sign the given message digest, returning a digital signature on success, or an + /// error if something went wrong. + /// + /// The `prehash` parameter should be the output of a secure cryptographic hash function. /// - /// The `prehash` parameter should be the output of a secure cryptographic - /// hash function. + /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths + /// for the message digest for a given concrete signature algorithm. /// - /// This API takes a `prehash` byte slice as there can potentially be many - /// compatible lengths for the message digest for a given concrete signature - /// algorithm. + /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide. /// - /// Allowed lengths are algorithm-dependent and up to a particular - /// implementation to decide. + /// # Errors + /// Returns [`Error`] in the event `prehash` is an invalid length. fn sign_prehash(&self, prehash: &[u8]) -> Result; } -/// Sign the provided message prehash using the provided external randomness source, returning a digital signature. +/// Sign the provided message prehash using the provided external randomness source, returning a +/// digital signature. #[cfg(feature = "rand_core")] pub trait RandomizedPrehashSigner { - /// Attempt to sign the given message digest, returning a digital signature - /// on success, or an error if something went wrong. + /// Attempt to sign the given message digest, returning a digital signature on success, or an + /// error if something went wrong. /// - /// The `prehash` parameter should be the output of a secure cryptographic - /// hash function. + /// The `prehash` parameter should be the output of a secure cryptographic hash function. /// - /// This API takes a `prehash` byte slice as there can potentially be many - /// compatible lengths for the message digest for a given concrete signature - /// algorithm. + /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths + /// for the message digest for a given concrete signature algorithm. /// - /// Allowed lengths are algorithm-dependent and up to a particular - /// implementation to decide. + /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide. + /// + /// # Errors + /// Returns [`Error`] in the event `prehash` is an invalid length, or if an internal error + /// in the provided `rng` occurs. fn sign_prehash_with_rng( &self, rng: &mut R, @@ -52,57 +58,54 @@ pub trait RandomizedPrehashSigner { /// Verify the provided message prehash using `Self` (e.g. a public key) pub trait PrehashVerifier { - /// Use `Self` to verify that the provided signature for a given message - /// `prehash` is authentic. + /// Use `Self` to verify that the provided signature for a given message `prehash` is authentic. + /// + /// The `prehash` parameter MUST be the output of a secure cryptographic hash function. /// - /// The `prehash` parameter should be the output of a secure cryptographic - /// hash function. + ///
+ /// Security Warning /// - /// Returns `Error` if it is inauthentic or some other error occurred, or - /// otherwise returns `Ok(())`. + /// If `prehash` is something other than the output of a cryptographically secure hash function, + /// an attacker can potentially forge signatures by e.g. solving a system of linear equations. + ///
/// - /// # ⚠️ Security Warning + /// Returns `Ok(())` if the signature verified successfully. /// - /// If `prehash` is something other than the output of a cryptographically - /// secure hash function, an attacker can potentially forge signatures by - /// solving a system of linear equations. + /// # Errors + /// Returns [`Error`] in the event the signature fails to verify or if `prehash` is an invalid + /// length. fn verify_prehash(&self, prehash: &[u8], signature: &S) -> Result<(), Error>; } /// Asynchronously sign the provided message prehash, returning a digital signature. #[allow(async_fn_in_trait)] pub trait AsyncPrehashSigner { - /// Attempt to sign the given message digest, returning a digital signature - /// on success, or an error if something went wrong. + /// Attempt to sign the given message digest, returning a digital signature on success, or an + /// error if something went wrong. /// - /// The `prehash` parameter should be the output of a secure cryptographic - /// hash function. + /// The `prehash` parameter should be the output of a secure cryptographic hash function. /// - /// This API takes a `prehash` byte slice as there can potentially be many - /// compatible lengths for the message digest for a given concrete signature - /// algorithm. + /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths + /// for the message digest for a given concrete signature algorithm. /// - /// Allowed lengths are algorithm-dependent and up to a particular - /// implementation to decide. + /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide. async fn sign_prehash_async(&self, prehash: &[u8]) -> Result; } -/// Asynchronously sign the provided message prehash using the provided external randomness source, returning a digital signature. +/// Asynchronously sign the provided message prehash using the provided external randomness source, +/// returning a digital signature. #[cfg(feature = "rand_core")] #[allow(async_fn_in_trait)] pub trait AsyncRandomizedPrehashSigner { - /// Attempt to sign the given message digest, returning a digital signature - /// on success, or an error if something went wrong. + /// Attempt to sign the given message digest, returning a digital signature on success, or an + /// error if something went wrong. /// - /// The `prehash` parameter should be the output of a secure cryptographic - /// hash function. + /// The `prehash` parameter should be the output of a secure cryptographic hash function. /// - /// This API takes a `prehash` byte slice as there can potentially be many - /// compatible lengths for the message digest for a given concrete signature - /// algorithm. + /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths + /// for the message digest for a given concrete signature algorithm. /// - /// Allowed lengths are algorithm-dependent and up to a particular - /// implementation to decide. + /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide. async fn sign_prehash_with_rng_async( &self, rng: &mut R, diff --git a/signature/src/lib.rs b/signature/src/lib.rs index e0a7b3453..dbd2d49ac 100644 --- a/signature/src/lib.rs +++ b/signature/src/lib.rs @@ -7,15 +7,6 @@ )] #![forbid(unsafe_code)] #![allow(async_fn_in_trait)] -#![warn( - clippy::mod_module_files, - clippy::unwrap_used, - missing_docs, - rust_2018_idioms, - unused_lifetimes, - missing_debug_implementations, - unused_qualifications -)] //! # Design //! diff --git a/signature/src/signer.rs b/signature/src/signer.rs index c75a90066..1057b6b07 100644 --- a/signature/src/signer.rs +++ b/signature/src/signer.rs @@ -1,4 +1,4 @@ -//! Traits for generating digital signatures +//! Traits for generating digital signatures. use crate::error::Error; @@ -8,50 +8,59 @@ use crate::digest::Update; #[cfg(feature = "rand_core")] use crate::rand_core::{CryptoRng, TryCryptoRng}; -/// Sign the provided message bytestring using `Self` (e.g. a cryptographic key -/// or connection to an HSM), returning a digital signature. +/// Sign the provided message bytestring using `Self` (e.g. a cryptographic key or connection to an +/// HSM), returning a digital signature. pub trait Signer { - /// Sign the given message and return a digital signature + /// Sign the given message and return a digital signature. fn sign(&self, msg: &[u8]) -> S { self.try_sign(msg).expect("signature operation failed") } - /// Attempt to sign the given message, returning a digital signature on - /// success, or an error if something went wrong. + /// Attempt to sign the given message, returning a digital signature on success, or an error if + /// something went wrong. + /// + /// The main intended use case for signing errors is when communicating with external signers, + /// e.g. cloud KMS, HSMs, or other hardware tokens. /// - /// The main intended use case for signing errors is when communicating - /// with external signers, e.g. cloud KMS, HSMs, or other hardware tokens. + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error). fn try_sign(&self, msg: &[u8]) -> Result; } /// Equivalent of [`Signer`] but the message is provided in non-contiguous byte slices. pub trait MultipartSigner { - /// Equivalent of [`Signer::sign()`] but the message - /// is provided in non-contiguous byte slices. + /// Equivalent of [`Signer::sign()`] but the message is provided in non-contiguous byte slices. fn multipart_sign(&self, msg: &[&[u8]]) -> S { self.try_multipart_sign(msg) .expect("signature operation failed") } - /// Equivalent of [`Signer::try_sign()`] but the - /// message is provided in non-contiguous byte slices. + /// Equivalent of [`Signer::try_sign()`] but the message is provided in non-contiguous byte + /// slices. + /// + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error). fn try_multipart_sign(&self, msg: &[&[u8]]) -> Result; } -/// Sign the provided message bytestring using `&mut Self` (e.g. an evolving -/// cryptographic key such as a stateful hash-based signature), returning a -/// digital signature. +/// Sign the provided message bytestring using `&mut Self` (e.g. an evolving cryptographic key such +/// as a stateful hash-based signature), returning a digital signature. pub trait SignerMut { /// Sign the given message, update the state, and return a digital signature. + /// + /// # Panics + /// In the event of a signing error. fn sign(&mut self, msg: &[u8]) -> S { self.try_sign(msg).expect("signature operation failed") } - /// Attempt to sign the given message, updating the state, and returning a - /// digital signature on success, or an error if something went wrong. + /// Attempt to sign the given message, updating the state, and returning a digital signature on + /// success, or an error if something went wrong. /// - /// Signing can fail, e.g., if the number of time periods allowed by the - /// current key is exceeded. + /// # Errors + /// Signing can fail, e.g. if the number of time periods allowed by the current key is exceeded. fn try_sign(&mut self, msg: &[u8]) -> Result; } @@ -59,30 +68,28 @@ pub trait SignerMut { /// /// ## Notes /// -/// This trait is primarily intended for signature algorithms based on the -/// [Fiat-Shamir heuristic], a method for converting an interactive -/// challenge/response-based proof-of-knowledge protocol into an offline -/// digital signature through the use of a random oracle, i.e. a digest -/// function. +/// This trait is primarily intended for signature algorithms based on the [Fiat-Shamir heuristic], +/// a method for converting an interactive challenge/response-based proof-of-knowledge protocol into +/// an offline digital signature through the use of a random oracle, i.e. a digest function. /// -/// The security of such protocols critically rests upon the inability of -/// an attacker to solve for the output of the random oracle, as generally -/// otherwise such signature algorithms are a system of linear equations and -/// therefore doing so would allow the attacker to trivially forge signatures. +/// The security of such protocols critically rests upon the inability of an attacker to solve for +/// the output of the random oracle, as generally otherwise such signature algorithms are a system +/// of linear equations and therefore doing so would allow the attacker to trivially forge +/// signatures. /// -/// To prevent misuse which would potentially allow this to be possible, this -/// API accepts a `Digest` instance, rather than a raw digest value. +/// To prevent misuse which would potentially allow this to be possible, this API accepts a `Digest` +/// instance, rather than a raw digest value. /// /// [Fiat-Shamir heuristic]: https://en.wikipedia.org/wiki/Fiat%E2%80%93Shamir_heuristic #[cfg(feature = "digest")] pub trait DigestSigner { - /// Sign a message by updating the received `Digest` with it, - /// returning a signature. + /// Sign a message by updating the received `Digest` with it, returning a signature. /// - /// The given function can be invoked multiple times. It is expected that - /// in each invocation the `Digest` is updated with the entire equal message. + /// The given function can be invoked multiple times. It is expected that in each invocation the + /// `Digest` is updated with the entire equal message. /// - /// Panics in the event of a signing error. + /// # Panics + /// In the event of a signing error. fn sign_digest(&self, f: F) -> S { self.try_sign_digest(|digest| { f(digest); @@ -91,11 +98,15 @@ pub trait DigestSigner { .expect("signature operation failed") } - /// Attempt to sign a message by updating the received `Digest` with it, - /// returning a digital signature on success, or an error if something went wrong. + /// Attempt to sign a message by updating the received `Digest` with it, returning a digital + /// signature on success, or an error if something went wrong. /// - /// The given function can be invoked multiple times. It is expected that - /// in each invocation the `Digest` is updated with the entire equal message. + /// The given function can be invoked multiple times. It is expected that in each invocation the + /// `Digest` is updated with the entire equal message. + /// + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error). fn try_sign_digest Result<(), Error>>(&self, f: F) -> Result; } @@ -108,11 +119,15 @@ pub trait RandomizedSigner { .expect("signature operation failed") } - /// Attempt to sign the given message, returning a digital signature on - /// success, or an error if something went wrong. + /// Attempt to sign the given message, returning a digital signature on success, or an error if + /// something went wrong. + /// + /// The main intended use case for signing errors is when communicating with external signers, + /// e.g. cloud KMS, HSMs, or other hardware tokens. /// - /// The main intended use case for signing errors is when communicating - /// with external signers, e.g. cloud KMS, HSMs, or other hardware tokens. + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error), or if the provided `rng` experiences an internal failure. fn try_sign_with_rng( &self, rng: &mut R, @@ -123,15 +138,19 @@ pub trait RandomizedSigner { /// Equivalent of [`RandomizedSigner`] but the message is provided in non-contiguous byte slices. #[cfg(feature = "rand_core")] pub trait RandomizedMultipartSigner { - /// Equivalent of [`RandomizedSigner::sign_with_rng()`] but - /// the message is provided in non-contiguous byte slices. + /// Equivalent of [`RandomizedSigner::sign_with_rng()`] but the message is provided in + /// non-contiguous byte slices. fn multipart_sign_with_rng(&self, rng: &mut R, msg: &[&[u8]]) -> S { self.try_multipart_sign_with_rng(rng, msg) .expect("signature operation failed") } - /// Equivalent of [`RandomizedSigner::try_sign_with_rng()`] but - /// the message is provided in non-contiguous byte slices. + /// Equivalent of [`RandomizedSigner::try_sign_with_rng()`] but the message is provided in + /// non-contiguous byte slices. + /// + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error), or if the provided `rng` experiences an internal failure. fn try_multipart_sign_with_rng( &self, rng: &mut R, @@ -139,17 +158,17 @@ pub trait RandomizedMultipartSigner { ) -> Result; } -/// Combination of [`DigestSigner`] and [`RandomizedSigner`] with support for -/// computing a signature over a digest which requires entropy from an RNG. +/// Combination of [`DigestSigner`] and [`RandomizedSigner`] with support for computing a signature +/// over a digest which requires entropy from an RNG. #[cfg(all(feature = "digest", feature = "rand_core"))] pub trait RandomizedDigestSigner { - /// Sign a message by updating the received `Digest` with it, - /// returning a signature. + /// Sign a message by updating the received `Digest` with it, returning a signature. /// - /// The given function can be invoked multiple times. It is expected that - /// in each invocation the `Digest` is updated with the entire equal message. + /// The given function can be invoked multiple times. It is expected that in each invocation the + /// `Digest` is updated with the entire equal message. /// - /// Panics in the event of a signing error. + /// # Panics + /// In the event of a signing error. fn sign_digest_with_rng(&self, rng: &mut R, f: F) -> S { self.try_sign_digest_with_rng(rng, |digest| { f(digest); @@ -158,11 +177,15 @@ pub trait RandomizedDigestSigner { .expect("signature operation failed") } - /// Attempt to sign a message by updating the received `Digest` with it, - /// returning a digital signature on success, or an error if something went wrong. + /// Attempt to sign a message by updating the received `Digest` with it, returning a digital + /// signature on success, or an error if something went wrong. + /// + /// The given function can be invoked multiple times. It is expected that in each invocation the + /// `Digest` is updated with the entire equal message. /// - /// The given function can be invoked multiple times. It is expected that - /// in each invocation the `Digest` is updated with the entire equal message. + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error), or if the provided `rng` experiences an internal failure. fn try_sign_digest_with_rng Result<(), Error>>( &self, rng: &mut R, @@ -170,22 +193,26 @@ pub trait RandomizedDigestSigner { ) -> Result; } -/// Sign the provided message bytestring using `&mut Self` (e.g. an evolving -/// cryptographic key such as a stateful hash-based signature), and a per-signature -/// randomizer, returning a digital signature. +/// Sign the provided message bytestring using `&mut Self` (e.g. an evolving cryptographic key such +/// as a stateful hash-based signature), and a per-signature randomizer, returning a digital +/// signature. #[cfg(feature = "rand_core")] pub trait RandomizedSignerMut { /// Sign the given message, update the state, and return a digital signature. + /// + /// # Panics + /// In the event of a signing error. fn sign_with_rng(&mut self, rng: &mut R, msg: &[u8]) -> S { self.try_sign_with_rng(rng, msg) .expect("signature operation failed") } - /// Attempt to sign the given message, updating the state, and returning a - /// digital signature on success, or an error if something went wrong. + /// Attempt to sign the given message, updating the state, and returning a digital signature on + /// success, or an error if something went wrong. /// - /// Signing can fail, e.g., if the number of time periods allowed by the - /// current key is exceeded. + /// # Errors + /// Signing can fail, e.g. if the number of time periods allowed by the current key is exceeded, + /// or if the provided `rng` experiences an internal failure. fn try_sign_with_rng( &mut self, rng: &mut R, @@ -196,15 +223,22 @@ pub trait RandomizedSignerMut { /// Equivalent of [`RandomizedSignerMut`] but the message is provided in non-contiguous byte slices. #[cfg(feature = "rand_core")] pub trait RandomizedMultipartSignerMut { - /// Equivalent of [`RandomizedSignerMut::sign_with_rng()`] but - /// the message is provided in non-contiguous byte slices. + /// Equivalent of [`RandomizedSignerMut::sign_with_rng()`] but the message is provided in + /// non-contiguous byte slices. + /// + /// # Panics + /// In the event of a signing error. fn multipart_sign_with_rng(&mut self, rng: &mut R, msg: &[&[u8]]) -> S { self.try_multipart_sign_with_rng(rng, msg) .expect("signature operation failed") } - /// Equivalent of [`RandomizedSignerMut::try_sign_with_rng()`] - /// but the message is provided in non-contiguous byte slices. + /// Equivalent of [`RandomizedSignerMut::try_sign_with_rng()`] but the message is provided in + /// non-contiguous byte slices. + /// + /// # Errors + /// Signing can fail, e.g. if the number of time periods allowed by the current key is exceeded, + /// or if the provided `rng` experiences an internal failure. fn try_multipart_sign_with_rng( &mut self, rng: &mut R, @@ -224,16 +258,20 @@ impl> RandomizedSignerMut for T { } } -/// Asynchronously sign the provided message bytestring using `Self` -/// (e.g. client for a Cloud KMS or HSM), returning a digital signature. +/// Asynchronously sign the provided message bytestring using `Self` (e.g. client for a Cloud KMS or +/// HSM), returning a digital signature. /// /// This trait is an async equivalent of the [`Signer`] trait. pub trait AsyncSigner { - /// Attempt to sign the given message, returning a digital signature on - /// success, or an error if something went wrong. + /// Attempt to sign the given message, returning a digital signature on success, or an error if + /// something went wrong. + /// + /// The main intended use case for signing errors is when communicating with external signers, + /// e.g. cloud KMS, HSMs, or other hardware tokens. /// - /// The main intended use case for signing errors is when communicating - /// with external signers, e.g. cloud KMS, HSMs, or other hardware tokens. + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error). async fn sign_async(&self, msg: &[u8]) -> Result; } @@ -254,11 +292,15 @@ pub trait AsyncDigestSigner where D: Update, { - /// Attempt to sign a message by updating the received `Digest` with it, - /// returning a digital signature on success, or an error if something went wrong. + /// Attempt to sign a message by updating the received `Digest` with it, returning a digital + /// signature on success, or an error if something went wrong. /// - /// The given function can be invoked multiple times. It is expected that - /// in each invocation the `Digest` is updated with the entire equal message. + /// The given function can be invoked multiple times. It is expected that in each invocation the + /// `Digest` is updated with the entire equal message. + /// + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error). async fn sign_digest_async Result<(), Error>>( &self, f: F, @@ -268,18 +310,25 @@ where /// Sign the given message using the provided external randomness source. #[cfg(feature = "rand_core")] pub trait AsyncRandomizedSigner { - /// Sign the given message and return a digital signature + /// Sign the given message and return a digital signature. + /// + /// # Panics + /// In the event of a signing error. async fn sign_with_rng_async(&self, rng: &mut R, msg: &[u8]) -> S { self.try_sign_with_rng_async(rng, msg) .await .expect("signature operation failed") } - /// Attempt to sign the given message, returning a digital signature on - /// success, or an error if something went wrong. + /// Attempt to sign the given message, returning a digital signature on success, or an error if + /// something went wrong. + /// + /// The main intended use case for signing errors is when communicating with external signers, + /// e.g. cloud KMS, HSMs, or other hardware tokens. /// - /// The main intended use case for signing errors is when communicating - /// with external signers, e.g. cloud KMS, HSMs, or other hardware tokens. + /// # Errors + /// Returns implementation-specific errors in the event signing failed (e.g. KMS or HSM + /// communication error), or if the provided `rng` experiences an internal failure. async fn try_sign_with_rng_async( &self, rng: &mut R, diff --git a/signature/src/verifier.rs b/signature/src/verifier.rs index 0d17163e3..edaf1f924 100644 --- a/signature/src/verifier.rs +++ b/signature/src/verifier.rs @@ -1,28 +1,33 @@ -//! Trait for verifying digital signatures +//! Trait for verifying digital signatures. use crate::error::Error; #[cfg(feature = "digest")] use crate::digest::Update; -/// Verify the provided message bytestring using `Self` (e.g. a public key) +/// Verify the provided message bytestring using `Self` (e.g. a public key). pub trait Verifier { - /// Use `Self` to verify that the provided signature for a given message - /// bytestring is authentic. + /// Use `Self` (e.g. a verifying key) to verify that the provided `signature` is authentic + /// for a given message bytestring. /// - /// Returns `Error` if it is inauthentic, or otherwise returns `()`. + /// Returns `Ok(())` if the `signature` is authentic for the given message. + /// + /// # Errors + /// Returns [`Error`] if the provided `signature` is inauthentic for the given message. fn verify(&self, msg: &[u8], signature: &S) -> Result<(), Error>; } /// Equivalent of [`Verifier`] but the message is provided in non-contiguous byte slices. pub trait MultipartVerifier { - /// Equivalent of [`Verifier::verify()`] but the - /// message is provided in non-contiguous byte slices. + /// Equivalent of [`Verifier::verify()`] but the message is provided in non-contiguous byte + /// slices. + /// + /// # Errors + /// Returns [`Error`] if the provided `signature` is inauthentic for the given message. fn multipart_verify(&self, msg: &[&[u8]], signature: &S) -> Result<(), Error>; } -/// Verify the provided signature for the given prehashed message `Digest` -/// is authentic. +/// Verify the provided signature for the given prehashed message `Digest` is authentic. /// /// ## Notes /// @@ -44,11 +49,13 @@ pub trait MultipartVerifier { /// [Fiat-Shamir heuristic]: https://en.wikipedia.org/wiki/Fiat%E2%80%93Shamir_heuristic #[cfg(feature = "digest")] pub trait DigestVerifier { - /// Verify the signature against the received `Digest` output, - /// by updating it with the message. + /// Verify the signature against the received `Digest` output, by updating it with the message. + /// + /// The given function can be invoked multiple times. It is expected that in each invocation the + /// `Digest` is updated with the entire equal message. /// - /// The given function can be invoked multiple times. It is expected that - /// in each invocation the `Digest` is updated with the entire equal message. + /// # Errors + /// Returns [`Error`] if the provided `signature` is inauthentic for the given message digest. fn verify_digest Result<(), Error>>( &self, f: F,