pimalaya_stream/
tls.rs

1//! User-facing TLS configuration.
2//!
3//! Consumers construct a [`Tls`] and pass it to a runtime-specific connector
4//! (e.g. [`StreamStd::connect_tls`] / [`StreamStd::upgrade_tls`]); the
5//! underlying TLS backend types (`rustls`, `native-tls`) never escape this
6//! crate.
7//!
8//! ALPN lives on [`Rustls`] rather than [`Tls`] because `native-tls` does
9//! not expose an ALPN option. Protocol crates (`io-imap`, `io-smtp`, ...)
10//! ship `default_alpn()` helpers so config layers can populate
11//! `rustls.alpn` before calling `connect_tls`.
12//!
13//! [`StreamStd::connect_tls`]: crate::std::stream::StreamStd::connect_tls
14//! [`StreamStd::upgrade_tls`]: crate::std::stream::StreamStd::upgrade_tls
15
16use std::path::PathBuf;
17
18/// TLS settings shared by both backends.
19#[derive(Clone, Debug, Default)]
20pub struct Tls {
21    /// TLS backend selector. `None` falls back to the first enabled feature
22    /// in this order: `rustls-ring`, `rustls-aws`, `native-tls`.
23    pub provider: Option<TlsProvider>,
24    /// Rustls-specific options. Ignored when the resolved provider is
25    /// [`TlsProvider::NativeTls`].
26    pub rustls: Rustls,
27    /// Optional certificate to trust, as a path to a PEM file.
28    ///
29    /// Under rustls it is pinned to the server's leaf (e.g. Proton Bridge),
30    /// else used as an extra trust anchor; under native-tls, a root
31    /// certificate.
32    pub cert: Option<PathBuf>,
33}
34
35/// TLS backend selector.
36#[derive(Clone, Debug)]
37pub enum TlsProvider {
38    /// The rustls backend.
39    Rustls,
40    /// The platform-backed native-tls backend.
41    NativeTls,
42}
43
44/// Rustls-specific TLS options.
45#[derive(Clone, Debug, Default)]
46pub struct Rustls {
47    /// Crypto provider. `None` falls back to `ring` if enabled, otherwise
48    /// `aws-lc-rs`.
49    pub crypto: Option<RustlsCrypto>,
50    /// ALPN protocol identifiers offered during the handshake (e.g.
51    /// `vec!["imap".into()]`). An empty vec skips ALPN negotiation. Ignored
52    /// by `native-tls`.
53    pub alpn: Vec<String>,
54}
55
56/// Rustls crypto provider selector.
57#[derive(Clone, Debug)]
58pub enum RustlsCrypto {
59    /// The aws-lc-rs crypto provider.
60    Aws,
61    /// The ring crypto provider.
62    Ring,
63}
pimalaya_stream/tls.rs

pimalaya_stream/
tls.rs
