SSL
When making a request over HTTPS, HTTPX needs to verify the identity of the requested host. To do this, it uses a bundle of SSL certificates (a.k.a. CA bundle) delivered by a trusted certificate authority (CA).
Changing the verification defaults
By default, HTTPX uses the CA bundle provided by Certifi. This is what you want in most cases, even though some advanced situations may require you to use a different set of certificates.
If you'd like to use a custom CA bundle, you can use the verify
parameter.
import httpx
r = httpx.get("https://example.org", verify="path/to/client.pem")
Alternatively, you can pass a standard library ssl.SSLContext
.
>>> import ssl
>>> import httpx
>>> context = ssl.create_default_context()
>>> context.load_verify_locations(cafile="/tmp/client.pem")
>>> httpx.get('https://example.org', verify=context)
<Response [200 OK]>
We also include a helper function for creating properly configured SSLContext
instances.
>>> context = httpx.create_ssl_context()
The create_ssl_context
function accepts the same set of SSL configuration arguments
(trust_env
, verify
, cert
and http2
arguments)
as httpx.Client
or httpx.AsyncClient
>>> import httpx
>>> context = httpx.create_ssl_context(verify="/tmp/client.pem")
>>> httpx.get('https://example.org', verify=context)
<Response [200 OK]>
Or you can also disable the SSL verification entirely, which is not recommended.
import httpx
r = httpx.get("https://example.org", verify=False)
SSL configuration on client instances
If you're using a Client()
instance, then you should pass any SSL settings when instantiating the client.
client = httpx.Client(verify=False)
The client.get(...)
method and other request methods do not support changing the SSL settings on a per-request basis. If you need different SSL settings in different cases you should use more that one client instance, with different settings on each. Each client will then be using an isolated connection pool with a specific fixed SSL configuration on all connections within that pool.
Client Side Certificates
You can also specify a local cert to use as a client-side certificate, either a path to an SSL certificate file, or two-tuple of (certificate file, key file), or a three-tuple of (certificate file, key file, password)
cert = "path/to/client.pem"
client = httpx.Client(cert=cert)
response = client.get("https://example.org")
Alternatively...
cert = ("path/to/client.pem", "path/to/client.key")
client = httpx.Client(cert=cert)
response = client.get("https://example.org")
Or...
cert = ("path/to/client.pem", "path/to/client.key", "password")
client = httpx.Client(cert=cert)
response = client.get("https://example.org")
Making HTTPS requests to a local server
When making requests to local servers, such as a development server running on localhost
, you will typically be using unencrypted HTTP connections.
If you do need to make HTTPS connections to a local server, for example to test an HTTPS-only service, you will need to create and use your own certificates. Here's one way to do it:
- Use trustme to generate a pair of server key/cert files, and a client cert file.
- Pass the server key/cert files when starting your local server. (This depends on the particular web server you're using. For example, Uvicorn provides the
--ssl-keyfile
and--ssl-certfile
options.) - Tell HTTPX to use the certificates stored in
client.pem
:
client = httpx.Client(verify="/tmp/client.pem")
response = client.get("https://localhost:8000")