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>
3.7 KiB
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, a memory-safe TLS implementation written in
Rust, with 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 flag, set the
UV_SYSTEM_CERTS environment variable to true,
or set system-certs = true in uv.toml.
When using system certificates, certificate verification is performed by
rustls-platform-verifier, which delegates to
the operating system's certificate verifier.
Custom certificates
To use custom CA certificates, set the
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 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 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 configuration option.
For example, adding the following to pyproject.toml will allow insecure connections to
example.com:
[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.