Zanie Blue
b6854d77bf
The following user-facing changes are included here: - `aws-lc` is used instead of `ring` for a cryptography backend - Expands our certificate signature algorithm support to include ECDSA_P256_SHA512, ECDSA_P384_SHA512, ECDSA_P521_SHA256, ECDSA_P521_SHA384, and ECDSA_P521_SHA512 - `--native-tls` is deprecated in favor of a new `--system-certs` flag, avoiding confusion with the TLS implementation used (we use `rustls` not `native-tls`, see prior confusion at https://github.com/astral-sh/uv/issues/11595) - NASM is a new build requirement on Windows, it is required by `aws-lc` on x86-64 and i386 - `rustls-platform-verifier` is used instead of `rustls-native-certs` for system certificate verification - On macOS, certificate validation is now delegated to `Security.framework` (`SecTrust`). Performance when using `--system-certs` is improved by avoiding exporting and parsing all the certificates from the keychain at startup. - On Windows, certificate validation is now delegated to `CertGetCertificateChain` and `CertVerifyCertificateChainPolicy` - On Linux, certificate validation should be approximately unchanged - Some previously failing chains may succeed, and some previously accepted chains may fail; generally, this should result in behavior closer matching browsers and other native applications - macOS and Windows may now perform live OCSP fetches for early revocation, which could add latency to some requests - Empty `SSL_CERT_FILE` values are ignored (for consistency with `SSL_CERT_DIR`) The following internal changes are included here: - Certificate loading has been refactored to use a newtype with helper methods - The certificate tests have been rewritten - We use `webpki-root-certs` instead of `webpki-roots`, see https://github.com/astral-sh/uv/pull/17543#discussion_r2820187691 - We request `identity` encoding for range requests, see https://github.com/astral-sh/async_http_range_reader/pull/3#discussion_r2700194798 - Various dependencies (including forks) updates to versions which use reqwest 0.13+ This is a replacement of #17543 with an updated description. See that pull request for prior discussion. I've made the following changes from the initial approach there: - Previously, the `native-tls` TLS implementation was added which included an OpenSSL build. We don't currently use the `native-tls` implementation, but the `--native-tls` flag there was erroneously updated to enable it. - Previously, there was a `--tls-backend` flag to toggle between `native-tls` and `rustls`. Since we currently always use `rustls`, this is deferred to future work (if we need it at all). - Previously, there were unintentional breaking changes to `SSL_CERT_FILE` and `SSL_CERT_DIR` handling, including merging with the base certificates instead of replacing them, dropping support for OpenSSL hash-named certificate files, skipping deduplication of certificates. Here, we retain use of `rustls-native-certs` for loading certificates from the system as it handles these edge cases. Closes https://github.com/astral-sh/uv/issues/17427 --------- Co-authored-by: salmonsd <22984014+salmonsd@users.noreply.github.com>
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
# TLS certificates
|
||
|
||
uv uses TLS to securely communicate with package indexes and other HTTPS servers. TLS certificates
|
||
are used to verify the identity of these servers, ensuring that connections are not intercepted.
|
||
|
||
## TLS backend
|
||
|
||
uv uses [`rustls`](https://github.com/rustls/rustls), a memory-safe TLS implementation written in
|
||
Rust, with [`aws-lc-rs`](https://github.com/aws/aws-lc-rs) as the cryptography provider.
|
||
|
||
uv supports the following X.509 certificate signature algorithms:
|
||
|
||
- ECDSA (P-256, P-384, P-521) with SHA-256, SHA-384, or SHA-512
|
||
- Ed25519
|
||
- RSA PKCS#1 v1.5 (2048–8192 bit) with SHA-256, SHA-384, or SHA-512
|
||
- RSA-PSS (2048–8192 bit) with SHA-256, SHA-384, or SHA-512
|
||
|
||
## System certificates
|
||
|
||
By default, uv uses bundled Mozilla root certificates for TLS verification. In some cases, you may
|
||
want to use the platform's native certificate store instead — for example, if you're relying on a
|
||
corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate
|
||
store.
|
||
|
||
To use system certificates, pass the [`--system-certs`](../../reference/cli.md#uv) flag, set the
|
||
[`UV_SYSTEM_CERTS`](../../reference/environment.md#uv_system_certs) environment variable to `true`,
|
||
or set [`system-certs = true`](../../reference/settings.md#system-certs) in `uv.toml`.
|
||
|
||
When using system certificates, certificate verification is performed by
|
||
[`rustls-platform-verifier`](https://github.com/rustls/rustls-platform-verifier), which delegates to
|
||
the operating system's certificate verifier.
|
||
|
||
## Custom certificates
|
||
|
||
To use custom CA certificates, set the
|
||
[`SSL_CERT_FILE`](../../reference/environment.md#ssl_cert_file) environment variable to the path of
|
||
a PEM-encoded certificate bundle (e.g., `certs.pem`, `ca-bundle.crt`), or set
|
||
[`SSL_CERT_DIR`](../../reference/environment.md#ssl_cert_dir) to one or more directories containing
|
||
PEM-encoded certificate files. Multiple entries are supported, separated using a platform-specific
|
||
delimiter (`:` on Unix, `;` on Windows).
|
||
|
||
Certificates are usually stored with `.pem`, `.crt`, or `.cer` extensions, but uv will attempt to
|
||
read a certificate from any regular file in the provided `SSL_CERT_DIR`.
|
||
|
||
Files that cannot be parsed as PEM certificates are ignored. uv resolves symlinks and ignores
|
||
dangling symlinks.
|
||
|
||
DER-encoded files are not supported.
|
||
|
||
When set, these environment variables **override** the default certificate source entirely — only
|
||
the provided certificates will be trusted.
|
||
|
||
`SSL_CERT_FILE` can point to a single certificate or a bundle containing multiple certificates.
|
||
`SSL_CERT_DIR` can include multiple directory entries; uv will load all valid certificates from each
|
||
directory.
|
||
|
||
If client certificate authentication (mTLS) is desired, set the
|
||
[`SSL_CLIENT_CERT`](../../reference/environment.md#ssl_client_cert) environment variable to the path
|
||
of a PEM formatted file containing the certificate followed by the private key.
|
||
|
||
## Insecure hosts
|
||
|
||
If you're using a setup in which you want to trust a self-signed certificate or otherwise disable
|
||
certificate verification, you can instruct uv to allow insecure connections to dedicated hosts via
|
||
the [`allow-insecure-host`](../../reference/settings.md#allow-insecure-host) configuration option.
|
||
For example, adding the following to `pyproject.toml` will allow insecure connections to
|
||
`example.com`:
|
||
|
||
```toml
|
||
[tool.uv]
|
||
allow-insecure-host = ["example.com"]
|
||
```
|
||
|
||
`allow-insecure-host` expects to receive a hostname (e.g., `localhost`) or hostname-port pair (e.g.,
|
||
`localhost:8080`), and is only applicable to HTTPS connections, as HTTP connections are inherently
|
||
insecure.
|
||
|
||
Use `allow-insecure-host` with caution and only in trusted environments, as it can expose you to
|
||
security risks due to the lack of certificate verification.
|