Merge pull request #244 from elitest/session-tls-version

Add support for querying the negotiated TLS version

ChangeLog

@@ -1,3 +1,9 @@
+2015-05-27  Jim Shaver <dcypherd@gmail.com>
+
+	* OpenSSL/SSL.py, : Add ``get_protocol_version()`` and 
+	  ``get_protocol_version_name()`` to ``Connection``.
+	  Based on work from Rich Moore.
+
 2015-05-02  Jim Shaver <dcypherd@gmail.com>
 
 	* .travis.yml, setup.py, tox.ini: Removed support for Python 3.2.

OpenSSL/SSL.py

@@ -1883,6 +1883,31 @@ def get_cipher_version(self):
             return version.decode("utf-8")
 
 
+    def get_protocol_version_name(self):
+        """
+        Obtain the protocol version of the current connection.
+
+        :returns: The TLS version of the current connection, for example
+            the value for TLS 1.2 would be ``TLSv1.2``or ``Unknown``
+            for connections that were not successfully established.
+        :rtype: :py:class:`unicode`
+        """
+        version = _ffi.string(_lib.SSL_get_version(self._ssl))
+        return version.decode("utf-8")
+
+
+    def get_protocol_version(self):
+        """
+        Obtain the protocol version of the current connection.
+
+        :returns: The TLS version of the current connection, for example
+            the value for TLS 1 would be 0x769.
+        :rtype: :py:class:`int`
+        """
+        version = _lib.SSL_version(self._ssl)
+        return version
+
+
     @_requires_npn
     def get_next_proto_negotiated(self):
         """

OpenSSL/test/test_ssl.py

@@ -2745,6 +2745,36 @@ def test_get_cipher_bits(self):
         self.assertEqual(server_cipher_bits, client_cipher_bits)
 
 
+    def test_get_protocol_version_name(self):
+        """
+        :py:obj:`Connection.get_protocol_version_name()` returns a string
+        giving the protocol version of the current connection.
+        """
+        server, client = self._loopback()
+        client_protocol_version_name = client.get_protocol_version_name()
+        server_protocol_version_name = server.get_protocol_version_name()
+
+        self.assertIsInstance(server_protocol_version_name, text_type)
+        self.assertIsInstance(client_protocol_version_name, text_type)
+
+        self.assertEqual(server_protocol_version_name, client_protocol_version_name)
+
+
+    def test_get_protocol_version(self):
+        """
+        :py:obj:`Connection.get_protocol_version()` returns an integer 
+        giving the protocol version of the current connection.
+        """
+        server, client = self._loopback()
+        client_protocol_version = client.get_protocol_version()
+        server_protocol_version = server.get_protocol_version()
+
+        self.assertIsInstance(server_protocol_version, int)
+        self.assertIsInstance(client_protocol_version, int)
+
+        self.assertEqual(server_protocol_version, client_protocol_version)
+
+
 
 class ConnectionGetCipherListTests(TestCase):
     """

doc/api/ssl.rst

@@ -598,6 +598,21 @@ Connection objects have the following methods:
     but not it returns the entire list in one go.
 
 
+.. py:method:: Connection.get_protocol_version()
+
+    Retrieve the version of the SSL or TLS protocol used by the Connection.
+    For example, it will return ``0x769`` for connections made over TLS
+    version 1.
+
+
+.. py:method:: Connection.get_protocol_version_name()
+
+    Retrieve the version of the SSL or TLS protocol used by the Connection as
+    a unicode string. For example, it will return ``TLSv1`` for connections
+    made over TLS version 1, or ``Unknown`` for connections that were not 
+    successfully established.
+
+
 .. py:method:: Connection.get_client_ca_list()
 
     Retrieve the list of preferred client certificate issuers sent by the server