bc_components/
keypair.rs

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

bc_components/
keypair.rs
