Skip to main content

hyprstream_rpc/transport/
pq_provider.rs

1//! Post-quantum hybrid TLS crypto-provider policies (#557 / S6 of epic #550).
2//!
3//! The owned iroh endpoint uses a provider that offers hybrid X25519MLKEM768
4//! plus classical X25519 because iroh reuses it for public N0 relay and pkarr
5//! HTTPS. The owned Hyprstream ALPNs remain hybrid-only at the completed
6//! carrier-admission hook, and application-layer HyKEM remains the primary,
7//! transport-independent confidentiality guarantee on every path.
8
9use std::sync::Arc;
10
11use rustls::crypto::{aws_lc_rs, CryptoProvider};
12
13const INTERNAL_MESH_GROUPS: &[rustls::NamedGroup] = &[rustls::NamedGroup::X25519MLKEM768];
14const EXTERNAL_INTEROP_GROUPS: &[rustls::NamedGroup] = &[
15    rustls::NamedGroup::X25519MLKEM768,
16    rustls::NamedGroup::X25519,
17];
18
19/// The effective process-wide rustls provider does not match hyprstream's
20/// declared external-interoperability policy.
21#[derive(Debug)]
22pub struct ProviderPolicyError {
23    expected: &'static [rustls::NamedGroup],
24    boundary: &'static str,
25    actual: Vec<rustls::NamedGroup>,
26}
27
28impl std::fmt::Display for ProviderPolicyError {
29    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
30        write!(
31            formatter,
32            "rustls {} crypto policy mismatch: expected {:?}, got {:?}",
33            self.boundary, self.expected, self.actual
34        )
35    }
36}
37
38impl std::error::Error for ProviderPolicyError {}
39
40fn provider_with_groups(
41    groups: impl IntoIterator<Item = &'static dyn rustls::crypto::SupportedKxGroup>,
42) -> CryptoProvider {
43    CryptoProvider {
44        kx_groups: groups.into_iter().collect(),
45        ..aws_lc_rs::default_provider()
46    }
47}
48
49fn external_interop_provider() -> CryptoProvider {
50    provider_with_groups([
51        aws_lc_rs::kx_group::X25519MLKEM768,
52        aws_lc_rs::kx_group::X25519,
53    ])
54}
55
56/// Provider for an owned internal-mesh connection. Classical fallback is
57/// intentionally absent, so an X25519-only peer fails the TLS handshake.
58pub fn internal_mesh_crypto_provider() -> Arc<CryptoProvider> {
59    Arc::new(provider_with_groups([aws_lc_rs::kx_group::X25519MLKEM768]))
60}
61
62/// Provider for an explicitly declared external-interoperability boundary.
63/// PQ hybrid is preferred, with classical X25519 retained for non-PQ peers.
64pub fn pq_crypto_provider() -> Arc<CryptoProvider> {
65    Arc::new(external_interop_provider())
66}
67
68fn group_names(provider: &CryptoProvider) -> Vec<rustls::NamedGroup> {
69    provider
70        .kx_groups
71        .iter()
72        .map(|group| group.name())
73        .collect()
74}
75
76fn validate_provider(
77    provider: &CryptoProvider,
78    expected: &'static [rustls::NamedGroup],
79    boundary: &'static str,
80) -> Result<(), ProviderPolicyError> {
81    let actual = group_names(provider);
82    if actual != expected {
83        return Err(ProviderPolicyError {
84            expected,
85            boundary,
86            actual,
87        });
88    }
89    Ok(())
90}
91
92/// Validate that a caller-supplied config uses the exact owned-mesh policy.
93/// This is intentionally stricter than merely preferring the hybrid group:
94/// any classical fallback makes the config unsuitable for an owned boundary.
95pub fn validate_internal_mesh_crypto_provider(
96    provider: &CryptoProvider,
97) -> Result<(), ProviderPolicyError> {
98    validate_provider(provider, INTERNAL_MESH_GROUPS, "owned-mesh")
99}
100
101/// Install and validate the external-interoperability provider as rustls's
102/// process-wide default.
103///
104/// rustls is first-install-wins. Consequently, silently ignoring
105/// `install_default` failure can leave a process on ring/X25519. This function
106/// always inspects the effective provider after installation and returns an
107/// error if an
108/// earlier initializer installed anything other than the exact declared
109/// external policy. Call it before constructing any WebTransport/rustls
110/// builder; a policy violation fails startup instead of downgrading transport.
111pub fn install_pq_crypto_provider() -> Result<(), ProviderPolicyError> {
112    let _ = external_interop_provider().install_default();
113
114    let provider = CryptoProvider::get_default().ok_or(ProviderPolicyError {
115        expected: EXTERNAL_INTEROP_GROUPS,
116        boundary: "process-default external-interoperability",
117        actual: Vec::new(),
118    })?;
119    validate_provider(
120        provider,
121        EXTERNAL_INTEROP_GROUPS,
122        "process-default external-interoperability",
123    )
124}
125
126#[cfg(test)]
127#[allow(clippy::expect_used)]
128mod tests {
129    use super::*;
130
131    #[test]
132    fn external_interop_is_pq_first_with_declared_x25519_fallback() {
133        assert_eq!(group_names(&pq_crypto_provider()), EXTERNAL_INTEROP_GROUPS);
134    }
135
136    #[test]
137    fn internal_mesh_is_hybrid_only() {
138        assert_eq!(
139            group_names(&internal_mesh_crypto_provider()),
140            INTERNAL_MESH_GROUPS
141        );
142    }
143
144    #[test]
145    fn internal_mesh_rejects_external_reordered_and_duplicate_groups() {
146        let mutations = [
147            provider_with_groups([
148                aws_lc_rs::kx_group::X25519MLKEM768,
149                aws_lc_rs::kx_group::X25519,
150            ]),
151            provider_with_groups([
152                aws_lc_rs::kx_group::X25519,
153                aws_lc_rs::kx_group::X25519MLKEM768,
154            ]),
155            provider_with_groups([
156                aws_lc_rs::kx_group::X25519MLKEM768,
157                aws_lc_rs::kx_group::X25519MLKEM768,
158            ]),
159        ];
160
161        for provider in mutations {
162            validate_internal_mesh_crypto_provider(&provider)
163                .expect_err("every non-exact owned-mesh group list must be rejected");
164        }
165    }
166
167    #[test]
168    fn external_interop_live_handshake_allows_classical_peer() {
169        let certified = rcgen::generate_simple_self_signed(vec!["localhost".to_owned()])
170            .expect("generate test certificate");
171        let cert = certified.cert.der().clone();
172        let key = rustls::pki_types::PrivatePkcs8KeyDer::from(certified.key_pair.serialize_der());
173        let server_config = rustls::ServerConfig::builder_with_provider(pq_crypto_provider())
174            .with_safe_default_protocol_versions()
175            .expect("external provider supports TLS 1.3")
176            .with_no_client_auth()
177            .with_single_cert(vec![cert.clone()], key.into())
178            .expect("valid test certificate");
179
180        let mut roots = rustls::RootCertStore::empty();
181        roots.add(cert).expect("add test root");
182        let client_config = rustls::ClientConfig::builder_with_provider(Arc::new(
183            rustls::crypto::ring::default_provider(),
184        ))
185        .with_safe_default_protocol_versions()
186        .expect("ring supports TLS 1.3")
187        .with_root_certificates(roots)
188        .with_no_client_auth();
189
190        let mut server = rustls::ServerConnection::new(Arc::new(server_config))
191            .expect("build server connection");
192        let mut client = rustls::ClientConnection::new(
193            Arc::new(client_config),
194            "localhost".try_into().expect("valid server name"),
195        )
196        .expect("build client connection");
197
198        for _ in 0..8 {
199            let mut client_records = Vec::new();
200            client
201                .write_tls(&mut client_records)
202                .expect("write client TLS records");
203            if !client_records.is_empty() {
204                server
205                    .read_tls(&mut std::io::Cursor::new(client_records))
206                    .expect("read client TLS records");
207                server
208                    .process_new_packets()
209                    .expect("process client TLS records");
210            }
211
212            let mut server_records = Vec::new();
213            server
214                .write_tls(&mut server_records)
215                .expect("write server TLS records");
216            if !server_records.is_empty() {
217                client
218                    .read_tls(&mut std::io::Cursor::new(server_records))
219                    .expect("read server TLS records");
220                client
221                    .process_new_packets()
222                    .expect("process server TLS records");
223            }
224            if !client.is_handshaking() && !server.is_handshaking() {
225                break;
226            }
227        }
228        assert!(!client.is_handshaking() && !server.is_handshaking());
229        assert_eq!(
230            server
231                .negotiated_key_exchange_group()
232                .expect("completed handshake has a group")
233                .name(),
234            rustls::NamedGroup::X25519,
235            "classical fallback is allowed only by the external interop policy"
236        );
237    }
238
239    // This mutation must run in a fresh process because rustls's default is a
240    // OnceLock. The ignored child test is invoked explicitly by its parent.
241    #[test]
242    #[ignore = "subprocess mutation fixture"]
243    fn non_pq_provider_installed_first_child() {
244        rustls::crypto::ring::default_provider()
245            .install_default()
246            .expect("fresh child process must not already have a provider");
247        let error = install_pq_crypto_provider()
248            .expect_err("non-PQ provider must fail closed with a policy error");
249        panic!("expected ring-first policy rejection: {error}");
250    }
251
252    #[test]
253    fn non_pq_provider_installed_first_fails_closed() {
254        let name = "transport::pq_provider::tests::non_pq_provider_installed_first_child";
255        let output = run_provider_fixture(name);
256        assert!(
257            !output.status.success(),
258            "a ring provider installed first must make startup fail"
259        );
260        let child_output = format!(
261            "{}{}",
262            String::from_utf8_lossy(&output.stdout),
263            String::from_utf8_lossy(&output.stderr)
264        );
265        assert!(
266            child_output.contains("crypto policy mismatch"),
267            "ring-first fixture must fail for the expected policy error: {child_output}"
268        );
269    }
270
271    fn run_provider_fixture(name: &str) -> std::process::Output {
272        let mut child =
273            std::process::Command::new(std::env::current_exe().expect("test executable path"))
274                .args(["--ignored", "--exact", name])
275                .stdout(std::process::Stdio::piped())
276                .stderr(std::process::Stdio::piped())
277                .spawn()
278                .expect("spawn provider-ordering mutation child");
279        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(30);
280        loop {
281            if child.try_wait().expect("poll provider fixture").is_some() {
282                return child
283                    .wait_with_output()
284                    .expect("collect provider fixture output");
285            }
286            if std::time::Instant::now() >= deadline {
287                let _ = child.kill();
288                let _ = child.wait();
289                panic!("provider fixture {name} timed out after 30 seconds");
290            }
291            std::thread::sleep(std::time::Duration::from_millis(10));
292        }
293    }
294}