Merge pull request #11151 from sethmlarson/truststore-user-guide

Add section on 'truststore' feature to User Guide

docs/html/user_guide.rst

@@ -1137,3 +1137,80 @@ announcements on the `low-traffic packaging announcements list`_ and
 .. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform
 .. _the official Python blog: https://blog.python.org/
 .. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher
+
+Using system trust stores for verifying HTTPS
+=============================================
+
+pip 22.2 added **experimental** support for using system trust stores to verify HTTPS certificates
+instead of certifi. Using system trust stores has advantages over certifi like automatically supporting
+corporate proxy certificates without additional configuration.
+
+In order to use system trust stores you must be using Python 3.10+ and install the package `truststore`_ from PyPI.
+
+.. tab:: Unix/macOS
+
+   .. code-block:: console
+
+      # Requires Python 3.10 or later
+      $ python --version
+      Python 3.10.4
+
+      # Install the 'truststore' package from PyPI
+      $ python -m pip install truststore
+      [...]
+
+      # Use '--use-feature=truststore' flag to enable
+      $ python -m pip install SomePackage --use-feature=truststore
+      [...]
+      Successfully installed SomePackage
+
+.. tab:: Windows
+
+   .. code-block:: console
+
+      # Requires Python 3.10 or later
+      C:\> py --version
+      Python 3.10.4
+
+      # Install the 'truststore' package from PyPI
+      C:\> py -m pip install truststore
+      [...]
+
+      # Use '--use-feature=truststore' flag to enable
+      C:\> py -m pip install SomePackage --use-feature=truststore
+      [...]
+      Successfully installed SomePackage
+
+When to use system trust stores
+-------------------------------
+
+You should try using system trust stores when there is a custom certificate chain configured for your
+system that pip isn't aware of. Typically this situation will manifest with an ``SSLCertVerificationError``
+with the message "certificate verify failed: unable to get local issuer certificate":
+
+.. code-block:: console
+
+   $ python -m pip install -U SomePackage
+
+   [...]
+
+   Could not fetch URL https://pypi.org/simple/SomePackage/:
+   There was a problem confirming the ssl certificate:
+
+   [...]
+
+   (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED]
+   certificate verify failed: unable to get local issuer certificate (_ssl.c:997)'))) - skipping
+
+This error means that OpenSSL wasn't able to find a trust anchor to verify the chain against.
+Using system trust stores instead of certifi will likely solve this issue.
+
+Follow up
+---------
+
+If you encounter a TLS/SSL error when using the ``truststore`` feature you should open an issue
+on the `truststore GitHub issue tracker`_ instead of pip's issue tracker. The maintainers of truststore
+will help diagnose and fix the issue.
+
+.. _truststore: https://truststore.readthedocs.io
+.. _truststore GitHub issue tracker: https://github.com/sethmlarson/truststore/issues