Skip to content

Commit 9d677f9

Browse files
pradyunsgpradyunsg
committed
Add a dedicated topic page for HTTPS certificates
This makes further progress on moving content into dedeicated topic pages, away from dumping it into `pip install`'s documentation or as a part of the user guide.
1 parent b8ccb04 commit 9d677f9

File tree

4 files changed

+77
-86
lines changed

4 files changed

+77
-86
lines changed

‎docs/html/cli/pip_install.rst

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -219,18 +219,10 @@ details) is selected.
219219

220220
See the :ref:`pip install Examples<pip install Examples>`.
221221

222+
.. _`0-ssl certificate verification`:
223+
.. rubric:: SSL Certificate Verification
222224

223-
.. _`SSL Certificate Verification`:
224-
225-
SSL Certificate Verification
226-
----------------------------
227-
228-
Starting with v1.3, pip provides SSL certificate verification over HTTP, to
229-
prevent man-in-the-middle attacks against PyPI downloads. This does not use
230-
the system certificate store but instead uses a bundled CA certificate
231-
store. The default bundled CA certificate store certificate store may be
232-
overridden by using ``--cert`` option or by using ``PIP_CERT``,
233-
``REQUESTS_CA_BUNDLE``, or ``CURL_CA_BUNDLE`` environment variables.
225+
This is now covered in :doc:`../topics/https-certificates`.
234226

235227
.. _`0-caching`:
236228
.. rubric:: Caching

‎docs/html/topics/https-certificates.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
(SSL Certificate Verification)=
2+
3+
# HTTPS Certificates
4+
5+
```{versionadded} 1.3
6+
7+
```
8+
9+
pip provides SSL certificate verification over HTTP, to prevent
10+
man-in-the-middle attacks against package downloads. This does not use the
11+
system certificate store but instead uses a bundled CA certificate store.
12+
13+
## Using a specific certificate store
14+
15+
The `--cert` option (and the corresponding `PIP_CERT` environment variable)
16+
allow users to specify a different certificate store/bundle for pip to use. It
17+
is also possible to use `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE` environment
18+
variables.
19+
20+
## Using system certificate stores
21+
22+
```{versionadded} 22.2
23+
Experimental support, behind `--use-feature=truststore`.
24+
```
25+
26+
It is possible to use the system trust store, instead of the bundled certifi
27+
certificates for verifying HTTPS certificates. This approach will typically
28+
support corporate proxy certificates without additional configuration.
29+
30+
In order to use system trust stores, you need to:
31+
32+
- Use Python 3.10 or newer.
33+
- Install the {pypi}`truststore` package, in the Python environment you're
34+
running pip in.
35+
36+
This is typically done by installing this package using a system package
37+
manager or by using pip in {ref}`Hash-checking mode` for this package and
38+
trusting the network using the `--trusted-host` flag.
39+
40+
```{pip-cli}
41+
$ python -m pip install truststore
42+
[...]
43+
$ python -m pip install SomePackage --use-feature=truststore
44+
[...]
45+
Successfully installed SomePackage
46+
```
47+
48+
### When to use
49+
50+
You should try using system trust stores when there is a custom certificate
51+
chain configured for your system that pip isn't aware of. Typically, this
52+
situation will manifest with an `SSLCertVerificationError` with the message
53+
"certificate verify failed: unable to get local issuer certificate":
54+
55+
```{pip-cli}
56+
$ pip install -U SomePackage
57+
[...]
58+
SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (\_ssl.c:997)'))) - skipping
59+
```
60+
61+
This error means that OpenSSL wasn't able to find a trust anchor to verify the
62+
chain against. Using system trust stores instead of certifi will likely solve
63+
this issue.
64+
65+
If you encounter a TLS/SSL error when using the `truststore` feature you should
66+
open an issue on the [truststore GitHub issue tracker] instead of pip's issue
67+
tracker. The maintainers of truststore will help diagnose and fix the issue.
68+
69+
[truststore github issue tracker]:
70+
https://github.com/sethmlarson/truststore/issues

‎docs/html/topics/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ authentication
1414
caching
1515
configuration
1616
dependency-resolution
17+
https-certificates
1718
local-project-installs
1819
repeatable-installs
1920
secure-installs

‎docs/html/user_guide.rst

Lines changed: 3 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1138,79 +1138,7 @@ announcements on the `low-traffic packaging announcements list`_ and
11381138
.. _the official Python blog: https://blog.python.org/
11391139
.. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher
11401140

1141-
Using system trust stores for verifying HTTPS
1142-
=============================================
1141+
.. _`0-using-system-trust-stores-for-verifying-https`:
1142+
.. rubric:: Using system trust stores for verifying HTTPS
11431143

1144-
pip 22.2 added **experimental** support for using system trust stores to verify HTTPS certificates
1145-
instead of certifi. Using system trust stores has advantages over certifi like automatically supporting
1146-
corporate proxy certificates without additional configuration.
1147-
1148-
In order to use system trust stores you must be using Python 3.10+ and install the package `truststore`_ from PyPI.
1149-
1150-
.. tab:: Unix/macOS
1151-
1152-
.. code-block:: console
1153-
1154-
# Requires Python 3.10 or later
1155-
$ python --version
1156-
Python 3.10.4
1157-
1158-
# Install the 'truststore' package from PyPI
1159-
$ python -m pip install truststore
1160-
[...]
1161-
1162-
# Use '--use-feature=truststore' flag to enable
1163-
$ python -m pip install SomePackage --use-feature=truststore
1164-
[...]
1165-
Successfully installed SomePackage
1166-
1167-
.. tab:: Windows
1168-
1169-
.. code-block:: console
1170-
1171-
# Requires Python 3.10 or later
1172-
C:\> py --version
1173-
Python 3.10.4
1174-
1175-
# Install the 'truststore' package from PyPI
1176-
C:\> py -m pip install truststore
1177-
[...]
1178-
1179-
# Use '--use-feature=truststore' flag to enable
1180-
C:\> py -m pip install SomePackage --use-feature=truststore
1181-
[...]
1182-
Successfully installed SomePackage
1183-
1184-
When to use system trust stores
1185-
-------------------------------
1186-
1187-
You should try using system trust stores when there is a custom certificate chain configured for your
1188-
system that pip isn't aware of. Typically this situation will manifest with an ``SSLCertVerificationError``
1189-
with the message "certificate verify failed: unable to get local issuer certificate":
1190-
1191-
.. code-block:: console
1192-
1193-
$ python -m pip install -U SomePackage
1194-
1195-
[...]
1196-
1197-
Could not fetch URL https://pypi.org/simple/SomePackage/:
1198-
There was a problem confirming the ssl certificate:
1199-
1200-
[...]
1201-
1202-
(Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED]
1203-
certificate verify failed: unable to get local issuer certificate (_ssl.c:997)'))) - skipping
1204-
1205-
This error means that OpenSSL wasn't able to find a trust anchor to verify the chain against.
1206-
Using system trust stores instead of certifi will likely solve this issue.
1207-
1208-
Follow up
1209-
---------
1210-
1211-
If you encounter a TLS/SSL error when using the ``truststore`` feature you should open an issue
1212-
on the `truststore GitHub issue tracker`_ instead of pip's issue tracker. The maintainers of truststore
1213-
will help diagnose and fix the issue.
1214-
1215-
.. _truststore: https://truststore.readthedocs.io
1216-
.. _truststore GitHub issue tracker: https://github.com/sethmlarson/truststore/issues
1144+
This is now covered in :doc:`topics/https-certificates`.

0 commit comments

Comments
 (0)