From 8d8ed7f6e1d09016910cd250bb30788959ca0675 Mon Sep 17 00:00:00 2001
From: mm-matthias <43849132+mm-matthias@users.noreply.github.com>
Date: Sun, 16 Jun 2024 22:27:44 +0200
Subject: [PATCH] gh-118596: Add thread-safety clarifications to the SSLContext
 documentation (#118597)

Add thread-safety clarifications to the SSLContext documentation. Per the issue:

This issue has also come up [here](https://github.com/psf/requests/pull/6667) where the matter was clarified by @tiran in [this comment](https://github.com/psf/requests/pull/6667):
> `SSLContext` is designed to be shared and used for multiple connections. It is thread safe as long as you don't reconfigure it once it is used by a connection. Adding new certs to the internal trust store is fine, but changing ciphers, verification settings, or mTLS certs can lead to surprising behavior. The problem is unrelated to threads and can even occur in a single-threaded program.
---
 Doc/library/ssl.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 99abf45469018ea..dc72f67c6361e20 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -1472,6 +1472,19 @@ to speed up repeated connections from the same clients.
       :data:`PROTOCOL_TLS`, :data:`PROTOCOL_TLS_CLIENT`, and
       :data:`PROTOCOL_TLS_SERVER` use TLS 1.2 as minimum TLS version.
 
+   .. note::
+
+      :class:`SSLContext` only supports limited mutation once it has been used
+      by a connection. Adding new certificates to the internal trust store is
+      allowed, but changing ciphers, verification settings, or mTLS
+      certificates may result in surprising behavior.
+
+   .. note::
+
+      :class:`SSLContext` is designed to be shared and used by multiple
+      connections.
+      Thus, it is thread-safe as long as it is not reconfigured after being
+      used by a connection.
 
 :class:`SSLContext` objects have the following methods and attributes: