Add an example of using a custom SSLContext to docs
@@ -480,3 +480,34 @@ To enable this simply define environment variable `SSLKEYLOGFILE`:
Then configure the key logfile in `Wireshark <https://wireshark.org>`_, see
`Wireshark TLS Decryption <https://wiki.wireshark.org/TLS#TLS_Decryption>`_ for instructions.
+
+Custom SSL Contexts
+-------------------
+
+You can exercise fine-grained control over the urllib3 SSL configuration by
+providing a :class:`ssl.SSLContext <python:ssl.SSLContext>` object. For purposes
+of compatibility, we recommend you obtain one from
+:func:`~urllib3.util.ssl_.create_urllib3_context`.
+
+Once you have a context object, you can mutate it to achieve whatever effect
+you'd like. For example, the code below loads the default SSL certificates, sets
+the :data:`ssl.OP_ENABLE_MIDDLEBOX_COMPAT<python:ssl.OP_ENABLE_MIDDLEBOX_COMPAT>`
+flag that isn't set by default, and then makes a HTTPS request:
+
+.. code-block:: python
+
+ import ssl
+
+ from urllib3 import PoolManager
+ from urllib3.util.ssl_ import create_urllib3_context
+
+ ctx = create_urllib3_context()
+ ctx.load_default_certs()
+ ctx.options |= ssl.OP_ENABLE_MIDDLEBOX_COMPAT
+
+ with PoolManager(ssl_context=ctx) as pool:
+ pool.request("GET", "https://www.google.com/")
+
+Note that this is different from passing an ``options`` argument to
+:func:`~urllib3.util.ssl_.create_urllib3_context` because we don't overwrite
+the default options: we only add a new one.
