From 901500c5e980a721bfeff9a042e440fc24a2f5e0 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Mon, 30 May 2022 14:18:16 -0500 Subject: [PATCH 1/4] Add section on 'truststore' feature to User Guide --- docs/html/user_guide.rst | 77 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 6a25a6e6ae3..78281a16839 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 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 From a3a953d7af5c7b93310fa78e639f4391f0ae5798 Mon Sep 17 00:00:00 2001 From: Tzu-ping Chung Date: Tue, 31 May 2022 10:22:45 +0800 Subject: [PATCH 2/4] Grammar --- docs/html/user_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 78281a16839..a0ae2cb8da3 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1221,7 +1221,7 @@ 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 +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. From 5b63fbaa00c801084c6437a78291dc4e71b293c9 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Mon, 6 Jun 2022 19:33:03 -0700 Subject: [PATCH 3/4] Update docs/html/user_guide.rst Co-authored-by: Pradyun Gedam --- docs/html/user_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index a0ae2cb8da3..7bfea8d5e99 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1151,7 +1151,7 @@ announcements on the `low-traffic packaging announcements list`_ and .. _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) +Using system trust stores for verifying HTTPS ============================================================ pip 22.2 added **experimental** support for using system trust stores to verify HTTPS certificates From 5565717a0630ecbd75ac3c8646824790afbef3bc Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Tue, 7 Jun 2022 04:05:50 -0700 Subject: [PATCH 4/4] Update docs/html/user_guide.rst Co-authored-by: Pradyun Gedam --- docs/html/user_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 7bfea8d5e99..2caa8f5e835 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1152,7 +1152,7 @@ announcements on the `low-traffic packaging announcements list`_ and .. _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