Trust the OS certificate store on ureq (native-certs), release 1.2.0 (#209)

* feat: add `native-certs` feature for the OS trust store on ureq

The crate-built ureq client verifies against `RootCerts::WebPki` (Mozilla's
bundled roots), which ignores the machine's trust store. Behind a TLS-intercepting
corporate proxy the company CA is installed on the machine and absent from the
bundled set, so every request fails to verify while `curl` and the browsers
succeed. `native-certs` moves the per-call agent to `RootCerts::PlatformVerifier`
and turns on `ureq/platform-verifier`, which the rustls lane panics without.

Off by default: widening a self-updater's trust store is opt-in. No effect on
reqwest, whose rustls setup already uses `rustls-platform-verifier`, or on an
injected `ureq::Agent`, which owns its own TLS config.

* docs: note that `native-certs` is a no-op without the ureq client

* release 1.2.0

Author: jaemk

CHANGELOG.md

@@ -8,6 +8,22 @@
 
 ### Removed
 
+## [1.2.0]
+Additive over `1.1.0`: one opt-in feature for the ureq client's trust store. No API breaks, no
+migration needed.
+
+### Added
+- `native-certs` feature: the crate-built ureq client verifies against the OS trust store
+  (`RootCerts::PlatformVerifier`) instead of Mozilla's bundled roots (`RootCerts::WebPki`). Needed
+  behind a TLS-intercepting corporate proxy, whose CA is installed on the machine and is absent from
+  the bundled set, so every request otherwise fails to verify. Off by default, so the ureq client's
+  trust store is unchanged unless asked for. No effect on reqwest (its rustls setup already uses
+  `rustls-platform-verifier`) or on an injected `ureq::Agent`, which owns its own TLS config.
+
+### Changed
+
+### Removed
+
 ## [1.1.0]
 Additive over `1.0.0`: two verification entry points for releases the built-in gates do not cover.
 No API breaks, no migration needed.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "self_update"
-version = "1.1.0"
+version = "1.2.0"
 description = "Self updates for standalone executables"
 repository = "https://github.com/jaemk/self_update"
 keywords = ["update", "upgrade", "download", "release"]
@@ -110,6 +110,17 @@ native-tls = ["reqwest?/native-tls", "ureq?/native-tls"]
 # the reqwest client; a ureq-only build gets `native-tls` (system OpenSSL) without vendoring.
 native-tls-vendored = ["native-tls", "reqwest?/native-tls-vendored"]
 rustls = ["reqwest?/rustls", "ureq?/rustls"]
+# Trust the OS certificate store instead of Mozilla's bundled roots, for the ureq client.
+# Turn it on when your users sit behind a TLS-intercepting corporate proxy whose CA is installed
+# in the machine's trust store: without it, every request fails to verify. It moves the ureq
+# per-call agent from `RootCerts::WebPki` to `RootCerts::PlatformVerifier`; no effect on an
+# injected `ureq::Agent`, which owns its own TLS config.
+#
+# A reqwest build needs nothing and is unaffected: reqwest 0.13's rustls setup already verifies
+# through `rustls-platform-verifier`, and its native-tls setup uses the system store by
+# definition. The `ureq?/` prefix means this feature is a no-op there, pulling in nothing.
+# See CORP-2 in specs/corporate-network-config.md.
+native-certs = ["ureq?/platform-verifier"]
 
 reqwest = ["dep:reqwest"]
 ureq = ["dep:ureq"]

README.md

@@ -855,5 +855,27 @@ export SSL_CERT_DIR=/etc/ssl/certs
 Alternatively build with the `rustls` feature, which uses a bundled root store and does not depend
 on the system OpenSSL cert layout.
 
+**TLS certificate errors behind a corporate proxy (`ureq` + `rustls`).** Many company networks
+terminate outbound HTTPS at an intercepting proxy that re-signs traffic with an internal CA. That CA
+is installed in the machine's trust store, so `curl` and the system browsers accept it, but the
+ureq client's default root store is `RootCerts::WebPki` (Mozilla's bundled roots), which ignores the
+machine entirely, so every request fails to verify. Enable the `native-certs` feature to move the
+ureq client onto the OS trust store instead:
+
+```toml
+self_update = { version = "1.2", features = ["ureq", "rustls", "native-certs"] }
+```
+
+The reqwest client needs nothing and is not affected by the feature: its rustls setup already
+verifies through `rustls-platform-verifier`, and its native-tls setup uses the system store by
+definition. On a reqwest-only build `native-certs` is a no-op that pulls in no extra dependency, so
+it is safe to enable unconditionally in a crate that offers both clients.
+`native-certs` has no effect on an injected `ureq::Agent` either, since that agent owns its own TLS
+config, so set `RootCerts::PlatformVerifier` on it yourself. On Linux the OS trust store honors
+`SSL_CERT_FILE` / `SSL_CERT_DIR`, so those env vars work as an escape hatch once the feature is on.
+To trust exactly one internal CA and nothing else, skip the feature and pass the certificate to
+[`add_root_certificate`](crate::backends::github::UpdateBuilder::add_root_certificate). Note that on
+a ureq build that *replaces* the trust store rather than adding to it.
+
 
 License: MIT

specs/README.md

@@ -48,7 +48,7 @@ design before it can be built). Keep each row's status current with `spec.py set
 | Releases Test Constructor | done | [releases-test-constructor.md](releases-test-constructor.md) |
 | Choose Latest Release Sort | done | [choose-latest-release-sort.md](choose-latest-release-sort.md) |
 | Embedded Key Verification | done | [embedded-key-verification.md](embedded-key-verification.md) |
-| Corporate Network Config | pending | [corporate-network-config.md](corporate-network-config.md) |
+| Corporate Network Config | partial | [corporate-network-config.md](corporate-network-config.md) |
 | Restart After Update | done | [ref-restart.md](ref-restart.md) |
 | Update-check Interval Guard | done | [ref-check-interval.md](ref-check-interval.md) |
 | Manifest Backend | done | [ref-manifest-backend.md](ref-manifest-backend.md) |

specs/corporate-network-config.md

@@ -1,6 +1,6 @@
 # Corporate Network Config
 
-Status: CORP-1 done; CORP-2 and CORP-3 pending
+Status: CORP-1 and CORP-2 done; CORP-3 pending
 
 ## Problem
 
@@ -10,24 +10,25 @@ its own root store and does not read the OS trust store, so any connection throu
 proxy fails with a certificate verification error unless the caller injects a
 pre-configured `reqwest` client with the custom CA added manually.
 
-CORP-1 has shipped; CORP-2 and CORP-3 remain open:
+CORP-1 and CORP-2 have shipped; CORP-3 remains open:
 
 - **Custom root CA (CORP-1)**: shipped. `self_update::Certificate` plus
   `add_root_certificate` on every builder and on `Download`; a malformed
   certificate surfaces as `Error::InvalidCertificate` from `build()` /
   `download_to`. See CORP-1 below and `ref-http-client.md`.
 
-- **OS trust store (CORP-2)**: the default reqwest + rustls setup in 0.13.4 already uses
-  the platform verifier (OS trust store) via `rustls-platform-verifier`. The gap is the
-  ureq per-call path, which defaults to Mozilla's bundled roots (`WebPki`), not the OS.
+- **OS trust store (CORP-2)**: shipped in 1.2.0 as the opt-in `native-certs` feature. The
+  default reqwest + rustls setup in 0.13.4 already used the platform verifier (OS trust
+  store) via `rustls-platform-verifier`; the gap was the ureq per-call path, which defaults
+  to Mozilla's bundled roots (`WebPki`) and so ignores the machine's trust store entirely.
 
 - **Proxy with auth (CORP-3)**: env-var passthrough (`HTTP_PROXY` / `HTTPS_PROXY`) works
   for unauthenticated proxies, but any proxy requiring credentials must be configured on
   an injected client. There is no `.proxy(url)` setter on the builders.
 
-The remaining gaps (CORP-2, CORP-3) force corporate users to add `reqwest` or `ureq` as
-a direct dependency solely to unlock transport config that belongs on the `self_update`
-builder surface.
+The remaining gap (CORP-3) forces corporate users to add `reqwest` or `ureq` as a direct
+dependency solely to unlock transport config that belongs on the `self_update` builder
+surface.
 
 ---
 
@@ -128,7 +129,7 @@ ureq build-time client        -- #[cfg(all(feature = "ureq", not(feature = "reqw
 
 ---
 
-## CORP-2: OS trust store for ureq (designed)
+## CORP-2: OS trust store for ureq (done)
 
 ### reqwest: already solved
 
@@ -178,6 +179,22 @@ CORP-2-7. When both `reqwest` and `ureq` features are on, the ureq per-call path
 reached; `native-certs` is effectively a no-op (no overhead). This is acceptable since
 the common default-feature path uses reqwest with the platform verifier already.
 
+CORP-2-8. `native-certs` is a no-op on a build with no `ureq` feature, and pulls in no
+dependency there: the mapping is `ureq?/platform-verifier`, and the `?` prefix activates
+`platform-verifier` only when `ureq` is itself enabled. Enabling `native-certs`
+unconditionally is therefore safe for a downstream crate that offers both clients. Nothing
+is needed on the reqwest side for either TLS backend: rustls verifies through
+`rustls-platform-verifier` (CORP-2-1), and native-tls uses the system store by definition.
+
+CORP-2-9. The reqwest rustls lane reaches the platform verifier only while `root_certs` is
+empty and `tls_certs_only` was never set (reqwest 0.13.4 `async_impl/client.rs`; the
+blocking client wraps the same builder, so both APIs behave alike). Neither condition is
+reachable by accident from this crate: `tls_certs_only` is never called, and
+`tls_certs_merge` is invoked with the collected `add_root_certificate` certs, which extends
+an empty vec with nothing when the caller supplied none. A caller who DOES supply
+certificates moves to `Verifier::new_with_extra_roots`, which keeps the OS trust store and
+adds theirs (CORP-1-12), rather than the ureq lane's replace semantics (CORP-1-15).
+
 ---
 
 ## CORP-3: proxy with auth (designed)

src/http_client/ureq.rs

@@ -42,8 +42,34 @@ impl From<Agent> for UreqClient {
     }
 }
 
+/// The trust store a crate-built ureq agent starts from, before any caller-supplied certificates
+/// replace it (CORP-2-4).
+///
+/// ureq's own default is [`RootCerts::WebPki`](ureq::tls::RootCerts::WebPki) -- Mozilla's bundled
+/// roots, which ignore the machine's trust store entirely. That is the safer default for a
+/// self-updater (it cannot be widened by anything installed on the host), so it stays the default
+/// here. The `native-certs` feature opts into
+/// [`PlatformVerifier`](ureq::tls::RootCerts::PlatformVerifier) instead, which is what a caller
+/// behind a TLS-intercepting corporate proxy needs: the company CA lives in the OS store, not in
+/// Mozilla's list.
+///
+/// Note the rustls lane *panics* on `PlatformVerifier` without ureq's `platform-verifier` feature
+/// (`ureq::tls::rustls`), which is exactly what `native-certs = ["ureq?/platform-verifier"]`
+/// guarantees -- so the two must stay wired together.
+fn default_root_certs() -> ureq::tls::RootCerts {
+    #[cfg(feature = "native-certs")]
+    {
+        ureq::tls::RootCerts::PlatformVerifier
+    }
+    #[cfg(not(feature = "native-certs"))]
+    {
+        ureq::tls::RootCerts::WebPki
+    }
+}
+
 /// Build a per-call ureq agent honoring the per-request `timeout`, the TLS feature, and proxy-env.
-/// `root_certs`, when `Some`, replaces the default trust store with the supplied certificates.
+/// `root_certs`, when `Some`, replaces the default trust store (see [`default_root_certs`]) with
+/// the supplied certificates.
 fn build_call_agent(
     timeout: Option<Duration>,
     #[cfg(any(not(feature = "reqwest"), test))] root_certs: Option<UreqRootCerts>,
@@ -57,9 +83,13 @@ fn build_call_agent(
     let provider = TlsProvider::NativeTls;
 
     #[cfg(any(not(feature = "reqwest"), test))]
-    let mut tls = TlsConfig::builder().provider(provider);
+    let mut tls = TlsConfig::builder()
+        .provider(provider)
+        .root_certs(default_root_certs());
     #[cfg(all(feature = "reqwest", not(test)))]
-    let tls = TlsConfig::builder().provider(provider);
+    let tls = TlsConfig::builder()
+        .provider(provider)
+        .root_certs(default_root_certs());
     #[cfg(any(not(feature = "reqwest"), test))]
     if let Some(certs) = root_certs {
         tls = tls.root_certs(ureq::tls::RootCerts::Specific(certs));
@@ -560,6 +590,44 @@ mod tests {
         );
     }
 
+    // spec: CORP-2-4
+    #[test]
+    fn default_trust_store_follows_the_native_certs_feature() {
+        // The whole point of `native-certs`: a crate-built agent must consult the OS trust store
+        // rather than Mozilla's bundled roots, because a corporate MITM proxy's CA is only ever in
+        // the former. Without the feature the WebPki default must be preserved exactly -- widening
+        // the trust store of a self-updater is not something a minor release gets to do silently.
+        let agent = build_call_agent(None, None);
+        let roots = agent.config().tls_config().root_certs();
+        #[cfg(feature = "native-certs")]
+        assert!(
+            matches!(roots, ureq::tls::RootCerts::PlatformVerifier),
+            "with `native-certs` the per-call agent must use the OS trust store, got {roots:?}"
+        );
+        #[cfg(not(feature = "native-certs"))]
+        assert!(
+            matches!(roots, ureq::tls::RootCerts::WebPki),
+            "without `native-certs` the per-call agent must keep ureq's WebPki roots, got {roots:?}"
+        );
+    }
+
+    // spec: CORP-1-14, CORP-1-15, CORP-2-4
+    #[test]
+    fn caller_supplied_certs_replace_the_default_trust_store() {
+        // CORP-1-15's documented limitation, pinned against the CORP-2 change: adding the default
+        // `root_certs` call must not turn `Specific` into a merge, and must not let the default
+        // win over an explicit cert. `Specific` still fully replaces whatever the default was.
+        let certs = std::sync::Arc::new(vec![
+            ureq::tls::Certificate::from_der(b"der-bytes").to_owned(),
+        ]);
+        let agent = build_call_agent(None, Some(certs));
+        let roots = agent.config().tls_config().root_certs();
+        assert!(
+            matches!(roots, ureq::tls::RootCerts::Specific(_)),
+            "caller-supplied roots must replace the default trust store, got {roots:?}"
+        );
+    }
+
     #[test]
     fn injected_agent_no_status_error_falls_through_to_is_success_check() {
         // 404 must still map to NotFound via the bottom-of-`get` is_success() path (the

src/lib.rs

@@ -873,6 +873,28 @@ export SSL_CERT_DIR=/etc/ssl/certs
 Alternatively build with the `rustls` feature, which uses a bundled root store and does not depend
 on the system OpenSSL cert layout.
 
+**TLS certificate errors behind a corporate proxy (`ureq` + `rustls`).** Many company networks
+terminate outbound HTTPS at an intercepting proxy that re-signs traffic with an internal CA. That CA
+is installed in the machine's trust store, so `curl` and the system browsers accept it, but the
+ureq client's default root store is `RootCerts::WebPki` (Mozilla's bundled roots), which ignores the
+machine entirely, so every request fails to verify. Enable the `native-certs` feature to move the
+ureq client onto the OS trust store instead:
+
+```toml
+self_update = { version = "1.2", features = ["ureq", "rustls", "native-certs"] }
+```
+
+The reqwest client needs nothing and is not affected by the feature: its rustls setup already
+verifies through `rustls-platform-verifier`, and its native-tls setup uses the system store by
+definition. On a reqwest-only build `native-certs` is a no-op that pulls in no extra dependency, so
+it is safe to enable unconditionally in a crate that offers both clients.
+`native-certs` has no effect on an injected `ureq::Agent` either, since that agent owns its own TLS
+config, so set `RootCerts::PlatformVerifier` on it yourself. On Linux the OS trust store honors
+`SSL_CERT_FILE` / `SSL_CERT_DIR`, so those env vars work as an escape hatch once the feature is on.
+To trust exactly one internal CA and nothing else, skip the feature and pass the certificate to
+[`add_root_certificate`](crate::backends::github::UpdateBuilder::add_root_certificate). Note that on
+a ureq build that *replaces* the trust store rather than adding to it.
+
 */
 
 // Enable the `doc_cfg` feature on docs.rs (nightly-only, guarded by the `docsrs` cfg set via

src/macros.rs

@@ -158,10 +158,12 @@ macro_rules! request_config_setters {
         /// certificate is surfaced at connection time instead.
         ///
         /// **ureq-only builds**: when the `reqwest` feature is disabled, the crate-built ureq client
-        /// trusts *only* the supplied certificates (replacing the default Mozilla root set). Supply
-        /// all CA certificates you need, including any public roots. If you need the Mozilla set plus
-        /// a custom CA, inject a pre-built `ureq::Agent` via [`ureq_agent`](Self::ureq_agent)
-        /// configured with `RootCerts::PlatformVerifier` or a merged root set instead.
+        /// trusts *only* the supplied certificates (replacing whatever the default root set was).
+        /// Supply all CA certificates you need, including any public roots. If what you actually
+        /// want is the machine's own trust store -- the usual case behind an intercepting corporate
+        /// proxy, whose CA is already installed there -- enable the `native-certs` feature and do
+        /// not call this setter at all. For anything finer, inject a pre-built `ureq::Agent` via
+        /// [`ureq_agent`](Self::ureq_agent) carrying its own merged root set.
         pub fn add_root_certificate(&mut self, cert: crate::Certificate) -> &mut Self {
             self.$($path).+.root_certificates.push(cert);
             self