bc_components/
keypair.rs

1use anyhow::Result;
2use bc_rand::RandomNumberGenerator;
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
9/// encapsulation (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
35/// generator.
36///
37/// This function creates a deterministic key pair using the provided random
38/// number generator and the default cryptographic schemes.
39///
40/// # Parameters
41///
42/// * `rng` - A mutable reference to a random number generator
43///
44/// # Returns
45///
46/// A Result containing a tuple with `PrivateKeys` and `PublicKeys` if
47/// successful, or an error if key generation fails.
48///
49/// # Errors
50///
51/// Returns an error if either the signature or encapsulation key generation
52/// fails.
53///
54/// # Example
55///
56/// ```
57/// use bc_components::keypair_using;
58/// use bc_rand::SecureRandomNumberGenerator;
59///
60/// // Create a random number generator
61/// let mut rng = SecureRandomNumberGenerator;
62///
63/// // Generate a key pair with default schemes but custom RNG
64/// let result = keypair_using(&mut rng);
65/// assert!(result.is_ok());
66/// ```
67pub fn keypair_using(
68    rng: &mut impl RandomNumberGenerator,
69) -> Result<(PrivateKeys, PublicKeys)> {
70    keypair_opt_using(
71        SignatureScheme::default(),
72        EncapsulationScheme::default(),
73        rng,
74    )
75}
76
77/// Generates a key pair with specified signature and encapsulation schemes.
78///
79/// This function creates a new key pair with custom cryptographic schemes for
80/// both signing and encryption operations.
81///
82/// # Parameters
83///
84/// * `signature_scheme` - The signature scheme to use (e.g., Schnorr, ECDSA,
85///   Ed25519)
86/// * `encapsulation_scheme` - The key encapsulation scheme to use (e.g.,
87///   X25519, ML-KEM)
88///
89/// # Returns
90///
91/// A tuple containing:
92/// - `PrivateKeys`: The private keys for signing and encapsulation
93/// - `PublicKeys`: The corresponding public keys
94///
95/// # Example
96///
97/// ```
98/// use bc_components::{EncapsulationScheme, SignatureScheme, keypair_opt};
99///
100/// // Generate a key pair with Ed25519 for signing and ML-KEM768 for encryption
101/// let (private_keys, public_keys) =
102///     keypair_opt(SignatureScheme::Ed25519, EncapsulationScheme::MLKEM768);
103/// ```
104pub fn keypair_opt(
105    signature_scheme: SignatureScheme,
106    encapsulation_scheme: EncapsulationScheme,
107) -> (PrivateKeys, PublicKeys) {
108    let (signing_private_key, signing_public_key) = signature_scheme.keypair();
109    let (encapsulation_private_key, encapsulation_public_key) =
110        encapsulation_scheme.keypair();
111    let private_keys =
112        PrivateKeys::with_keys(signing_private_key, encapsulation_private_key);
113    let public_keys =
114        PublicKeys::new(signing_public_key, encapsulation_public_key);
115    (private_keys, public_keys)
116}
117
118/// Generates a key pair with specified schemes using a custom random number
119/// generator.
120///
121/// This function provides the most control over key pair generation by allowing
122/// custom specification of both cryptographic schemes and the random number
123/// generator.
124///
125/// # Parameters
126///
127/// * `signature_scheme` - The signature scheme to use
128/// * `encapsulation_scheme` - The key encapsulation scheme to use
129/// * `rng` - A mutable reference to a random number generator
130///
131/// # Returns
132///
133/// A Result containing a tuple with `PrivateKeys` and `PublicKeys` if
134/// successful, or an error if key generation fails.
135///
136/// # Errors
137///
138/// Returns an error if either the signature or encapsulation key generation
139/// fails.
140///
141/// # Example
142///
143/// ```
144/// use bc_components::{
145///     EncapsulationScheme, SignatureScheme, keypair_opt_using,
146/// };
147/// use bc_rand::SecureRandomNumberGenerator;
148///
149/// // Create a random number generator
150/// let mut rng = SecureRandomNumberGenerator;
151///
152/// // Generate a specific key pair deterministically
153/// let result = keypair_opt_using(
154///     SignatureScheme::Ecdsa,
155///     EncapsulationScheme::X25519,
156///     &mut rng,
157/// );
158/// assert!(result.is_ok());
159/// ```
160pub fn keypair_opt_using(
161    signature_scheme: SignatureScheme,
162    encapsulation_scheme: EncapsulationScheme,
163    rng: &mut impl RandomNumberGenerator,
164) -> Result<(PrivateKeys, PublicKeys)> {
165    let (signing_private_key, signing_public_key) =
166        signature_scheme.keypair_using(rng, "")?;
167    let (encapsulation_private_key, encapsulation_public_key) =
168        encapsulation_scheme.keypair_using(rng)?;
169    let private_keys =
170        PrivateKeys::with_keys(signing_private_key, encapsulation_private_key);
171    let public_keys =
172        PublicKeys::new(signing_public_key, encapsulation_public_key);
173    Ok((private_keys, public_keys))
174}
bc_components/keypair.rs

bc_components/
keypair.rs
