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,