Skip to content

Commit 8070892

Browse files
pradyunsgpradyunsg
authored
Merge pull request #11322 from pradyunsg/docs/move-truststore-docs
Add a dedicated topic page for HTTPS certificates
2 parents 9066584 + dc1ea04 commit 8070892

File tree

4 files changed

+78
-86
lines changed

4 files changed

+78
-86
lines changed

‎docs/html/cli/pip_install.rst

+3-11
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

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

‎docs/html/topics/index.md

+1
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

+3-75
Original file line numberDiff line numberDiff line change
@@ -1147,79 +1147,7 @@ announcements on the `low-traffic packaging announcements list`_ and
11471147
.. _the official Python blog: https://blog.python.org/
11481148
.. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher
11491149

1150-
Using system trust stores for verifying HTTPS
1151-
=============================================
1150+
.. _`0-using-system-trust-stores-for-verifying-https`:
1151+
.. rubric:: Using system trust stores for verifying HTTPS
11521152

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

0 commit comments

Comments
 (0)