diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 384d393fdd7..7c17c264a30 100644 --- a/docs/html/cli/pip_install.rst +++ b/docs/html/cli/pip_install.rst @@ -219,18 +219,10 @@ details) is selected. See the :ref:`pip install Examples`. +.. _`0-ssl certificate verification`: +.. rubric:: SSL Certificate Verification -.. _`SSL Certificate Verification`: - -SSL Certificate Verification ----------------------------- - -Starting with v1.3, pip provides SSL certificate verification over HTTP, to -prevent man-in-the-middle attacks against PyPI downloads. This does not use -the system certificate store but instead uses a bundled CA certificate -store. The default bundled CA certificate store certificate store may be -overridden by using ``--cert`` option or by using ``PIP_CERT``, -``REQUESTS_CA_BUNDLE``, or ``CURL_CA_BUNDLE`` environment variables. +This is now covered in :doc:`../topics/https-certificates`. .. _`0-caching`: .. rubric:: Caching diff --git a/docs/html/topics/https-certificates.md b/docs/html/topics/https-certificates.md new file mode 100644 index 00000000000..b42c463e6cc --- /dev/null +++ b/docs/html/topics/https-certificates.md @@ -0,0 +1,71 @@ +(SSL Certificate Verification)= + +# HTTPS Certificates + +```{versionadded} 1.3 + +``` + +By default, pip will perform SSL certificate verification for network +connections it makes over HTTPS. These serve to prevent man-in-the-middle +attacks against package downloads. This does not use the system certificate +store but, instead, uses a bundled CA certificate store from {pypi}`certifi`. + +## Using a specific certificate store + +The `--cert` option (and the corresponding `PIP_CERT` environment variable) +allow users to specify a different certificate store/bundle for pip to use. It +is also possible to use `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE` environment +variables. + +## Using system certificate stores + +```{versionadded} 22.2 +Experimental support, behind `--use-feature=truststore`. +``` + +It is possible to use the system trust store, instead of the bundled certifi +certificates for verifying HTTPS certificates. This approach will typically +support corporate proxy certificates without additional configuration. + +In order to use system trust stores, you need to: + +- Use Python 3.10 or newer. +- Install the {pypi}`truststore` package, in the Python environment you're + running pip in. + + This is typically done by installing this package using a system package + manager or by using pip in {ref}`Hash-checking mode` for this package and + trusting the network using the `--trusted-host` flag. + + ```{pip-cli} + $ python -m pip install truststore + [...] + $ python -m pip install SomePackage --use-feature=truststore + [...] + Successfully installed SomePackage + ``` + +### When to use + +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": + +```{pip-cli} +$ pip install -U SomePackage +[...] + 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. + +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 github issue tracker]: + https://github.com/sethmlarson/truststore/issues diff --git a/docs/html/topics/index.md b/docs/html/topics/index.md index 011205a111d..eb2b5f54d5b 100644 --- a/docs/html/topics/index.md +++ b/docs/html/topics/index.md @@ -14,6 +14,7 @@ authentication caching configuration dependency-resolution +https-certificates local-project-installs repeatable-installs secure-installs diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 70a28ab9988..b31ca4f608a 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1138,79 +1138,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 -============================================= +.. _`0-using-system-trust-stores-for-verifying-https`: +.. rubric:: 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 +This is now covered in :doc:`topics/https-certificates`.