bc_components/
keypair.rs

1use bc_rand::RandomNumberGenerator;
2use anyhow::Result;
3
4use crate::{EncapsulationScheme, PrivateKeys, PublicKeys, SignatureScheme};
5
6/// Generates a key pair using the default signature and encapsulation schemes.
7///
8/// This function creates a new key pair containing both signing and encapsulation
9/// (encryption) keys using the default cryptographic schemes:
10/// - Default signature scheme: Currently `SignatureScheme::Schnorr`
11/// - Default encapsulation scheme: Currently `EncapsulationScheme::X25519`
12///
13/// # Returns
14///
15/// A tuple containing:
16/// - `PrivateKeys`: The private keys for signing and encapsulation
17/// - `PublicKeys`: The corresponding public keys
18///
19/// # Example
20///
21/// ```
22/// use bc_components::keypair;
23///
24/// // Generate a key pair with default cryptographic schemes
25/// let (private_keys, public_keys) = keypair();
26///
27/// // The private_keys can be used for signing and decryption
28/// // The public_keys can be shared and used for verification and encryption
29/// ```
30pub fn keypair() -> (PrivateKeys, PublicKeys) {
31    keypair_opt(SignatureScheme::default(), EncapsulationScheme::default())
32}
33
34/// Generates a key pair using the default schemes and a custom random number generator.
35///
36/// This function creates a deterministic key pair using the provided random number
37/// generator and the default cryptographic schemes.
38///
39/// # Parameters
40///
41/// * `rng` - A mutable reference to a random number generator
42///
43/// # Returns
44///
45/// A Result containing a tuple with `PrivateKeys` and `PublicKeys` if successful,
46/// or an error if key generation fails.
47///
48/// # Errors
49///
50/// Returns an error if either the signature or encapsulation key generation fails.
51///
52/// # Example
53///
54/// ```
55/// use bc_components::keypair_using;
56/// use bc_rand::SecureRandomNumberGenerator;
57///
58/// // Create a random number generator
59/// let mut rng = SecureRandomNumberGenerator;
60///
61/// // Generate a key pair with default schemes but custom RNG
62/// let result = keypair_using(&mut rng);
63/// assert!(result.is_ok());
64/// ```
65pub fn keypair_using(rng: &mut impl RandomNumberGenerator) -> Result<(PrivateKeys, PublicKeys)> {
66    keypair_opt_using(SignatureScheme::default(), EncapsulationScheme::default(), rng)
67}
68
69/// Generates a key pair with specified signature and encapsulation schemes.
70///
71/// This function creates a new key pair with custom cryptographic schemes for
72/// both signing and encryption operations.
73///
74/// # Parameters
75///
76/// * `signature_scheme` - The signature scheme to use (e.g., Schnorr, ECDSA, Ed25519)
77/// * `encapsulation_scheme` - The key encapsulation scheme to use (e.g., X25519, ML-KEM)
78///
79/// # Returns
80///
81/// A tuple containing:
82/// - `PrivateKeys`: The private keys for signing and encapsulation
83/// - `PublicKeys`: The corresponding public keys
84///
85/// # Example
86///
87/// ```
88/// use bc_components::{keypair_opt, SignatureScheme, EncapsulationScheme};
89///
90/// // Generate a key pair with Ed25519 for signing and ML-KEM768 for encryption
91/// let (private_keys, public_keys) = keypair_opt(
92///     SignatureScheme::Ed25519,
93///     EncapsulationScheme::MLKEM768
94/// );
95/// ```
96pub fn keypair_opt(signature_scheme: SignatureScheme, encapsulation_scheme: EncapsulationScheme) -> (PrivateKeys, PublicKeys) {
97    let (signing_private_key, signing_public_key) = signature_scheme.keypair();
98    let (encapsulation_private_key, encapsulation_public_key) = encapsulation_scheme.keypair();
99    let private_keys = PrivateKeys::with_keys(signing_private_key, encapsulation_private_key);
100    let public_keys = PublicKeys::new(signing_public_key, encapsulation_public_key);
101    (private_keys, public_keys)
102}
103
104/// Generates a key pair with specified schemes using a custom random number generator.
105///
106/// This function provides the most control over key pair generation by allowing
107/// custom specification of both cryptographic schemes and the random number generator.
108///
109/// # Parameters
110///
111/// * `signature_scheme` - The signature scheme to use
112/// * `encapsulation_scheme` - The key encapsulation scheme to use
113/// * `rng` - A mutable reference to a random number generator
114///
115/// # Returns
116///
117/// A Result containing a tuple with `PrivateKeys` and `PublicKeys` if successful,
118/// or an error if key generation fails.
119///
120/// # Errors
121///
122/// Returns an error if either the signature or encapsulation key generation fails.
123///
124/// # Example
125///
126/// ```
127/// use bc_components::{keypair_opt_using, SignatureScheme, EncapsulationScheme};
128/// use bc_rand::SecureRandomNumberGenerator;
129///
130/// // Create a random number generator
131/// let mut rng = SecureRandomNumberGenerator;
132///
133/// // Generate a specific key pair deterministically
134/// let result = keypair_opt_using(
135///     SignatureScheme::Ecdsa,
136///     EncapsulationScheme::X25519,
137///     &mut rng
138/// );
139/// assert!(result.is_ok());
140/// ```
141pub fn keypair_opt_using(signature_scheme: SignatureScheme, encapsulation_scheme: EncapsulationScheme, rng: &mut impl RandomNumberGenerator) -> Result<(PrivateKeys, PublicKeys)> {
142    let (signing_private_key, signing_public_key) = signature_scheme.keypair_using(rng, "")?;
143    let (encapsulation_private_key, encapsulation_public_key) = encapsulation_scheme.keypair_using(rng)?;
144    let private_keys = PrivateKeys::with_keys(signing_private_key, encapsulation_private_key);
145    let public_keys = PublicKeys::new(signing_public_key, encapsulation_public_key);
146    Ok((private_keys, public_keys))
147}
bc_components/keypair.rs

bc_components/
keypair.rs
