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

bc_components/signing/
signer.rs
