Help us test system trust stores in Python

Published 2022-07-26 by Seth Larson
Reading time: 3 minutes

⚠️ If you're an IT or software team that uses Python along with corporate system certificates, an internal CA, or internal PyPI repository: please read on to help improve Python. If you know one or more teams that fits this description: forward them this article! We need lots of people to try the new pip feature to test our implementation of system trust stores in Python.

On July 21st pip v22.2 was released with a new experimental feature for using native system trust stores to verify HTTPS connections with --use-feature=truststore. This support is provided by a new Python package called 'truststore':

# No more 'local issuer not found' errors!

$ python -m pip install \
    --use-feature=truststore Flask

Now that the feature is available in pip we need your help proving the implementation works for a large set of systems and environments. The long-term goal of the 'truststore' project is to make the default TLS experience better for libraries like pip, urllib3, and Requests.

TLDR: How can I help?

You can try running the following commands in a virtual environment:

# 'truststore' requires Python 3.10 or later to work.
$ python --version

# Upgrade to pip 22.2 and install 'truststore'
$ python -m pip install -U pip truststore

Successfully installed pip-22.2
Successfully installed truststore-0.4.0

# Check that pip is 22.2 or later
$ python -m pip --version
pip 22.2 from .../venv/lib/python3.10/site-packages/pip (python 3.10)

# Try the new feature! 🚀
$ python -m pip install -U --use-feature=truststore urllib3

Successfully installed urllib3-1.26.10

What should I do afterwards?

What do errors from custom CA certificates typically look like?

Usually the error will have a message like the one below:

  '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:'
  '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)'

For pip there are usually retries so you may see the error more than once. If you see a different error and you're not sure what it means feel free to open an issue describing your environment.

What if I can't upgrade pip because of custom CA certificates?

An unfortunate "chicken and egg" situation. Can't upgrade pip from PyPI to use custom CA certificates because your custom CA certificate is causing errors. For this situation I suggest running the following commands which disables TLS certificate verification for PyPI but does integrity verification of the downloaded packages to ensure they haven't been modified in transit:

# Create a temporary requirements file to require hashes on install:
$ echo "\
truststore==0.4.0 \
    --hash=sha256:018f261a13c970eb814ac424db4a48d538310416ddad4231ca49033c210eb5cf \
pip==22.2 \
    --hash=sha256:8d63fcd4ee293e30b644827268a0a973d080e5c7425ef26d427f5eb2126c7681 \
    --hash=sha256:9abf423d5d64f3289ab9d5bf31da9e6234f2e9c5d8dcf1423bcb46b809a02c2c" > reqs.txt

# Install pip and truststore and verify hashes
$ python -m pip install --require-hashes \
  --trusted-host pypi.org \
  --trusted-host files.pythonhosted.org \
  -r reqs.txt

Successfully installed pip-22.2
Successfully installed truststore-0.4.0

After installing pip and truststore you should be able to use the --use-feature=truststore option in the instructions above.

Thanks for reading! ♡ Did you find this article helpful and want more content like it? Get notified of new posts by subscribing to the RSS feed or the email newsletter.

This work is licensed under CC BY-SA 4.0