Add opt-in TCPConnector(use_truststore=True) for OS-native trust store integration (#11705)

.mypy.ini

@@ -36,3 +36,6 @@ ignore_missing_imports = True
 
 [mypy-gunicorn.*]
 ignore_missing_imports = True
+
+[mypy-truststore]
+ignore_missing_imports = True

CHANGES/11705.feature.rst

@@ -0,0 +1 @@
+*aiohttp* now prefers the `truststore <https://truststore.readthedocs.io/>`_ library for TLS certificate verification when the optional dependency is installed, with automatic fallback to the stdlib :mod:`ssl` defaults otherwise. This resolves common ``CERTIFICATE_VERIFY_FAILED`` errors for users behind enterprise TLS-intercepting proxies whose root CA lives in the macOS Keychain or Windows certificate stores. Install the optional dependency with ``pip install aiohttp[truststore]`` -- by :user:`Krishnachaitanyakc`.

CONTRIBUTORS.txt

@@ -234,6 +234,7 @@ Kirill Malovitsa
 Kirill Potapenko
 Konstantin Shutkin
 Konstantin Valetov
+Krishnachaitanya Balusu
 Krzysztof Blazewicz
 Kyrylo Perevozchikov
 Kyungmin Lee

aiohttp/connector.py

@@ -64,6 +64,13 @@
     ssl = None  # type: ignore[assignment]
     SSLContext = object  # type: ignore[misc,assignment]
 
+try:
+    import truststore
+
+    HAS_TRUSTSTORE = True
+except ImportError:
+    HAS_TRUSTSTORE = False
+
 EMPTY_SCHEMA_SET = frozenset({""})
 HTTP_SCHEMA_SET = frozenset({"http", "https"})
 WS_SCHEMA_SET = frozenset({"ws", "wss"})
@@ -846,12 +853,22 @@ def _make_ssl_context(verified: bool) -> SSLContext:
 
     This method is not async-friendly and should be called from a thread
     because it will load certificates from disk and do other blocking I/O.
+
+    When the optional ``truststore`` library is importable and ``verified``
+    is ``True``, the returned context is a :class:`truststore.SSLContext`,
+    which delegates certificate verification to the operating system's
+    native trust store (macOS Keychain, Windows certificate stores, OpenSSL
+    default paths on Linux). Otherwise the stdlib default context is used.
     """
     if ssl is None:
         # No ssl support
         return None  # type: ignore[unreachable]
+    sslcontext: SSLContext
     if verified:
-        sslcontext = ssl.create_default_context()
+        if HAS_TRUSTSTORE:
+            sslcontext = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        else:
+            sslcontext = ssl.create_default_context()
     else:
         sslcontext = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
         sslcontext.options |= ssl.OP_NO_SSLv2
@@ -868,6 +885,8 @@ def _make_ssl_context(verified: bool) -> SSLContext:
 # since they do blocking I/O to load certificates from disk,
 # and imports should always be done before the event loop starts
 # or in a thread.
+# _SSL_CONTEXT_VERIFIED is frozen at module import; tests that toggle
+# HAS_TRUSTSTORE must call _make_ssl_context(True) fresh, not inspect this.
 _SSL_CONTEXT_VERIFIED = _make_ssl_context(True)
 _SSL_CONTEXT_UNVERIFIED = _make_ssl_context(False)
 
@@ -909,6 +928,14 @@ class TCPConnector(BaseConnector):
                            notifying the remote peer of connection closure,
                            while avoiding excessive delays during connector cleanup.
                            Note: Only takes effect on Python 3.11+.
+
+    When the optional ``truststore`` library is installed
+    (``pip install aiohttp[truststore]``), the default verified SSL context
+    delegates certificate verification to the operating system's native
+    trust store (macOS Keychain, Windows certificate stores, OpenSSL default
+    paths on Linux). Without the dependency, the stdlib defaults are used.
+    Passing an explicit :class:`ssl.SSLContext` via ``ssl=`` always wins
+    over the default behaviour.
     """
 
     allowed_protocol_schema_set = HIGH_LEVEL_SCHEMA_SET | frozenset({"tcp"})

docs/client_advanced.rst

@@ -641,14 +641,52 @@ If you need to skip both ssl related errors
   except aiohttp.ClientSSLError as e:
       assert isinstance(e, ssl.CertificateError)
 
+Example: Use truststore for system trust stores
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, *aiohttp* relies on :func:`ssl.create_default_context`, which uses
+OpenSSL's bundled certificate paths. On macOS and Windows this set does not
+include certificates that the user, an administrator, or an MDM solution has
+installed into the operating system's native trust store (the macOS Keychain or
+the Windows certificate stores). As a result, requests can fail with
+``CERTIFICATE_VERIFY_FAILED`` in environments where ``curl`` and the system
+browsers succeed -- a common situation behind enterprise TLS-intercepting
+proxies that rely on a locally-installed root CA.
+
+The `truststore <https://truststore.readthedocs.io/>`_ library provides an
+``SSLContext`` that delegates verification to the OS-native APIs. *aiohttp*
+prefers it automatically whenever the library is importable -- there is no
+constructor flag to set::
+
+  pip install aiohttp[truststore]
+
+With the optional dependency installed, the default
+:class:`~aiohttp.TCPConnector` uses :class:`!truststore.SSLContext` for its
+verified SSL context. Without it, the stdlib defaults are used and behaviour
+is unchanged.
+
+To force the stdlib trust paths even when ``truststore`` is installed, pass
+an explicit context built from :func:`ssl.create_default_context`::
+
+  conn = aiohttp.TCPConnector(ssl=ssl.create_default_context())
+  async with aiohttp.ClientSession(connector=conn) as sess:
+      ...
+
+Installing the extra causes the verified default SSL context to be built at
+``import aiohttp`` time via OS trust-store APIs; this is intentional, so any
+blocking I/O happens before the event loop starts, consistent with how the
+stdlib default context has always been built at import time.
+
 Example: Use certifi
 ^^^^^^^^^^^^^^^^^^^^
 
-By default, Python uses the system CA certificates. In rare cases, these may not be
-installed or Python is unable to find them, resulting in a error like
-`ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate`
+In environments where the OpenSSL default certificate paths are missing or
+unreadable, requests can fail with::
+
+  ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
 
-One way to work around this problem is to use the `certifi` package::
+One way to work around this problem is to bundle a known-good certificate
+authority list via the `certifi` package::
 
   ssl_context = ssl.create_default_context(cafile=certifi.where())
   async with ClientSession(connector=TCPConnector(ssl=ssl_context)) as sess:

docs/client_reference.rst

@@ -1278,6 +1278,26 @@ is controlled by *force_close* constructor's parameter).
       *ssl_context* may be used for configuring certification
       authority channel, supported SSL options etc.
 
+   .. note::
+
+      When the optional `truststore <https://truststore.readthedocs.io/>`_
+      library is importable (install it via
+      ``pip install aiohttp[truststore]``), *aiohttp* automatically uses
+      :class:`!truststore.SSLContext` for its default verified SSL context.
+      This delegates certificate verification to the operating system's
+      native trust store (macOS Keychain, Windows certificate stores, OpenSSL
+      default paths on Linux) and fixes ``CERTIFICATE_VERIFY_FAILED`` errors
+      in environments where OS-managed roots -- including those installed by
+      an administrator or an enterprise TLS-intercepting proxy -- are not in
+      OpenSSL's default paths. Without the dependency, the stdlib defaults
+      are used. Passing an explicit :class:`ssl.SSLContext` via ``ssl=``
+      always wins.
+
+      .. versionchanged:: 3.14
+
+         Automatically prefer ``truststore`` when the optional dependency
+         is installed.
+
    :param tuple local_addr: tuple of ``(local_host, local_port)`` used to bind
       socket locally if specified.
 

docs/spelling_wordlist.txt

@@ -12,6 +12,7 @@ al
 alives
 api
 api’s
+APIs
 app
 app’s
 apps
@@ -155,6 +156,7 @@ httpretty
 https
 hostname
 impl
+importable
 incapsulates
 Indices
 infos
@@ -181,6 +183,7 @@ keepalive
 keepalived
 keepalives
 keepaliving
+Keychain
 kib
 KiB
 kwarg
@@ -196,8 +199,10 @@ lookup
 lookups
 lossless
 lowercased
+macOS
 Mako
 manylinux
+MDM
 metadata
 MiB
 microservice
@@ -233,6 +238,7 @@ normalizer
 nowait
 OAuth
 Online
+OpenSSL
 optimizations
 orjson
 os
@@ -325,6 +331,7 @@ ssl
 SSLContext
 startup
 stateful
+stdlib
 storages
 subapplication
 subclassed
@@ -358,6 +365,7 @@ toolbar
 toplevel
 towncrier
 tp
+truststore
 tuples
 UI
 un

pyproject.toml

@@ -53,6 +53,9 @@ speedups = [
   "brotlicffi >= 1.2; platform_python_implementation != 'CPython'",
   "backports.zstd; platform_python_implementation == 'CPython' and python_version < '3.14' and sys_platform != 'android' and sys_platform != 'ios'",
 ]
+truststore = [
+  "truststore >= 0.10",
+]
 
 [[project.maintainers]]
 name = "aiohttp team"

requirements/lint.in

@@ -13,6 +13,7 @@ pytest_codspeed
 python-on-whales
 slotscheck
 trustme
+truststore; implementation_name == "cpython"
 uvloop; platform_system != "Windows"
 valkey
 zlib_ng

requirements/lint.txt

@@ -144,6 +144,8 @@ tomli==2.4.1
     #   slotscheck
 trustme==1.2.1
     # via -r requirements/lint.in
+truststore==0.10.4 ; implementation_name == "cpython"
+    # via -r requirements/lint.in
 typing-extensions==4.15.0
     # via
     #   aiosignal

requirements/test-common.in

@@ -8,4 +8,5 @@ pytest-xdist
 pytest_codspeed
 python-on-whales
 trustme; platform_machine != "i686" # no 32-bit wheels
+truststore; implementation_name == "cpython"
 zlib_ng

tests/conftest.py

@@ -101,6 +101,14 @@ def blockbuster(request: pytest.FixtureRequest) -> Iterator[None]:
             bb.functions[func].can_block_in(
                 "aiohttp/web_urldispatcher.py", "add_static"
             )
+        # truststore's _configure_context probes well-known CA file/dir
+        # locations on every wrap_socket call; on Linux this is a no-op
+        # versus stdlib but blockbuster flags the os.path.is* probes.
+        for func, fn_names in (
+            ("os.stat", ("_configure_context", "_capath_contains_certs")),
+            ("os.listdir", ("_capath_contains_certs",)),
+        ):
+            bb.functions[func].can_block_in("truststore/_openssl.py", fn_names)
         # Note: coverage.py uses locking internally which can cause false positives
         # in blockbuster when it instruments code. This is particularly problematic
         # on Windows where it can lead to flaky test failures.

tests/test_truststore.py

@@ -0,0 +1,114 @@
+"""Tests for automatic ``truststore`` preference on :class:`TCPConnector`.
+
+The ``truststore`` library delegates TLS certificate verification to the
+operating system's native trust store. When ``truststore`` is importable,
+``aiohttp.connector`` automatically uses ``truststore.SSLContext`` for its
+default verified context; otherwise it falls back to the stdlib
+``ssl.create_default_context()``. This module covers both branches.
+
+These tests intentionally do not perform live TLS handshakes — they exercise
+the SSL-context construction and dispatch logic only.
+"""
+
+import ssl
+from unittest import mock
+
+import pytest
+
+from aiohttp import TCPConnector, connector as connector_module
+from aiohttp.client_reqrep import Fingerprint
+
+
+def _has_truststore() -> bool:
+    try:
+        import truststore  # type: ignore[import-not-found,unused-ignore]  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def test_has_truststore_matches_importability() -> None:
+    """``HAS_TRUSTSTORE`` reflects whether the library can be imported."""
+    assert connector_module.HAS_TRUSTSTORE is _has_truststore()
+
+
+@pytest.mark.skipif(not _has_truststore(), reason="truststore not installed")
+def test_make_ssl_context_uses_truststore_when_available() -> None:
+    """Verified context is a truststore.SSLContext when the lib is installed."""
+    import truststore  # type: ignore[import-not-found,unused-ignore]
+
+    ctx = connector_module._make_ssl_context(True)
+    assert isinstance(ctx, truststore.SSLContext)
+
+
+def test_make_ssl_context_falls_back_to_stdlib_when_truststore_absent() -> None:
+    """Verified context is a plain ssl.SSLContext when truststore is missing.
+
+    Uses ``type() is`` rather than ``isinstance``: ``truststore.SSLContext``
+    subclasses ``ssl.SSLContext``, so ``isinstance`` would pass in both
+    branches and silently hide a regression here.
+    """
+    with mock.patch.object(connector_module, "HAS_TRUSTSTORE", False):
+        ctx = connector_module._make_ssl_context(True)
+    assert type(ctx) is ssl.SSLContext
+
+
+def test_make_ssl_context_unverified_path_does_not_touch_truststore() -> None:
+    """Unverified context never uses truststore, regardless of HAS_TRUSTSTORE."""
+    with mock.patch.object(connector_module, "HAS_TRUSTSTORE", True):
+        ctx = connector_module._make_ssl_context(False)
+    assert type(ctx) is ssl.SSLContext
+    assert ctx.verify_mode == ssl.CERT_NONE
+
+
+@pytest.mark.skipif(not _has_truststore(), reason="truststore not installed")
+def test_make_ssl_context_verified_with_truststore_sets_alpn() -> None:
+    """``set_alpn_protocols`` works on a truststore-backed context."""
+    ctx = connector_module._make_ssl_context(True)
+    assert isinstance(ctx, ssl.SSLContext)
+
+
+@pytest.mark.skipif(not _has_truststore(), reason="truststore not installed")
+async def test_get_ssl_context_returns_module_level_verified() -> None:
+    """Default verified request returns the module-level ``_SSL_CONTEXT_VERIFIED``."""
+    import truststore  # type: ignore[import-not-found,unused-ignore]
+
+    conn = TCPConnector()
+    try:
+        req = mock.Mock()
+        req.is_ssl.return_value = True
+        req.ssl = True
+        returned = conn._get_ssl_context(req)
+        assert returned is connector_module._SSL_CONTEXT_VERIFIED
+        assert isinstance(returned, truststore.SSLContext)
+    finally:
+        await conn.close()
+
+
+@pytest.mark.skipif(not _has_truststore(), reason="truststore not installed")
+async def test_explicit_ssl_context_overrides_default() -> None:
+    """An explicit ``ssl=<SSLContext>`` argument wins over the default."""
+    explicit_ctx = ssl.create_default_context()
+    conn = TCPConnector(ssl=explicit_ctx)
+    try:
+        req = mock.Mock()
+        req.is_ssl.return_value = True
+        req.ssl = True
+        assert conn._get_ssl_context(req) is explicit_ctx
+    finally:
+        await conn.close()
+
+
+@pytest.mark.skipif(not _has_truststore(), reason="truststore not installed")
+async def test_fingerprint_uses_unverified_context_even_with_truststore() -> None:
+    """A ``Fingerprint`` replaces CA verification; truststore must not apply."""
+    fingerprint = Fingerprint(b"\x00" * 32)
+    conn = TCPConnector(ssl=fingerprint)
+    try:
+        req = mock.Mock()
+        req.is_ssl.return_value = True
+        req.ssl = True
+        returned = conn._get_ssl_context(req)
+        assert returned is connector_module._SSL_CONTEXT_UNVERIFIED
+    finally:
+        await conn.close()