signature/
hazmat.rs

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 used in special
4//! cases where they are specifically needed.
5//!
6//! <div class = "warning">
7//! <b>Security Warning</b>
8//!
9//! Using these traits incorrectly can introduce security vulnerabilities. Please carefully read the
10//! documentation before attempting to use them.
11//! </div>
12
13use crate::Error;
14
15#[cfg(feature = "rand_core")]
16use crate::rand_core::TryCryptoRng;
17
18/// Sign the provided message prehash, returning a digital signature.
19pub trait PrehashSigner<S> {
20    /// Attempt to sign the given message digest, returning a digital signature on success, or an
21    /// error if something went wrong.
22    ///
23    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
24    ///
25    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
26    /// for the message digest for a given concrete signature algorithm.
27    ///
28    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
29    ///
30    /// # Errors
31    /// Returns [`Error`] in the event `prehash` is an invalid length.
32    fn sign_prehash(&self, prehash: &[u8]) -> Result<S, Error>;
33}
34
35/// Sign the provided message prehash using the provided external randomness source, returning a
36/// digital signature.
37#[cfg(feature = "rand_core")]
38pub trait RandomizedPrehashSigner<S> {
39    /// Attempt to sign the given message digest, returning a digital signature on success, or an
40    /// error if something went wrong.
41    ///
42    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
43    ///
44    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
45    /// for the message digest for a given concrete signature algorithm.
46    ///
47    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
48    ///
49    /// # Errors
50    /// Returns [`Error`] in the event `prehash` is an invalid length, or if an internal error
51    /// in the provided `rng` occurs.
52    fn sign_prehash_with_rng<R: TryCryptoRng + ?Sized>(
53        &self,
54        rng: &mut R,
55        prehash: &[u8],
56    ) -> Result<S, Error>;
57}
58
59/// Verify the provided message prehash using `Self` (e.g. a public key)
60pub trait PrehashVerifier<S> {
61    /// Use `Self` to verify that the provided signature for a given message `prehash` is authentic.
62    ///
63    /// The `prehash` parameter MUST be the output of a secure cryptographic hash function.
64    ///
65    /// <div class="warning">
66    /// <b>Security Warning</b>
67    ///
68    /// If `prehash` is something other than the output of a cryptographically secure hash function,
69    /// an attacker can potentially forge signatures by e.g. solving a system of linear equations.
70    /// </div>
71    ///
72    /// Returns `Ok(())` if the signature verified successfully.
73    ///
74    /// # Errors
75    /// Returns [`Error`] in the event the signature fails to verify or if `prehash` is an invalid
76    /// length.
77    fn verify_prehash(&self, prehash: &[u8], signature: &S) -> Result<(), Error>;
78}
79
80/// Asynchronously sign the provided message prehash, returning a digital signature.
81#[allow(async_fn_in_trait)]
82pub trait AsyncPrehashSigner<S> {
83    /// Attempt to sign the given message digest, returning a digital signature on success, or an
84    /// error if something went wrong.
85    ///
86    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
87    ///
88    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
89    /// for the message digest for a given concrete signature algorithm.
90    ///
91    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
92    async fn sign_prehash_async(&self, prehash: &[u8]) -> Result<S, Error>;
93}
94
95/// Asynchronously sign the provided message prehash using the provided external randomness source,
96/// returning a digital signature.
97#[cfg(feature = "rand_core")]
98#[allow(async_fn_in_trait)]
99pub trait AsyncRandomizedPrehashSigner<S> {
100    /// Attempt to sign the given message digest, returning a digital signature on success, or an
101    /// error if something went wrong.
102    ///
103    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
104    ///
105    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
106    /// for the message digest for a given concrete signature algorithm.
107    ///
108    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
109    async fn sign_prehash_with_rng_async<R: TryCryptoRng + ?Sized>(
110        &self,
111        rng: &mut R,
112        prehash: &[u8],
113    ) -> Result<S, Error>;
114}
signature/hazmat.rs

signature/
hazmat.rs
