diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 6a25a6e6ae3..2caa8f5e835 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -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 +============================================= + +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