Documentation for SSL_CERT_FILE and SSL_CERT_DIR (#3579)

Co-authored-by: Kim Christie <[email protected]>

Author: tobb10001

docs/advanced/ssl.md

@@ -71,19 +71,7 @@ client = httpx.Client(verify=ctx)
 
 ### Working with `SSL_CERT_FILE` and `SSL_CERT_DIR`
 
-Unlike `requests`, the `httpx` package does not automatically pull in [the environment variables `SSL_CERT_FILE` or `SSL_CERT_DIR`](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_default_verify_paths.html). If you want to use these they need to be enabled explicitly.
-
-For example...
-
-```python
-# Use `SSL_CERT_FILE` or `SSL_CERT_DIR` if configured.
-# Otherwise default to certifi.
-ctx = ssl.create_default_context(
-    cafile=os.environ.get("SSL_CERT_FILE", certifi.where()),
-    capath=os.environ.get("SSL_CERT_DIR"),
-)
-client = httpx.Client(verify=ctx)
-```
+`httpx` does respect the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables by default. For details, refer to [the section on the environment variables page](../environment_variables.md#ssl_cert_file).
 
 ### Making HTTPS requests to a local server
 

docs/environment_variables.md

@@ -51,3 +51,29 @@ python -c "import httpx; httpx.get('http://example.com')"
 python -c "import httpx; httpx.get('http://127.0.0.1:5000/my-api')"
 python -c "import httpx; httpx.get('https://www.python-httpx.org')"
 ```
+
+## `SSL_CERT_FILE`
+
+Valid values: a filename
+
+If this environment variable is set then HTTPX will load
+CA certificate from the specified file instead of the default
+location.
+
+Example:
+
+```console
+SSL_CERT_FILE=/path/to/ca-certs/ca-bundle.crt python -c "import httpx; httpx.get('https://example.com')"
+```
+
+## `SSL_CERT_DIR`
+
+Valid values: a directory following an [OpenSSL specific layout](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html).
+
+If this environment variable is set and the directory follows an [OpenSSL specific layout](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html) (ie. you ran `c_rehash`) then HTTPX will load CA certificates from this directory instead of the default location.
+
+Example:
+
+```console
+SSL_CERT_DIR=/path/to/ca-certs/ python -c "import httpx; httpx.get('https://example.com')"
+```