bpo-34271: Add ssl debugging helpers (GH-10031)
The ssl module now can dump key material to a keylog file and trace TLS
protocol messages with a tracing callback. The default and stdlib
contexts also support SSLKEYLOGFILE env var.
The msg_callback and related enums are private members. The feature
is designed for internal debugging and not for end users.
Signed-off-by: Christian Heimes <christian@python.org>
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 20f5724..be09f38 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -139,6 +139,10 @@
*cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load
default CA certificates.
+ When :attr:`~SSLContext.keylog_filename` is supported and the environment
+ variable :envvar:`SSLKEYLOGFILE` is set, :func:`create_default_context`
+ enables key logging.
+
.. note::
The protocol, options, cipher and other settings may change to more
restrictive values anytime without prior deprecation. The values
@@ -172,6 +176,10 @@
3DES was dropped from the default cipher string.
+ .. versionchanged:: 3.8
+
+ Support for key logging to :envvar:`SSLKEYLOGFILE` was added.
+
Exceptions
^^^^^^^^^^
@@ -1056,6 +1064,7 @@
SSL 3.0 to TLS 1.3.
+
SSL Sockets
-----------
@@ -1901,6 +1910,20 @@
This features requires OpenSSL 0.9.8f or newer.
+.. attribute:: SSLContext.keylog_filename
+
+ Write TLS keys to a keylog file, whenever key material is generated or
+ received. The keylog file is designed for debugging purposes only. The
+ file format is specified by NSS and used by many traffic analyzers such
+ as Wireshark. The log file is opened in append-only mode. Writes are
+ synchronized between threads, but not between processes.
+
+ .. versionadded:: 3.8
+
+ .. note::
+
+ This features requires OpenSSL 1.1.1 or newer.
+
.. attribute:: SSLContext.maximum_version
A :class:`TLSVersion` enum member representing the highest supported