Document the behavior of `--cert`

Environment

• pip version: 19.2dev0 (and earlier)
• Python version: n/a
• OS: n/a

Description

The documentation for the --cert option currently just says “Path to alternate CA bundle.”

This leaves the user wondering: does the specified bundle replace the default set of trust roots, or augment it?

(Also, it would be nice if --trusted-host had a mention of --cert since many people use the former when they could more securely be using the latter.)

[chrahunt]

Some information on the current state of pip (a6b0605) with respect to SSL verification:

1. pip vendors requests and certifi (the versions specified here), and does not patch them in any way to change their default cert-handling behavior. As a result, the default behavior when --cert is not provided is the default behavior of requests.
   1. The default behavior of requests is to use the path returned by certifi.where() if verify is not set to an alternate path (link)
      1. requests itself sets verify to the contents of REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE if not explicitly set (link)
      2. By default certifi.where() returns the path to the CA certificate bundle cacert.pem which is distributed in certifi itself (link)
      3. On Debian, which debundles pip, certifi.where() returns /etc/ssl/certs/ca-certificates.crt (link) - likewise for Ubuntu
      4. On Fedora, which keeps pip bundled but carries a few patches, certifi.where() returns /etc/pki/tls/certs/ca-bundle.crt (link) - probably similar to RedHat and CentOS
2. if --cert is provided, pip sets its session’s verify property to the provided path. As shown in the requests sources above, this completely overrides the default CA certificate bundle. Also as shown above, this can be a file path or a directory.
3. The format of the file/directory provided via --cert should be as described for ssl.SSLContext.load_verify_locations. An example of the file form is in Certificate chains and the directory form is in SSL_CTX_load_verify_locations (in the description of the CApath argument)
4. Previously, pip supported a globally-managed version of certifi being used in preference to the vendored version, but this was reverted by #4712 (10.0.0b1) (I don’t see this in NEWS)

Which I think would translate into the following actions for this issue:

1. Update the pip_install/SSL Certificate Verification docs, mentioning that by default pip uses a bundled CA certificate store provided by certifi (with a link to certifi), but that this may be overridden by package-manager-managed pip.
2. Update the description of --cert. I would leave out the possibility of using a directory and instead just say something like “PEM-encoded CA certificate bundle. If provided, overrides the default.” and optionally:
   1. when generating documentation, we could also include a link to the SSL Certificate Verification section mentioned above
   2. when being invoked as a command, we may mention to reference the user guide for details

[webknjaz]

There’s also 2.python-requests.org/en/master/api/#requests.Session.verify but that doesn’t contain much detail.

I bet this loosely corresponds to the TLS verification mode (https://docs.python.org/3/library/ssl.html#ssl.SSLContext.verify_mode) allowing the user to ignore untrusted certificates. It looks like if it’s set, the check is enforced unconditionally.