bc_components/signing/
signer.rs

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

bc_components/signing/
signer.rs
