Support external certicate and document init_context

Allow user to provide their own certification file. Add description of the init_context method to the API documentation.

Author: jdecuyper

docs/source/api.rst

@@ -40,6 +40,11 @@ Headers
 .. autoclass:: hyper.common.headers.HTTPHeaderMap
    :inherited-members:
 
+SSLContext
+----------
+
+.. automethod:: hyper.tls.init_context
+
 Requests Transport Adapter
 --------------------------
 

hyper/common/connection.py

@@ -40,7 +40,7 @@ class HTTPConnection(object):
         resources to the client (see
         :meth:`get_pushes() <hyper.HTTP20Connection.get_pushes>`).
     :param ssl_context: (optional) A class with custom certificate settings.
-        If not provided then hyper's default SSLContext is used instead.
+        If not provided then hyper's default ``SSLContext`` is used instead.
     """
     def __init__(self,
                  host,

hyper/http11/connection.py

@@ -44,7 +44,7 @@ class HTTP11Connection(object):
         ``False`` for most requests, but to ``True`` for any request issued to
         port 443.
     :param ssl_context: (optional) A class with custom certificate settings.
-        If not provided then hyper's default SSLContext is used instead.
+        If not provided then hyper's default ``SSLContext`` is used instead.
     """
     def __init__(self, host, port=None, secure=None, ssl_context=None,
                  **kwargs):

hyper/http20/connection.py

@@ -52,7 +52,7 @@ class HTTP20Connection(object):
         resources to the client (see
         :meth:`get_pushes() <hyper.HTTP20Connection.get_pushes>`).
     :param ssl_context: (optional) A class with custom certificate settings.
-        If not provided then hyper's default SSLContext is used instead.
+        If not provided then hyper's default ``SSLContext`` is used instead.
     """
     def __init__(self, host, port=None, window_manager=None, enable_push=False,
                  ssl_context=None, **kwargs):

hyper/tls.py

@@ -32,7 +32,7 @@ def wrap_socket(sock, server_hostname, ssl_context=None):
 
     # create the singleton SSLContext we use
     if _context is None:  # pragma: no cover
-        _context = _init_context()
+        _context = init_context()
 
     # if an SSLContext is provided then use it instead of default context
     _ssl_context = ssl_context or _context
@@ -62,13 +62,21 @@ def wrap_socket(sock, server_hostname, ssl_context=None):
     return (ssl_sock, proto)
 
 
-def _init_context():
+def init_context(cert_path=None):
     """
-    Create a pre-configured SSLContext.
+    Create a new ``SSLContext`` that is correctly set up for an HTTP/2 connection.
+    This SSL context object can be customized and passed as a parameter to the
+    :class:`HTTPConnection <hyper.HTTPConnection>` class. Provide your
+    own certificate file in case you don’t want to use hyper’s default
+    certificate. The path to the certificate can be absolute or relative
+    to your working directory.
+
+    :param cert_path: (optional) The path to the certificate file.
+    :returns: An ``SSLContext`` correctly set up for HTTP/2.
     """
     context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
     context.set_default_verify_paths()
-    context.load_verify_locations(cafile=cert_loc)
+    context.load_verify_locations(cafile=cert_path or cert_loc)
     context.verify_mode = ssl.CERT_REQUIRED
     context.check_hostname = True
 

test/test_SSLContext.py

@@ -13,7 +13,7 @@ class TestSSLContext(object):
     """
     def test_default_context(self):
         # Create default SSLContext
-        hyper.tls._context = hyper.tls._init_context()
+        hyper.tls._context = hyper.tls.init_context()
         assert hyper.tls._context.check_hostname == True
         assert hyper.tls._context.verify_mode == ssl.CERT_REQUIRED
         assert hyper.tls._context.options & ssl.OP_NO_COMPRESSION != 0

test/test_integration.py

@@ -27,7 +27,7 @@
 
 # Turn off certificate verification for the tests.
 if ssl is not None:
-    hyper.tls._context = hyper.tls._init_context()
+    hyper.tls._context = hyper.tls.init_context()
     hyper.tls._context.check_hostname = False
     hyper.tls._context.verify_mode = ssl.CERT_NONE
 

test/test_integration_http11.py

@@ -14,7 +14,7 @@
 
 # Turn off certificate verification for the tests.
 if ssl is not None:
-    hyper.tls._context = hyper.tls._init_context()
+    hyper.tls._context = hyper.tls.init_context()
     hyper.tls._context.check_hostname = False
     hyper.tls._context.verify_mode = ssl.CERT_NONE