Skip to content

Commit dc1ea04

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 dc1ea04

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
@@ -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)