signature/
hazmat.rs

Help
1//! Hazardous Materials: low-level APIs which can be insecure if misused.
2//!
3//! The traits in this module are not generally recommended, and should only be
4//! used in special cases where they are specifically needed.
5//!
6//! Using them incorrectly can introduce security vulnerabilities. Please
7//! carefully read the documentation before attempting to use them.
8
9use crate::Error;
10
11#[cfg(feature = "rand_core")]
12use crate::rand_core::CryptoRngCore;
13
14/// Sign the provided message prehash, returning a digital signature.
15pub trait PrehashSigner<S> {
16    /// Attempt to sign the given message digest, returning a digital signature
17    /// on success, or an error if something went wrong.
18    ///
19    /// The `prehash` parameter should be the output of a secure cryptographic
20    /// hash function.
21    ///
22    /// This API takes a `prehash` byte slice as there can potentially be many
23    /// compatible lengths for the message digest for a given concrete signature
24    /// algorithm.
25    ///
26    /// Allowed lengths are algorithm-dependent and up to a particular
27    /// implementation to decide.
28    fn sign_prehash(&self, prehash: &[u8]) -> Result<S, Error>;
29}
30
31/// Sign the provided message prehash using the provided external randomness source, returning a digital signature.
32#[cfg(feature = "rand_core")]
33pub trait RandomizedPrehashSigner<S> {
34    /// Attempt to sign the given message digest, returning a digital signature
35    /// on success, or an error if something went wrong.
36    ///
37    /// The `prehash` parameter should be the output of a secure cryptographic
38    /// hash function.
39    ///
40    /// This API takes a `prehash` byte slice as there can potentially be many
41    /// compatible lengths for the message digest for a given concrete signature
42    /// algorithm.
43    ///
44    /// Allowed lengths are algorithm-dependent and up to a particular
45    /// implementation to decide.
46    fn sign_prehash_with_rng(
47        &self,
48        rng: &mut impl CryptoRngCore,
49        prehash: &[u8],
50    ) -> Result<S, Error>;
51}
52
53/// Verify the provided message prehash using `Self` (e.g. a public key)
54pub trait PrehashVerifier<S> {
55    /// Use `Self` to verify that the provided signature for a given message
56    /// `prehash` is authentic.
57    ///
58    /// The `prehash` parameter should be the output of a secure cryptographic
59    /// hash function.
60    ///
61    /// Returns `Error` if it is inauthentic or some other error occurred, or
62    /// otherwise returns `Ok(())`.
63    ///
64    /// # ⚠️ Security Warning
65    ///
66    /// If `prehash` is something other than the output of a cryptographically
67    /// secure hash function, an attacker can potentially forge signatures by
68    /// solving a system of linear equations.
69    fn verify_prehash(&self, prehash: &[u8], signature: &S) -> Result<(), Error>;
70}
signature/hazmat.rs

signature/
hazmat.rs
