Merge pull request #11322 from pradyunsg/docs/move-truststore-docs

Add a dedicated topic page for HTTPS certificates

docs/html/cli/pip_install.rst

@@ -219,18 +219,10 @@ details) is selected.
 
 See the :ref:`pip install Examples<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

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

docs/html/topics/index.md

@@ -14,6 +14,7 @@ authentication
 caching
 configuration
 dependency-resolution
+https-certificates
 local-project-installs
 repeatable-installs
 secure-installs

docs/html/user_guide.rst

@@ -1147,79 +1147,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`.