Add docs on SSL certificates (#510)

* Add docs on SSL certificates

* Update docs on verify and cert params

* Tweak wording

* Tweak wording about localhost

* Remove advanced warning

* Rephrase introduction of local HTTPS section

diff --git a/docs/advanced.md b/docs/advanced.md
index f0d402ba6383740d39825ba1e2ac36533153e566..3e73f5b57394bdf327a973502d43430925228677 100644 (file)
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -362,3 +362,38 @@ is set to `None` or it cannot be inferred from it, HTTPX will default to
   ...
 }
 ```
+
+## SSL certificates
+
+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).
+
+### Default CA bundle
+
+By default, HTTPX uses the CA bundle provided by [Certifi](https://pypi.org/project/certifi/). This is what you want in most cases, even though some advanced situations may require you to use a different set of certificates.
+
+### Using a custom CA bundle
+
+If you'd like to use a custom CA bundle, you can use the `verify` parameter that is available on the high-level API as well as clients. For example:
+
+```python
+import httpx
+
+r = httpx.get("https://example.org", verify="path/to/client.pem")
+```
+
+### 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:
+
+1. Use [trustme-cli](https://github.com/sethmlarson/trustme-cli/) to generate a pair of server key/cert files, and a client cert file.
+1. Pass the server key/cert files when starting your local server. (This depends on the particular web server you're using. For example, [Uvicorn](https://www.uvicorn.org) provides the `--ssl-keyfile` and `--ssl-certfile` options.)
+1. Tell HTTPX to use the certificates stored in `client.pem`:
+
+```python
+>>> import httpx
+>>> r = httpx.get("https://localhost:8000", verify="/tmp/client.pem")
+>>> r
+Response <200 OK>
+```

diff --git a/httpx/api.py b/httpx/api.py
index 82fc48dc59583f126c925d4cb5d9b8a14ea16bd7..1e01983c7243bfb42ca52302e6910b1e9be5c1ae 100644 (file)
--- a/httpx/api.py
+++ b/httpx/api.py
@@ -27,8 +27,8 @@ def request(
     auth: AuthTypes = None,
     timeout: TimeoutTypes = None,
     allow_redirects: bool = True,
-    cert: CertTypes = None,
     verify: VerifyTypes = True,
+    cert: CertTypes = None,
     stream: bool = False,
     trust_env: bool = None,
 ) -> Response:
@@ -57,10 +57,13 @@ def request(
     * **timeout** - *(optional)* The timeout configuration to use when sending
     the request.
     * **allow_redirects** - *(optional)* Enables or disables HTTP redirects.
-    * **cert** - *(optional)* Either a path to an SSL certificate file, or
+    * **verify** - *(optional)* SSL certificates (a.k.a CA bundle) used to
+    verify the identity of requested hosts. Either `True` (default CA bundle),
+    a path to an SSL certificate file, or `False` (disable verification).
+    * **cert** - *(optional)* An SSL certificate used by the requested host
+    to authenticate the client. 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).
-    * **verify** - *(optional)* Enables or disables SSL verification.
     * **trust_env** - *(optional)* Enables or disables usage of environment
     variables for configuration.
     * **proxies** - *(optional)* A dictionary mapping HTTP protocols to proxy

diff --git a/httpx/client.py b/httpx/client.py
index d54d2fd62c420176fb5585f9b973f81232f7de3e..45589b9e23bf96f2b54f681f3cf4e48a6a05b589 100644 (file)
--- a/httpx/client.py
+++ b/httpx/client.py
@@ -694,8 +694,11 @@ class Client(BaseClient):
     sending requests.
     * **cookies** - *(optional)* Dictionary of Cookie items to include when
     sending requests.
-    * **verify** - *(optional)* Enables or disables SSL verification.
-    * **cert** - *(optional)* Either a path to an SSL certificate file, or
+    * **verify** - *(optional)* SSL certificates (a.k.a CA bundle) used to
+    verify the identity of requested hosts. Either `True` (default CA bundle),
+    a path to an SSL certificate file, or `False` (disable verification).
+    * **cert** - *(optional)* An SSL certificate used by the requested host
+    to authenticate the client. 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).
     * **http_versions** - *(optional)* A list of strings of HTTP protocol
@@ -776,8 +779,8 @@ class Client(BaseClient):
         stream: bool = False,
         auth: AuthTypes = None,
         allow_redirects: bool = True,
-        cert: CertTypes = None,
         verify: VerifyTypes = None,
+        cert: CertTypes = None,
         timeout: TimeoutTypes = None,
         trust_env: bool = None,
     ) -> Response:
@@ -805,10 +808,13 @@ class Client(BaseClient):
         * **auth** - *(optional)* An authentication class to use when sending the
         request.
         * **allow_redirects** - *(optional)* Enables or disables HTTP redirects.
-        * **cert** - *(optional)* Either a path to an SSL certificate file, or
+        * **verify** - *(optional)* SSL certificates (a.k.a CA bundle) used to
+        verify the identity of requested hosts. Either `True` (default CA bundle),
+        a path to an SSL certificate file, or `False` (disable verification).
+        * **cert** - *(optional)* An SSL certificate used by the requested host
+        to authenticate the client. 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).
-        * **verify** - *(optional)* Enables or disables SSL verification.
         * **timeout** - *(optional)* The timeout configuration to use when sending
         the request.
         * **trust_env** - *(optional)* Enables or disables usage of environment