Issue #5639: Add a *server_hostname* argument to `SSLContext.wrap_socket`

in order to support the TLS SNI extension.  `HTTPSConnection` and
`urlopen()` also use this argument, so that HTTPS virtual hosts are now
supported.

Doc/library/http.client.rst

@@ -76,6 +76,10 @@ The module provides the following classes:
    .. versionchanged:: 3.2
       *source_address*, *context* and *check_hostname* were added.
 
+   .. versionchanged:: 3.2
+      This class now supports HTTPS virtual hosts if possible (that is,
+      if :data:`ssl.HAS_SNI` is true).
+
 
 .. class:: HTTPResponse(sock, debuglevel=0, strict=0, method=None, url=None)
 

Doc/library/ssl.rst

@@ -338,6 +338,15 @@ Constants
 
    .. versionadded:: 3.2
 
+.. data:: HAS_SNI
+
+   Whether the OpenSSL library has built-in support for the *Server Name
+   Indication* extension to the SSLv3 and TLSv1 protocols (as defined in
+   :rfc:`4366`).  When true, you can use the *server_hostname* argument to
+   :meth:`SSLContext.wrap_socket`.
+
+   .. versionadded:: 3.2
+
 .. data:: OPENSSL_VERSION
 
    The version string of the OpenSSL library loaded by the interpreter::
@@ -538,7 +547,9 @@ to speed up repeated connections from the same clients.
       when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
       give the currently selected cipher.
 
-.. method:: SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True)
+.. method:: SSLContext.wrap_socket(sock, server_side=False, \
+      do_handshake_on_connect=True, suppress_ragged_eofs=True, \
+      server_hostname=None)
 
    Wrap an existing Python socket *sock* and return an :class:`SSLSocket`
    object.  The SSL socket is tied to the context, its settings and
@@ -546,6 +557,15 @@ to speed up repeated connections from the same clients.
    and *suppress_ragged_eofs* have the same meaning as in the top-level
    :func:`wrap_socket` function.
 
+   On client connections, the optional parameter *server_hostname* specifies
+   the hostname of the service which we are connecting to.  This allows a
+   single server to host multiple SSL-based services with distinct certificates,
+   quite similarly to HTTP virtual hosts.  Specifying *server_hostname*
+   will raise a :exc:`ValueError` if the OpenSSL library doesn't have support
+   for it (that is, if :data:`HAS_SNI` is :const:`False`).  Specifying
+   *server_hostname* will also raise a :exc:`ValueError` if *server_side*
+   is true.
+
 .. method:: SSLContext.session_stats()
 
    Get statistics about the SSL sessions created or managed by this context.
@@ -937,3 +957,6 @@ not SSLv2.
 
    `RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile <http://www.ietf.org/rfc/rfc3280>`_
        Housley et. al.
+
+   `RFC 4366: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc/rfc4366>`_
+       Blake-Wilson et. al.

Doc/library/urllib.request.rst

@@ -72,6 +72,10 @@ The :mod:`urllib.request` module defines the following functions:
    .. versionchanged:: 3.2
       *cafile* and *capath* were added.
 
+   .. versionchanged:: 3.2
+      HTTPS virtual hosts are now supported if possible (that is, if
+      :data:`ssl.HAS_SNI` is true).
+
 .. function:: install_opener(opener)
 
    Install an :class:`OpenerDirector` instance as the default global opener.

Lib/http/client.py

@@ -1081,7 +1081,9 @@ else:
                 self.sock = sock
                 self._tunnel()
 
-            self.sock = self._context.wrap_socket(sock)
+            server_hostname = self.host if ssl.HAS_SNI else None
+            self.sock = self._context.wrap_socket(sock,
+                                                  server_hostname=server_hostname)
             try:
                 if self._check_hostname:
                     ssl.match_hostname(self.sock.getpeercert(), self.host)

Lib/ssl.py

@@ -77,6 +77,7 @@ from _ssl import (
     SSL_ERROR_EOF,
     SSL_ERROR_INVALID_ERROR_CODE,
     )
+from _ssl import HAS_SNI
 
 from socket import getnameinfo as _getnameinfo
 from socket import error as socket_error
@@ -158,10 +159,12 @@ class SSLContext(_SSLContext):
 
     def wrap_socket(self, sock, server_side=False,
                     do_handshake_on_connect=True,
-                    suppress_ragged_eofs=True):
+                    suppress_ragged_eofs=True,
+                    server_hostname=None):
         return SSLSocket(sock=sock, server_side=server_side,
                          do_handshake_on_connect=do_handshake_on_connect,
                          suppress_ragged_eofs=suppress_ragged_eofs,
+                         server_hostname=server_hostname,
                          _context=self)
 
 
@@ -176,6 +179,7 @@ class SSLSocket(socket):
                  do_handshake_on_connect=True,
                  family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None,
                  suppress_ragged_eofs=True, ciphers=None,
+                 server_hostname=None,
                  _context=None):
 
         if _context:
@@ -202,7 +206,11 @@ class SSLSocket(socket):
             self.ssl_version = ssl_version
             self.ca_certs = ca_certs
             self.ciphers = ciphers
+        if server_side and server_hostname:
+            raise ValueError("server_hostname can only be specified "
+                             "in client mode")
         self.server_side = server_side
+        self.server_hostname = server_hostname
         self.do_handshake_on_connect = do_handshake_on_connect
         self.suppress_ragged_eofs = suppress_ragged_eofs
         connected = False
@@ -232,7 +240,8 @@ class SSLSocket(socket):
         if connected:
             # create the SSL object
             try:
-                self._sslobj = self.context._wrap_socket(self, server_side)
+                self._sslobj = self.context._wrap_socket(self, server_side,
+                                                         server_hostname)
                 if do_handshake_on_connect:
                     timeout = self.gettimeout()
                     if timeout == 0.0:
@@ -431,7 +440,7 @@ class SSLSocket(socket):
         if self._sslobj:
             raise ValueError("attempt to connect already-connected SSLSocket!")
         socket.connect(self, addr)
-        self._sslobj = self.context._wrap_socket(self, False)
+        self._sslobj = self.context._wrap_socket(self, False, self.server_hostname)
         try:
             if self.do_handshake_on_connect:
                 self.do_handshake()

Lib/test/test_ssl.py

@@ -89,6 +89,7 @@ class BasicSocketTests(unittest.TestCase):
         ssl.CERT_NONE
         ssl.CERT_OPTIONAL
         ssl.CERT_REQUIRED
+        self.assertIn(ssl.HAS_SNI, {True, False})
 
     def test_random(self):
         v = ssl.RAND_status()
@@ -277,6 +278,12 @@ class BasicSocketTests(unittest.TestCase):
         self.assertRaises(ValueError, ssl.match_hostname, None, 'example.com')
         self.assertRaises(ValueError, ssl.match_hostname, {}, 'example.com')
 
+    def test_server_side(self):
+        # server_hostname doesn't work for server sockets
+        ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
+        sock = socket.socket()
+        self.assertRaises(ValueError, ctx.wrap_socket, sock, True,
+                          server_hostname="some.hostname")
 
 class ContextTests(unittest.TestCase):
 
@@ -441,6 +448,14 @@ class NetworkedTests(unittest.TestCase):
                 self.assertEqual({}, s.getpeercert())
             finally:
                 s.close()
+            # Same with a server hostname
+            s = ctx.wrap_socket(socket.socket(socket.AF_INET),
+                                server_hostname="svn.python.org")
+            if ssl.HAS_SNI:
+                s.connect(("svn.python.org", 443))
+                s.close()
+            else:
+                self.assertRaises(ValueError, s.connect, ("svn.python.org", 443))
             # This should fail because we have no verification certs
             ctx.verify_mode = ssl.CERT_REQUIRED
             s = ctx.wrap_socket(socket.socket(socket.AF_INET))
@@ -1500,6 +1515,7 @@ def test_main(verbose=False):
         print("test_ssl: testing with %r %r" %
             (ssl.OPENSSL_VERSION, ssl.OPENSSL_VERSION_INFO))
         print("          under %s" % plat)
+        print("          HAS_SNI = %r" % ssl.HAS_SNI)
 
     for filename in [
         CERTFILE, SVN_PYTHON_ORG_ROOT_CERT, BYTES_CERTFILE,

Lib/test/test_urllib2net.py

@@ -9,6 +9,10 @@ import socket
 import urllib.error
 import urllib.request
 import sys
+try:
+    import ssl
+except ImportError:
+    ssl = None
 
 TIMEOUT = 60  # seconds
 
@@ -278,9 +282,30 @@ class TimeoutTest(unittest.TestCase):
         self.assertEqual(u.fp.fp.raw._sock.gettimeout(), 60)
 
 
+@unittest.skipUnless(ssl, "requires SSL support")
+class HTTPSTests(unittest.TestCase):
+
+    def test_sni(self):
+        # Checks that Server Name Indication works, if supported by the
+        # OpenSSL linked to.
+        # The ssl module itself doesn't have server-side support for SNI,
+        # so we rely on a third-party test site.
+        expect_sni = ssl.HAS_SNI
+        with support.transient_internet("bob.sni.velox.ch"):
+            u = urllib.request.urlopen("https://bob.sni.velox.ch/")
+            contents = u.readall()
+            if expect_sni:
+                self.assertIn(b"Great", contents)
+                self.assertNotIn(b"Unfortunately", contents)
+            else:
+                self.assertNotIn(b"Great", contents)
+                self.assertIn(b"Unfortunately", contents)
+
+
 def test_main():
     support.requires("network")
     support.run_unittest(AuthTests,
+                         HTTPSTests,
                          OtherNetworkTests,
                          CloseSocketTest,
                          TimeoutTest,

Misc/NEWS

@@ -43,6 +43,11 @@ Core and Builtins
 Library
 -------
 
+- Issue #5639: Add a *server_hostname* argument to ``SSLContext.wrap_socket``
+  in order to support the TLS SNI extension.  ``HTTPSConnection`` and
+  ``urlopen()`` also use this argument, so that HTTPS virtual hosts are now
+  supported.
+
 - Issue #10166: Avoid recursion in pstats Stats.add() for many stats items.
 
 - Issue #10163: Skip unreadable registry keys during mimetypes

Modules/_ssl.c

@@ -281,7 +281,8 @@ _setSSLError (char *errstr, int errcode, char *filename, int lineno) {
 
 static PySSLSocket *
 newPySSLSocket(SSL_CTX *ctx, PySocketSockObject *sock,
-               enum py_ssl_server_or_client socket_type)
+               enum py_ssl_server_or_client socket_type,
+               char *server_hostname)
 {
     PySSLSocket *self;
 
@@ -305,6 +306,11 @@ newPySSLSocket(SSL_CTX *ctx, PySocketSockObject *sock,
     SSL_set_mode(self->ssl, SSL_MODE_AUTO_RETRY);
 #endif
 
+#ifdef SSL_CTRL_SET_TLSEXT_HOSTNAME
+    if (server_hostname != NULL)
+        SSL_set_tlsext_host_name(self->ssl, server_hostname);
+#endif
+
     /* If the socket is in non-blocking mode or timeout mode, set the BIO
      * to non-blocking mode (blocking is the default)
      */
@@ -1711,16 +1717,37 @@ load_verify_locations(PySSLContext *self, PyObject *args, PyObject *kwds)
 static PyObject *
 context_wrap_socket(PySSLContext *self, PyObject *args, PyObject *kwds)
 {
-    char *kwlist[] = {"sock", "server_side", NULL};
+    char *kwlist[] = {"sock", "server_side", "server_hostname", NULL};
     PySocketSockObject *sock;
     int server_side = 0;
+    char *hostname = NULL;
+    PyObject *hostname_obj, *res;
 
-    if (!PyArg_ParseTupleAndKeywords(args, kwds, "O!i:_wrap_socket", kwlist,
+    /* server_hostname is either None (or absent), or to be encoded
+       using the idna encoding. */
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "O!i|O!:_wrap_socket", kwlist,
+                                     PySocketModule.Sock_Type,
+                                     &sock, &server_side,
+                                     Py_TYPE(Py_None), &hostname_obj)) {
+        PyErr_Clear();
+        if (!PyArg_ParseTupleAndKeywords(args, kwds, "O!iet:_wrap_socket", kwlist,
             PySocketModule.Sock_Type,
-                                     &sock, &server_side))
+            &sock, &server_side,
+            "idna", &hostname))
             return NULL;
+#ifndef SSL_CTRL_SET_TLSEXT_HOSTNAME
+        PyMem_Free(hostname);
+        PyErr_SetString(PyExc_ValueError, "server_hostname is not supported "
+                        "by your OpenSSL library");
+        return NULL;
+#endif
+    }
 
-    return (PyObject *) newPySSLSocket(self->ctx, sock, server_side);
+    res = (PyObject *) newPySSLSocket(self->ctx, sock, server_side,
+                                      hostname);
+    if (hostname != NULL)
+        PyMem_Free(hostname);
+    return res;
 }
 
 static PyObject *
@@ -2090,6 +2117,14 @@ PyInit__ssl(void)
     PyModule_AddIntConstant(m, "OP_NO_SSLv3", SSL_OP_NO_SSLv3);
     PyModule_AddIntConstant(m, "OP_NO_TLSv1", SSL_OP_NO_TLSv1);
 
+#ifdef SSL_CTRL_SET_TLSEXT_HOSTNAME
+    r = Py_True;
+#else
+    r = Py_False;
+#endif
+    Py_INCREF(r);
+    PyModule_AddObject(m, "HAS_SNI", r);
+
     /* OpenSSL version */
     /* SSLeay() gives us the version of the library linked against,
        which could be different from the headers version.