chore(tls): add examples for root and self-signed certificates (#792)

Author: 0x676e67

Cargo.toml

@@ -245,8 +245,8 @@ path = "examples/emulation_twitter.rs"
 required-features = ["full", "tracing"]
 
 [[example]]
-name = "set_cert_store"
-path = "examples/set_cert_store.rs"
+name = "cert_store"
+path = "examples/cert_store.rs"
 required-features = ["webpki-roots", "tracing"]
 
 [[example]]

examples/cert_store.rs

@@ -0,0 +1,81 @@
+use std::time::Duration;
+
+use wreq::{
+    Client,
+    tls::{CertStore, TlsInfo},
+};
+
+/// Certificate Store Example
+///
+/// In most cases, you don't need to manually configure certificate stores. wreq automatically
+/// uses appropriate default certificates:
+/// - With `webpki-roots` feature enabled: Uses Mozilla's maintained root certificate collection
+/// - Without this feature: Uses system default certificate store paths
+///
+/// Manual certificate store configuration is only needed in the following special cases:
+///
+/// ## Scenarios requiring custom certificate store:
+///
+/// ### 1. Self-signed Certificates
+/// - Connect to internal services using self-signed certificates
+/// - Test servers in development environments
+///
+/// ### 2. Enterprise Internal CA
+/// - Add root certificates from enterprise internal certificate authorities
+/// - Access HTTPS services on corporate intranets
+///
+/// ### 3. Certificate Updates and Management
+/// - Dynamically update certificates in the certificate store
+/// - Remove revoked or expired certificates
+///
+/// ### 4. Compliance Requirements
+/// - Special compliance requirements for certain industries or regions
+/// - Need to use specific certificate collections
+///
+/// ### 5. Performance Optimization
+/// - Reduce certificate store size to improve TLS handshake performance
+/// - Include only necessary root certificates
+#[tokio::main]
+async fn main() -> wreq::Result<()> {
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::INFO)
+        .init();
+
+    // Create a client with a custom certificate store using webpki-roots
+    let client = Client::builder()
+        .cert_store(CertStore::from_der_certs(
+            webpki_root_certs::TLS_SERVER_ROOT_CERTS,
+        )?)
+        .build()?;
+
+    // Use the API you're already familiar with
+    client.get("https://www.google.com").send().await?;
+
+    // Self-signed certificate Client
+    // Skip certificate verification for self-signed certificates
+    let client = Client::builder()
+        .tls_info(true)
+        .cert_verification(false)
+        .build()?;
+
+    // Use the API you're already familiar with
+    let resp = client.get("https://self-signed.badssl.com/").send().await?;
+    if let Some(val) = resp.extensions().get::<TlsInfo>() {
+        if let Some(peer_cert_der) = val.peer_certificate() {
+            // Create self-signed certificate Store
+            let self_signed_store = CertStore::from_der_certs(&[peer_cert_der])?;
+
+            // Create a client with self-signed certificate store
+            let client = Client::builder()
+                .cert_store(self_signed_store)
+                .connect_timeout(Duration::from_secs(10))
+                .build()?;
+
+            // Use the API you're already familiar with
+            let resp = client.get("https://self-signed.badssl.com/").send().await?;
+            println!("{}", resp.text().await?);
+        }
+    }
+
+    Ok(())
+}

examples/emulation_twitter.rs

@@ -85,7 +85,6 @@ async fn main() -> wreq::Result<()> {
         headers
     };
 
-    // Original headers
     // The headers keep the original case and order
     let original_headers = {
         let mut original_headers = OriginalHeaders::new();

examples/set_cert_store.rs

@@ -64,10 +64,7 @@ use crate::{
     error::{self, BoxError, Error},
     proxy::Matcher as ProxyMatcher,
     redirect::{self, RedirectPolicy},
-    tls::{
-        AlpnProtocol, CertStore, CertificateInput, Identity, KeyLogPolicy, TlsConnectorBuilder,
-        TlsVersion,
-    },
+    tls::{AlpnProtocol, CertStore, Identity, KeyLogPolicy, TlsConnectorBuilder, TlsVersion},
 };
 
 /// An `Client` to make Requests with.
@@ -1028,33 +1025,6 @@ impl ClientBuilder {
         self
     }
 
-    // TLS options
-
-    /// Configures SSL/TLS certificate pinning for the client.
-    ///
-    /// This method allows you to specify a set of PEM-encoded certificates that the client
-    /// will pin to, ensuring that only these certificates are trusted during SSL/TLS connections.
-    /// This provides an additional layer of security by preventing man-in-the-middle (MITM)
-    /// attacks, even if a malicious certificate is issued by a trusted Certificate Authority
-    /// (CA).
-    ///
-    /// # Parameters
-    ///
-    /// - `certs`: An iterator of DER-encoded certificates. Each certificate should be provided as a
-    ///   byte slice (`&[u8]`).
-    #[inline]
-    pub fn ssl_pinning<'c, I>(mut self, certs: I) -> ClientBuilder
-    where
-        I: IntoIterator,
-        I::Item: Into<CertificateInput<'c>>,
-    {
-        match CertStore::from_der_certs(certs) {
-            Ok(store) => self.config.tls_cert_store = store,
-            Err(err) => self.config.error = Some(err),
-        }
-        self
-    }
-
     /// Sets the identity to be used for client certificate authentication.
     #[inline]
     pub fn identity(mut self, identity: Identity) -> ClientBuilder {

examples/tls_info.rs

@@ -19,7 +19,7 @@ pub use self::{
     types::{
         AlpnProtocol, AlpsProtocol, CertificateCompressionAlgorithm, ExtensionType, TlsVersion,
     },
-    x509::{CertStore, CertStoreBuilder, Certificate, CertificateInput, Identity},
+    x509::{CertStore, CertStoreBuilder, Certificate, Identity},
 };
 
 /// Http extension carrying extra TLS layer information.

src/client/http/mod.rs

@@ -2,7 +2,7 @@ use std::time::Duration;
 
 use wreq::{
     Client,
-    tls::{AlpsProtocol, TlsInfo, TlsOptions, TlsVersion},
+    tls::{AlpsProtocol, CertStore, TlsInfo, TlsOptions, TlsVersion},
 };
 
 macro_rules! join {
@@ -186,7 +186,7 @@ async fn test_aes_hw_override() -> wreq::Result<()> {
 }
 
 #[tokio::test]
-async fn test_ssl_pinning() {
+async fn test_tls_self_signed_cert() {
     let client = wreq::Client::builder()
         .cert_verification(false)
         .connect_timeout(Duration::from_secs(360))
@@ -206,8 +206,13 @@ async fn test_ssl_pinning() {
         .and_then(|info| info.peer_certificate())
         .unwrap();
 
+    let self_signed_cert_store = CertStore::builder()
+        .add_der_cert(peer_cert_der)
+        .build()
+        .unwrap();
+
     let client = wreq::Client::builder()
-        .ssl_pinning([peer_cert_der])
+        .cert_store(self_signed_cert_store)
         .build()
         .unwrap();