/rust/registry/src/index.crates.io-1949cf8c6b5b557f/signature-2.2.0/src/signer.rs
Line | Count | Source |
1 | | //! Traits for generating digital signatures |
2 | | |
3 | | use crate::error::Error; |
4 | | |
5 | | #[cfg(feature = "digest")] |
6 | | use crate::digest::Digest; |
7 | | |
8 | | #[cfg(feature = "rand_core")] |
9 | | use crate::rand_core::CryptoRngCore; |
10 | | |
11 | | /// Sign the provided message bytestring using `Self` (e.g. a cryptographic key |
12 | | /// or connection to an HSM), returning a digital signature. |
13 | | pub trait Signer<S> { |
14 | | /// Sign the given message and return a digital signature |
15 | 3.26k | fn sign(&self, msg: &[u8]) -> S { |
16 | 3.26k | self.try_sign(msg).expect("signature operation failed") |
17 | 3.26k | } <ecdsa::signing::SigningKey<p256::NistP256> as signature::signer::Signer<ecdsa::Signature<p256::NistP256>>>::sign Line | Count | Source | 15 | 3.26k | fn sign(&self, msg: &[u8]) -> S { | 16 | 3.26k | self.try_sign(msg).expect("signature operation failed") | 17 | 3.26k | } |
Unexecuted instantiation: <_ as signature::signer::Signer<_>>::sign |
18 | | |
19 | | /// Attempt to sign the given message, returning a digital signature on |
20 | | /// success, or an error if something went wrong. |
21 | | /// |
22 | | /// The main intended use case for signing errors is when communicating |
23 | | /// with external signers, e.g. cloud KMS, HSMs, or other hardware tokens. |
24 | | fn try_sign(&self, msg: &[u8]) -> Result<S, Error>; |
25 | | } |
26 | | |
27 | | /// Sign the provided message bytestring using `&mut Self` (e.g. an evolving |
28 | | /// cryptographic key such as a stateful hash-based signature), returning a |
29 | | /// digital signature. |
30 | | pub trait SignerMut<S> { |
31 | | /// Sign the given message, update the state, and return a digital signature. |
32 | 0 | fn sign(&mut self, msg: &[u8]) -> S { |
33 | 0 | self.try_sign(msg).expect("signature operation failed") |
34 | 0 | } |
35 | | |
36 | | /// Attempt to sign the given message, updating the state, and returning a |
37 | | /// digital signature on success, or an error if something went wrong. |
38 | | /// |
39 | | /// Signing can fail, e.g., if the number of time periods allowed by the |
40 | | /// current key is exceeded. |
41 | | fn try_sign(&mut self, msg: &[u8]) -> Result<S, Error>; |
42 | | } |
43 | | |
44 | | /// Blanket impl of [`SignerMut`] for all [`Signer`] types. |
45 | | impl<S, T: Signer<S>> SignerMut<S> for T { |
46 | 0 | fn try_sign(&mut self, msg: &[u8]) -> Result<S, Error> { |
47 | 0 | T::try_sign(self, msg) |
48 | 0 | } |
49 | | } |
50 | | |
51 | | /// Sign the given prehashed message [`Digest`] using `Self`. |
52 | | /// |
53 | | /// ## Notes |
54 | | /// |
55 | | /// This trait is primarily intended for signature algorithms based on the |
56 | | /// [Fiat-Shamir heuristic], a method for converting an interactive |
57 | | /// challenge/response-based proof-of-knowledge protocol into an offline |
58 | | /// digital signature through the use of a random oracle, i.e. a digest |
59 | | /// function. |
60 | | /// |
61 | | /// The security of such protocols critically rests upon the inability of |
62 | | /// an attacker to solve for the output of the random oracle, as generally |
63 | | /// otherwise such signature algorithms are a system of linear equations and |
64 | | /// therefore doing so would allow the attacker to trivially forge signatures. |
65 | | /// |
66 | | /// To prevent misuse which would potentially allow this to be possible, this |
67 | | /// API accepts a [`Digest`] instance, rather than a raw digest value. |
68 | | /// |
69 | | /// [Fiat-Shamir heuristic]: https://en.wikipedia.org/wiki/Fiat%E2%80%93Shamir_heuristic |
70 | | #[cfg(feature = "digest")] |
71 | | pub trait DigestSigner<D: Digest, S> { |
72 | | /// Sign the given prehashed message [`Digest`], returning a signature. |
73 | | /// |
74 | | /// Panics in the event of a signing error. |
75 | 0 | fn sign_digest(&self, digest: D) -> S { |
76 | 0 | self.try_sign_digest(digest) |
77 | 0 | .expect("signature operation failed") |
78 | 0 | } |
79 | | |
80 | | /// Attempt to sign the given prehashed message [`Digest`], returning a |
81 | | /// digital signature on success, or an error if something went wrong. |
82 | | fn try_sign_digest(&self, digest: D) -> Result<S, Error>; |
83 | | } |
84 | | |
85 | | /// Sign the given message using the provided external randomness source. |
86 | | #[cfg(feature = "rand_core")] |
87 | | pub trait RandomizedSigner<S> { |
88 | | /// Sign the given message and return a digital signature |
89 | 0 | fn sign_with_rng(&self, rng: &mut impl CryptoRngCore, msg: &[u8]) -> S { |
90 | 0 | self.try_sign_with_rng(rng, msg) |
91 | 0 | .expect("signature operation failed") |
92 | 0 | } |
93 | | |
94 | | /// Attempt to sign the given message, returning a digital signature on |
95 | | /// success, or an error if something went wrong. |
96 | | /// |
97 | | /// The main intended use case for signing errors is when communicating |
98 | | /// with external signers, e.g. cloud KMS, HSMs, or other hardware tokens. |
99 | | fn try_sign_with_rng(&self, rng: &mut impl CryptoRngCore, msg: &[u8]) -> Result<S, Error>; |
100 | | } |
101 | | |
102 | | /// Combination of [`DigestSigner`] and [`RandomizedSigner`] with support for |
103 | | /// computing a signature over a digest which requires entropy from an RNG. |
104 | | #[cfg(all(feature = "digest", feature = "rand_core"))] |
105 | | pub trait RandomizedDigestSigner<D: Digest, S> { |
106 | | /// Sign the given prehashed message `Digest`, returning a signature. |
107 | | /// |
108 | | /// Panics in the event of a signing error. |
109 | 0 | fn sign_digest_with_rng(&self, rng: &mut impl CryptoRngCore, digest: D) -> S { |
110 | 0 | self.try_sign_digest_with_rng(rng, digest) |
111 | 0 | .expect("signature operation failed") |
112 | 0 | } |
113 | | |
114 | | /// Attempt to sign the given prehashed message `Digest`, returning a |
115 | | /// digital signature on success, or an error if something went wrong. |
116 | | fn try_sign_digest_with_rng(&self, rng: &mut impl CryptoRngCore, digest: D) |
117 | | -> Result<S, Error>; |
118 | | } |