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
12/// schemes.
13///
14/// # Examples
15///
16/// ```
17/// use bc_components::{SignatureScheme, Signer, Verifier};
18///
19/// // Create a key pair using the default signature scheme (Schnorr)
20/// let (private_key, public_key) = SignatureScheme::default().keypair();
21///
22/// // Sign a message
23/// let message = b"Hello, world!";
24/// let signature = private_key.sign(&message).unwrap();
25///
26/// // Verify the signature
27/// assert!(public_key.verify(&signature, &message));
28/// ```
29pub trait Signer {
30    /// Signs a message with additional options specific to the signature
31    /// scheme.
32    ///
33    /// # Arguments
34    ///
35    /// * `message` - The message to sign
36    /// * `options` - Optional signing options (algorithm-specific parameters)
37    ///
38    /// # Returns
39    ///
40    /// A `Result` containing the digital signature or an error if signing
41    /// fails.
42    ///
43    /// # Examples
44    ///
45    /// ```
46    /// use std::{cell::RefCell, rc::Rc};
47    ///
48    /// use bc_components::{SignatureScheme, Signer, SigningOptions, Verifier};
49    /// use bc_rand::SecureRandomNumberGenerator;
50    ///
51    /// // Create a key pair
52    /// let (private_key, public_key) = SignatureScheme::Schnorr.keypair();
53    ///
54    /// // Create signing options for a Schnorr signature
55    /// let rng = Rc::new(RefCell::new(SecureRandomNumberGenerator));
56    /// let options = SigningOptions::Schnorr { rng };
57    ///
58    /// // Sign a message with options
59    /// let message = b"Hello, world!";
60    /// let signature = private_key
61    ///     .sign_with_options(&message, Some(options))
62    ///     .unwrap();
63    ///
64    /// // Verify the signature
65    /// assert!(public_key.verify(&signature, &message));
66    /// ```
67    fn sign_with_options(
68        &self,
69        message: &dyn AsRef<[u8]>,
70        options: Option<SigningOptions>,
71    ) -> Result<Signature>;
72
73    /// Signs a message using default options.
74    ///
75    /// This is a convenience method that calls `sign_with_options` with `None`
76    /// for the options parameter.
77    ///
78    /// # Arguments
79    ///
80    /// * `message` - The message to sign
81    ///
82    /// # Returns
83    ///
84    /// A `Result` containing the digital signature or an error if signing
85    /// fails.
86    ///
87    /// # Examples
88    ///
89    /// ```
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/// ```
113/// use bc_components::{SignatureScheme, Signer, Verifier};
114///
115/// // Create a key pair using the ECDSA signature scheme
116/// let (private_key, public_key) = SignatureScheme::Ecdsa.keypair();
117///
118/// // Sign a message
119/// let message = b"Hello, world!";
120/// let signature = private_key.sign(&message).unwrap();
121///
122/// // Verify the signature
123/// assert!(public_key.verify(&signature, &message));
124///
125/// // Verification should fail for a different message
126/// assert!(!public_key.verify(&signature, &b"Different message"));
127/// ```
128pub trait Verifier {
129    /// Verifies a signature against a message.
130    ///
131    /// # Arguments
132    ///
133    /// * `signature` - The signature to verify
134    /// * `message` - The message that was allegedly signed
135    ///
136    /// # Returns
137    ///
138    /// `true` if the signature is valid for the message, `false` otherwise.
139    ///
140    /// # Examples
141    ///
142    /// ```
143    /// use bc_components::{SignatureScheme, Signer, Verifier};
144    ///
145    /// // Create a key pair
146    /// let (private_key, public_key) = SignatureScheme::Ed25519.keypair();
147    ///
148    /// // Sign a message
149    /// let message = b"Hello, world!";
150    /// let signature = private_key.sign(&message).unwrap();
151    ///
152    /// // Verify the signature with the correct message (should succeed)
153    /// assert!(public_key.verify(&signature, &message));
154    ///
155    /// // Verify the signature with an incorrect message (should fail)
156    /// assert!(!public_key.verify(&signature, &b"Tampered message"));
157    /// ```
158    fn verify(&self, signature: &Signature, message: &dyn AsRef<[u8]>) -> bool;
159}
bc_components/signing/signer.rs

bc_components/signing/
signer.rs
