bc_components/signing/
signer.rs

1use crate::{Result, Signature, SigningOptions};
2
3/// A trait for types capable of creating digital signatures.
4///
5/// The `Signer` trait provides methods for signing messages with various
6/// cryptographic signature schemes. Implementations of this trait can sign
7/// messages using different algorithms according to the specific signer type.
8///
9/// This trait is implemented by `SigningPrivateKey` for all supported signature
10/// schemes.
11///
12/// # Examples
13///
14/// ```
15/// use bc_components::{SignatureScheme, Signer, Verifier};
16///
17/// // Create a key pair using the default signature scheme (Schnorr)
18/// let (private_key, public_key) = SignatureScheme::default().keypair();
19///
20/// // Sign a message
21/// let message = b"Hello, world!";
22/// let signature = private_key.sign(&message).unwrap();
23///
24/// // Verify the signature
25/// assert!(public_key.verify(&signature, &message));
26/// ```
27pub trait Signer {
28    /// Signs a message with additional options specific to the signature
29    /// scheme.
30    ///
31    /// # Arguments
32    ///
33    /// * `message` - The message to sign
34    /// * `options` - Optional signing options (algorithm-specific parameters)
35    ///
36    /// # Returns
37    ///
38    /// A `Result` containing the digital signature or an error if signing
39    /// fails.
40    ///
41    /// # Examples
42    ///
43    /// ```ignore
44    /// # // Requires secp256k1 feature (enabled by default)
45    /// use std::{cell::RefCell, rc::Rc};
46    ///
47    /// use bc_components::{SignatureScheme, Signer, SigningOptions, Verifier};
48    /// use bc_rand::SecureRandomNumberGenerator;
49    ///
50    /// // Create a key pair
51    /// let (private_key, public_key) = SignatureScheme::Schnorr.keypair();
52    ///
53    /// // Create signing options for a Schnorr signature
54    /// let rng = Rc::new(RefCell::new(SecureRandomNumberGenerator));
55    /// let options = SigningOptions::Schnorr { rng };
56    ///
57    /// // Sign a message with options
58    /// let message = b"Hello, world!";
59    /// let signature = private_key
60    ///     .sign_with_options(&message, Some(options))
61    ///     .unwrap();
62    ///
63    /// // Verify the signature
64    /// assert!(public_key.verify(&signature, &message));
65    /// ```
66    fn sign_with_options(
67        &self,
68        message: &dyn AsRef<[u8]>,
69        options: Option<SigningOptions>,
70    ) -> Result<Signature>;
71
72    /// Signs a message using default options.
73    ///
74    /// This is a convenience method that calls `sign_with_options` with `None`
75    /// for the options parameter.
76    ///
77    /// # Arguments
78    ///
79    /// * `message` - The message to sign
80    ///
81    /// # Returns
82    ///
83    /// A `Result` containing the digital signature or an error if signing
84    /// fails.
85    ///
86    /// # Examples
87    ///
88    /// ```ignore
89    /// # // Requires secp256k1 feature (enabled by default)
90    /// use bc_components::{SignatureScheme, Signer};
91    ///
92    /// // Create a key pair
93    /// let (private_key, _) = SignatureScheme::Ecdsa.keypair();
94    ///
95    /// // Sign a message
96    /// let message = b"Hello, world!";
97    /// let signature = private_key.sign(&message).unwrap();
98    /// ```
99    fn sign(&self, message: &dyn AsRef<[u8]>) -> Result<Signature> {
100        self.sign_with_options(message, None)
101    }
102}
103
104/// A trait for types capable of verifying digital signatures.
105///
106/// The `Verifier` trait provides a method to verify that a signature was
107/// created by a corresponding signer for a specific message. This trait is
108/// implemented by `SigningPublicKey` for all supported signature schemes.
109///
110/// # Examples
111///
112/// ```ignore
113/// # // Requires secp256k1 feature (enabled by default)
114/// use bc_components::{SignatureScheme, Signer, Verifier};
115///
116/// // Create a key pair using the ECDSA signature scheme
117/// let (private_key, public_key) = SignatureScheme::Ecdsa.keypair();
118///
119/// // Sign a message
120/// let message = b"Hello, world!";
121/// let signature = private_key.sign(&message).unwrap();
122///
123/// // Verify the signature
124/// assert!(public_key.verify(&signature, &message));
125///
126/// // Verification should fail for a different message
127/// assert!(!public_key.verify(&signature, &b"Different message"));
128/// ```
129pub trait Verifier {
130    /// Verifies a signature against a message.
131    ///
132    /// # Arguments
133    ///
134    /// * `signature` - The signature to verify
135    /// * `message` - The message that was allegedly signed
136    ///
137    /// # Returns
138    ///
139    /// `true` if the signature is valid for the message, `false` otherwise.
140    ///
141    /// # Examples
142    ///
143    /// ```
144    /// # #[cfg(feature = "ed25519")]
145    /// # {
146    /// use bc_components::{SignatureScheme, Signer, Verifier};
147    ///
148    /// // Create a key pair
149    /// let (private_key, public_key) = SignatureScheme::Ed25519.keypair();
150    ///
151    /// // Sign a message
152    /// let message = b"Hello, world!";
153    /// let signature = private_key.sign(&message).unwrap();
154    ///
155    /// // Verify the signature with the correct message (should succeed)
156    /// assert!(public_key.verify(&signature, &message));
157    ///
158    /// // Verify the signature with an incorrect message (should fail)
159    /// assert!(!public_key.verify(&signature, &b"Tampered message"));
160    /// # }
161    /// ```
162    fn verify(&self, signature: &Signature, message: &dyn AsRef<[u8]>) -> bool;
163}
bc_components/signing/signer.rs

bc_components/signing/
signer.rs
