feat: Add client TLS configuration, with built-in support for rustls

Author: LukeMathWalker

libs/Cargo.lock

@@ -19,6 +19,7 @@ vergen-gitcl = { version = "1.0.8", features = ["build"] }
 ahash = "0.8"
 anstyle = "1.0.11"
 anyhow = "1.0.98"
+base64 = "0.22.1"
 better-panic = "0.3.0"
 bimap = "0.6.3"
 bincode = "2"
@@ -96,6 +97,9 @@ reqwest = { version = "0.12", default-features = false, features = [
 reqwest-middleware = "0.4"
 reqwest-retry = "0.7.0"
 reqwest-tracing = "0.5.8"
+rustls = "0.23"
+rustls-pki-types = "1.12.0"
+rustls-platform-verifier = "0.6.1"
 ring = "0.17.14"
 rlimit = "0.10.2"
 ron = "0.10"
@@ -111,6 +115,7 @@ serde_html_form = "0.2"
 serde_json = "1.0.142"
 serde_path_to_error = "0.1"
 serde_stacker = "0.1"
+serde_yaml = "0.9.33"
 sha2 = "0.10.9"
 similar = "2.7.0"
 smallvec = "1"

libs/Cargo.toml

@@ -13,17 +13,18 @@ repository.workspace = true
 license.workspace = true
 readme = "README.md"
 
-[lints.rust]
-unexpected_cfgs = { level = "allow", check-cfg = ['cfg(pavex_ide_hint)'] }
-
 [features]
-default = ["server", "server_request_id", "time", "cookie", "config"]
+default = ["server", "server_request_id", "time", "cookie", "config", "rustls_0_23"]
 
 server = ["dep:hyper-util", "dep:socket2", "tokio/net"]
 config = ["dep:figment"]
 cookie = ["dep:biscotti", "time"]
 server_request_id = ["dep:uuid"]
 time = ["dep:jiff"]
+rustls_0_23 = ["dep:rustls", "dep:rustls-pki-types", "dep:rustls-platform-verifier", "dep:base64"]
+fips = ["rustls?/fips"]
+tls_crypto_provider_ring = ["rustls?/aws_lc_rs"]
+tls_crypto_provider_aws_lc_rs = ["rustls?/ring"]
 
 [dependencies]
 bytes = { workspace = true }
@@ -46,6 +47,7 @@ persist_if_changed = { path = "../persist_if_changed", version = "0.2.7" }
 
 # Configuration
 figment = { workspace = true, features = ["env", "yaml"], optional = true }
+serde_yaml = { workspace = true }
 
 # Route parameters
 matchit = { workspace = true }
@@ -74,6 +76,12 @@ type-safe-id = { workspace = true }
 # Time facilities
 jiff = { workspace = true, features = ["serde"], optional = true }
 
+# TLS
+rustls = { workspace = true, optional = true }
+rustls-pki-types = { workspace = true, optional = true }
+rustls-platform-verifier = { workspace = true, optional = true }
+base64 = { workspace = true, optional = true }
+
 tokio = { workspace = true, features = ["sync", "rt", "time"] }
 hyper = { workspace = true, features = ["full"] }
 hyper-util = { workspace = true, features = [
@@ -93,7 +101,9 @@ tracing = { workspace = true }
 reqwest = { workspace = true }
 itertools = { workspace = true }
 secrecy = { workspace = true, features = ["serde"] }
+serde_yaml = { workspace = true }
 pavex_tracing = { path = "../pavex_tracing" }
+uuid = { workspace = true, features = ["v7", "v4"] }
 
 pavex_macros = { path = "../pavex_macros", features = [
     "allow_unreachable_pub",

libs/pavex/Cargo.toml

@@ -38,6 +38,7 @@ pub mod time {
     //! It's a re-export of the [`[email protected]`](https://docs.rs/jiff/0.2) crate.
     pub use jiff::*;
 }
+pub mod tls;
 
 /// Define a [prebuilt type](https://pavex.dev/docs/guide/dependency_injection/prebuilt_types/).
 ///

libs/pavex/src/lib.rs

@@ -0,0 +1,285 @@
+//! Configure the TLS policy for a client.
+//!
+//! Check out the documentation for [`TlsClientPolicyConfig`](super::TlsClientPolicyConfig) for
+//! a detailed explanation of the available configuration options.
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+// Wrapped into a sub-module to avoid exposing `TlsClientPolicyConfig` in two places:
+// inside `pavex::tls::config` and `pavex::tls::client`.
+// We only want users to see `pavex::tls::client::TlsClientPolicyConfig`.
+pub(crate) mod _config {
+    use super::*;
+
+    #[derive(Debug, Default, Clone, Deserialize, Serialize)]
+    /// Configure the TLS policy for a client.
+    ///
+    /// It covers:
+    /// - The [cryptographic stack](`Self::crypto_provider`) used to secure the connection.
+    /// - Which [TLS versions](`Self::allowed_versions`) are allowed.
+    /// - The [certificate verification](`Self::certificate_verification`) mechanism used to verify server certificates.
+    ///
+    /// For testing/development purposes only, it exposes a few [insecure](`Self::insecure`) configuration options
+    /// that lower the security posture of your client.
+    ///
+    /// # Defaults
+    ///
+    /// The default configuration should be suitable for most production environments:
+    ///
+    /// ```yaml
+    #[doc = include_str!("../../../tests/fixtures/tls_config/default.yaml")]
+    /// ```
+    ///
+    /// # Overriding the default configuration
+    ///
+    /// If you want to deviate from the default configuration, it's enough to specify the fields you
+    /// want to override.
+    ///
+    /// ## Example: Disable TLS 1.2
+    ///
+    /// ```yaml
+    #[doc = include_str!("../../../tests/fixtures/tls_config/disable_tls_1_2.yaml")]
+    /// ```
+    ///
+    /// ## Example: Trust additional root certificates
+    ///
+    /// ```yaml
+    #[doc = include_str!("../../../tests/fixtures/tls_config/additional_roots.yaml")]
+    /// ```
+    ///
+    /// ## Example: Disable certificate verification
+    ///
+    /// ```yaml
+    #[doc = include_str!("../../../tests/fixtures/tls_config/skip_verification.yaml")]
+    /// ```
+    #[non_exhaustive]
+    pub struct TlsClientPolicyConfig {
+        /// The cryptographic stack used to secure the connection.
+        ///
+        /// Refer to the documentation for [`CryptoProviderConfig`](CryptoProviderConfig)
+        /// for more details.
+        #[serde(default)]
+        #[serde(with = "serde_yaml::with::singleton_map_recursive")]
+        pub crypto_provider: CryptoProviderConfig,
+        /// Which TLS versions are allowed.
+        ///
+        /// Refer to the documentation for [`AllowedTlsVersionsConfig`](AllowedTlsVersionsConfig)
+        /// for more details.
+        #[serde(default)]
+        pub allowed_versions: AllowedTlsVersionsConfig,
+        /// The mechanism used to verify server certificates.
+        ///
+        /// Refer to the documentation for [`CertificateVerificationConfig`](CertificateVerificationConfig)
+        /// for more details.
+        #[serde(default)]
+        pub certificate_verification: CertificateVerificationConfig,
+        /// Dangerous configuration options that lower the security
+        /// posture of your client.
+        ///
+        /// These options should never be used in production scenarios.
+        /// They are available for testing/development purposes only.
+        #[serde(default)]
+        pub insecure: InsecureTlsClientConfig,
+    }
+}
+
+#[derive(Debug, Clone, Copy, Deserialize, Serialize)]
+#[non_exhaustive]
+/// Which TLS versions are allowed.
+///
+/// By default, TLS 1.2 and TLS 1.3 are enabled.
+///
+/// # Security
+///
+/// The lack of support for TLS 1.0 and TLS 1.1 is intentional.
+pub struct AllowedTlsVersionsConfig {
+    /// Enables TLS 1.2 if `true`.
+    ///
+    /// It requires the server to support TLS 1.2.
+    #[serde(default = "default_v1_2")]
+    pub v1_2: bool,
+    /// Enables TLS 1.3 if `true`.
+    ///
+    /// It requires the server to support TLS 1.3.
+    #[serde(default = "default_v1_3")]
+    pub v1_3: bool,
+}
+
+fn default_v1_2() -> bool {
+    true
+}
+
+fn default_v1_3() -> bool {
+    true
+}
+
+impl Default for AllowedTlsVersionsConfig {
+    fn default() -> Self {
+        Self {
+            v1_2: default_v1_2(),
+            v1_3: default_v1_3(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[non_exhaustive]
+/// Configure how server certificates are verified.
+///
+/// # Default
+///
+/// By default, we rely on verification machinery of the underlying operating system.
+/// Refer to the documentation for [`rustls-platform-verifier`](https://docs.rs/rustls-platform-verifier/latest/rustls_platform_verifier/)
+/// for more information on how each platform handles certificate verification.
+///
+/// # Customization
+///
+/// Set [`additional_roots`][`CertificateVerificationConfig::additional_roots`] to trust
+/// additional root certificates in addition to the ones already trusted
+/// by the operating system.
+///
+/// # Skipping Verification
+///
+/// If you want to skip certificate verification altogether, check out the [`insecure`][`super::TlsClientPolicyConfig::insecure`]
+/// options in [`TlsClientPolicyConfig`][`super::TlsClientPolicyConfig`].
+///
+/// ## Incorrect Usage
+///
+/// Setting [`use_os_verifier`][`CertificateVerificationConfig::use_os_verifier`] to `false`, with
+/// no [`additional_roots`][`CertificateVerificationConfig::additional_roots`] specified, does **not**
+/// disable certificate verification. It does instead cause all certificate verification attempts to fail.
+///
+/// We treat this scenario as a misconfiguration and return an error at runtime, when
+/// trying to initialize the client.
+pub struct CertificateVerificationConfig {
+    /// Whether to use the certificate verification machinery provided by
+    /// the underlying operating system.
+    ///
+    /// Defaults to `true`.
+    #[serde(default = "default_use_os_verifier")]
+    pub use_os_verifier: bool,
+    /// Trust one or more additional root certificates.
+    ///
+    /// If [`use_os_verifier`][`CertificateVerificationConfig::use_os_verifier`] is `false`,
+    /// these will be the only trusted root certificates.
+    /// If [`use_os_verifier`][`CertificateVerificationConfig::use_os_verifier`] is `true`, these will be
+    /// trusted **in addition** to the ones already trusted by the underlying operating system.
+    ///
+    /// They can either be loaded from files or inlined in configuration.
+    #[serde(default)]
+    #[serde(with = "serde_yaml::with::singleton_map_recursive")]
+    pub additional_roots: Vec<RootCertificate>,
+}
+
+fn default_use_os_verifier() -> bool {
+    true
+}
+
+impl Default for CertificateVerificationConfig {
+    fn default() -> Self {
+        CertificateVerificationConfig {
+            use_os_verifier: default_use_os_verifier(),
+            additional_roots: Default::default(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+#[non_exhaustive]
+/// [Additional root certificates](`CertificateVerificationConfig::additional_roots`) to be trusted.
+pub enum RootCertificate {
+    /// Retrieve the root certificate from a file.
+    File {
+        /// How to decode the root certificate inside the file.
+        encoding: RootCertificateFileEncoding,
+        /// The path to the root certificate file.
+        path: PathBuf,
+    },
+    /// A root certificate that's inlined inside the provided configuration.
+    Inline {
+        /// How to decode the root certificate.
+        encoding: RootCertificateInlineEncoding,
+        /// The root certificate data.
+        data: String,
+    },
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+#[non_exhaustive]
+/// Supported encodings for the root certificate in [`RootCertificate::File`].
+pub enum RootCertificateFileEncoding {
+    /// A DER-encoded X.509 certificate; as specified in [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1).
+    Der,
+    /// A PEM-encoded X.509 certificate; as specified in [RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468#section-5).
+    Pem,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+#[non_exhaustive]
+/// Supported encodings for the root certificate in [`RootCertificate::Inline`].
+pub enum RootCertificateInlineEncoding {
+    /// A DER-encoded X.509 certificate; as specified in [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1).
+    ///
+    /// Since DER is a binary format, we expect the data to be [base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
+    Base64Der,
+    /// A PEM-encoded X.509 certificate; as specified in [RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468#section-5).
+    ///
+    /// Since PEM is a text format, we don't expect the data to be base64-encoded.
+    Pem,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[non_exhaustive]
+/// Dangerous configuration options to lower the security posture of a TLS client.
+pub struct InsecureTlsClientConfig {
+    /// Don't verify server certificates.
+    ///
+    /// Extremely dangerous option, limit its usage to local development environments.
+    #[serde(default = "default_skip_verification")]
+    pub skip_verification: bool,
+}
+
+impl Default for InsecureTlsClientConfig {
+    fn default() -> Self {
+        InsecureTlsClientConfig {
+            skip_verification: default_skip_verification(),
+        }
+    }
+}
+
+fn default_skip_verification() -> bool {
+    false
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case", tag = "name")]
+#[non_exhaustive]
+/// Which implementation to use for TLS cryptographic operations.
+pub enum CryptoProviderConfig {
+    /// Use [`aws-lc-rs`](https://docs.rs/aws-lc-rs/) for cryptographic operations.
+    AwsLcRs {
+        #[serde(default)]
+        /// Whether to require FIPS compliance.
+        ///
+        /// # Additional constraints
+        ///
+        /// FIPS mode is not supported on all platforms.
+        /// Furthermore, `aws-lc-rs` requires additional system dependencies at build time.
+        /// Check out their [documentation](https://docs.rs/aws-lc-rs/latest/aws_lc_rs/#fips) for
+        /// more information.
+        require_fips: bool,
+    },
+    /// Use [`ring`](https://docs.rs/ring/) for cryptographic operations.
+    Ring,
+}
+
+impl Default for CryptoProviderConfig {
+    fn default() -> Self {
+        CryptoProviderConfig::AwsLcRs {
+            require_fips: false,
+        }
+    }
+}

libs/pavex/src/tls/client/config.rs

@@ -0,0 +1,9 @@
+//! Secure your client connections with TLS (Transport Layer Security).
+//!
+//! Check out the documentation for [`TlsClientPolicyConfig`] for
+//! a detailed explanation of the available configuration options.
+pub mod config;
+pub use config::_config::TlsClientPolicyConfig;
+
+#[cfg(feature = "rustls_0_23")]
+mod rustls_0_23;