tlspuffin/tls/rustls/
kx.rs

1use crate::tls::rustls::error::Error;
2use crate::tls::rustls::msgs::enums::NamedGroup;
3
4/// An in-progress key exchange.  This has the algorithm,
5/// our private key, and our public key.
6pub struct KeyExchange {
7    pub skxg: &'static SupportedKxGroup,
8    pub privkey: ring::agreement::EphemeralPrivateKey,
9    pub pubkey: ring::agreement::PublicKey,
10}
11
12impl KeyExchange {
13    /// Choose a SupportedKxGroup by name, from a list of supported groups.
14    pub fn choose(
15        name: NamedGroup,
16        supported: &[&'static SupportedKxGroup],
17    ) -> Option<&'static SupportedKxGroup> {
18        supported.iter().find(|skxg| skxg.name == name).cloned()
19    }
20
21    /// Start a key exchange, using the given SupportedKxGroup.
22    ///
23    /// This generates an ephemeral key pair and stores it in the returned KeyExchange object.
24    pub fn start(skxg: &'static SupportedKxGroup) -> Option<Self> {
25        let rng = ring::rand::SystemRandom::new();
26        let ours =
27            ring::agreement::EphemeralPrivateKey::generate(skxg.agreement_algorithm, &rng).ok()?;
28
29        let pubkey = ours.compute_public_key().ok()?;
30
31        Some(Self {
32            skxg,
33            privkey: ours,
34            pubkey,
35        })
36    }
37
38    /// Return the group being used.
39    pub fn group(&self) -> NamedGroup {
40        self.skxg.name
41    }
42
43    /// Completes the key exchange, given the peer's public key.
44    ///
45    /// The shared secret is passed into the closure passed down in `f`, and the result of calling
46    /// `f` is returned to the caller.
47    pub fn complete<T>(
48        self,
49        peer: &[u8],
50        f: impl FnOnce(&[u8]) -> Result<T, ()>,
51    ) -> Result<T, Error> {
52        let peer_key = ring::agreement::UnparsedPublicKey::new(self.skxg.agreement_algorithm, peer);
53        ring::agreement::agree_ephemeral(self.privkey, &peer_key, (), f)
54            .map_err(|()| Error::PeerMisbehavedError("key agreement failed".to_string()))
55    }
56}
57
58/// A key-exchange group supported by rustls.
59///
60/// All possible instances of this class are provided by the library in
61/// the `ALL_KX_GROUPS` array.
62#[derive(Debug)]
63pub struct SupportedKxGroup {
64    /// The IANA "TLS Supported Groups" name of the group
65    pub name: NamedGroup,
66
67    /// The corresponding ring agreement::Algorithm
68    pub agreement_algorithm: &'static ring::agreement::Algorithm,
69}
70
71/// Ephemeral ECDH on curve25519 (see RFC7748)
72pub static X25519: SupportedKxGroup = SupportedKxGroup {
73    name: NamedGroup::X25519,
74    agreement_algorithm: &ring::agreement::X25519,
75};
76
77/// Ephemeral ECDH on secp256r1 (aka NIST-P256)
78pub static SECP256R1: SupportedKxGroup = SupportedKxGroup {
79    name: NamedGroup::secp256r1,
80    agreement_algorithm: &ring::agreement::ECDH_P256,
81};
82
83/// Ephemeral ECDH on secp384r1 (aka NIST-P384)
84pub static SECP384R1: SupportedKxGroup = SupportedKxGroup {
85    name: NamedGroup::secp384r1,
86    agreement_algorithm: &ring::agreement::ECDH_P384,
87};
88
89/// A list of all the key exchange groups supported by rustls.
90pub static ALL_KX_GROUPS: [&SupportedKxGroup; 3] = [&X25519, &SECP256R1, &SECP384R1];