Skip to main content

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. [`Stream::connect_tls`] / [`Stream::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//! [`Stream::connect_tls`]: crate::stream::Stream::connect_tls
14//! [`Stream::upgrade_tls`]: crate::stream::Stream::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    /// Certificate to trust in the server, beside the platform store.
28    pub server: Option<TlsServer>,
29    /// Certificate presented when the server asks for one (mutual TLS).
30    pub client: Option<TlsClient>,
31}
32
33/// What the client trusts in the server, beyond the platform store.
34#[derive(Clone, Debug)]
35pub struct TlsServer {
36    /// Path to the PEM certificate.
37    ///
38    /// Under rustls it is pinned to the server's leaf, else used as an
39    /// extra trust anchor; under native-tls, a root certificate.
40    pub cert: PathBuf,
41}
42
43/// The certificate the client presents, with its private key.
44#[derive(Clone, Debug)]
45pub struct TlsClient {
46    /// Path to the PEM certificate, optionally followed by intermediates.
47    pub cert: PathBuf,
48    /// Path to the PEM private key.
49    ///
50    /// PKCS#8 under native-tls, rustls also reads PKCS#1 and SEC1.
51    pub key: PathBuf,
52}
53
54/// TLS backend selector.
55#[derive(Clone, Debug)]
56pub enum TlsProvider {
57    /// The rustls backend.
58    Rustls,
59    /// The platform-backed native-tls backend.
60    NativeTls,
61}
62
63/// Rustls-specific TLS options.
64#[derive(Clone, Debug, Default)]
65pub struct Rustls {
66    /// Crypto provider. `None` falls back to `ring` if enabled, otherwise
67    /// `aws-lc-rs`.
68    pub crypto: Option<RustlsCrypto>,
69    /// ALPN protocol identifiers offered during the handshake (e.g.
70    /// `vec!["imap".into()]`). An empty vec skips ALPN negotiation. Ignored
71    /// by `native-tls`.
72    pub alpn: Vec<String>,
73}
74
75/// Rustls crypto provider selector.
76#[derive(Clone, Debug)]
77pub enum RustlsCrypto {
78    /// The aws-lc-rs crypto provider.
79    Aws,
80    /// The ring crypto provider.
81    Ring,
82}