diff options
Diffstat (limited to 'vendor/signature/src/hazmat.rs')
-rw-r--r-- | vendor/signature/src/hazmat.rs | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/vendor/signature/src/hazmat.rs b/vendor/signature/src/hazmat.rs new file mode 100644 index 000000000..8119225c6 --- /dev/null +++ b/vendor/signature/src/hazmat.rs @@ -0,0 +1,75 @@ +//! 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. +//! +//! Using them incorrectly can introduce security vulnerabilities. Please +//! carefully read the documentation before attempting to use them. +//! +//! To use them, enable the `hazmat-preview` crate feature. Note that this +//! feature is semi-unstable and not subject to regular 1.x SemVer guarantees. +//! However, any breaking changes will be accompanied with a minor version bump. + +use crate::{Error, Signature}; + +#[cfg(feature = "rand-preview")] +use crate::rand_core::{CryptoRng, RngCore}; + +/// Sign the provided message prehash, returning a digital signature. +pub trait PrehashSigner<S: Signature> { + /// 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. + /// + /// 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. + fn sign_prehash(&self, prehash: &[u8]) -> Result<S, Error>; +} + +/// Sign the provided message prehash using the provided external randomness source, returning a digital signature. +#[cfg(feature = "rand-preview")] +#[cfg_attr(docsrs, doc(cfg(feature = "rand-preview")))] +pub trait RandomizedPrehashSigner<S: Signature> { + /// 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. + /// + /// 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. + fn sign_prehash_with_rng( + &self, + rng: impl CryptoRng + RngCore, + prehash: &[u8], + ) -> Result<S, Error>; +} + +/// Verify the provided message prehash using `Self` (e.g. a public key) +pub trait PrehashVerifier<S: Signature> { + /// Use `Self` to verify that the provided signature for a given message + /// `prehash` is authentic. + /// + /// The `prehash` parameter should be the output of a secure cryptographic + /// hash function. + /// + /// Returns `Error` if it is inauthentic or some other error occurred, or + /// otherwise returns `Ok(())`. + /// + /// # ⚠️ Security Warning + /// + /// 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. + fn verify_prehash(&self, prehash: &[u8], signature: &S) -> Result<(), Error>; +} |