Add section on 'truststore' feature to User Guide
@@ -1150,3 +1150,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 in 22.2 (2022)
+============================================================
+
+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 an 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
