Doc: document OpenSSL 3 behaviour of the ssl module

- Describe the supported OpenSSL range (1.0.2 - 3.x) and the behaviour
  differences with OpenSSL 3: TLS 1.0/1.1 need a lowered security
  level, version-pinned PROTOCOL_TLSv1* contexts (and that, as before,
  they override a system-wide MinProtocol), OP_IGNORE_UNEXPECTED_EOF
  being on by default, and load_dh_params() errors coming from
  OSSL_DECODER.
- OP_IGNORE_UNEXPECTED_EOF: say that it is enabled by default, explain
  the truncation risk and how to turn it off, and fix the
  "versionadded:: 3.10" which is wrong for this backport.
- Add a NEWS entry summarising the OpenSSL 3 API port.

Patch: python36-OpenSSL-32-documentation.patch

Author: mcepl

Doc/library/ssl.rst

@@ -28,6 +28,26 @@ probably additional platforms, as long as OpenSSL is installed on that platform.
    cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with
    openssl version 1.0.1.
 
+.. note::
+
+   This build of the module requires OpenSSL 1.0.2 or newer and supports
+   OpenSSL 3. When built against OpenSSL 3, only the OpenSSL 3.0 API is
+   used. Notable differences with OpenSSL 3:
+
+   * OpenSSL 3 refuses TLS 1.0 and TLS 1.1 at the default security level.
+     :data:`PROTOCOL_TLSv1` and :data:`PROTOCOL_TLSv1_1` contexts only
+     work after lowering it, e.g. with
+     ``context.set_ciphers("@SECLEVEL=0:ALL")``.
+   * :data:`PROTOCOL_TLSv1`, :data:`PROTOCOL_TLSv1_1` and
+     :data:`PROTOCOL_TLSv1_2` contexts are created from the generic TLS
+     method with both the minimum and maximum protocol version set to the
+     requested version. Like the version-specific methods used with
+     older OpenSSL, this overrides a ``MinProtocol`` set in the system-wide
+     OpenSSL configuration.
+   * :data:`OP_IGNORE_UNEXPECTED_EOF` is enabled by default.
+   * Errors from :meth:`SSLContext.load_dh_params` are reported by the
+     ``OSSL_DECODER`` library instead of ``PEM``.
+
 .. warning::
    Don't use this module without reading the :ref:`ssl-security`.  Doing so
    may lead to a false sense of security, as the default settings of the
@@ -846,11 +866,24 @@ Constants
 
 .. data:: OP_IGNORE_UNEXPECTED_EOF
 
-   Ignore unexpected shutdown of TLS connections.
+   Ignore unexpected shutdown of TLS connections: an EOF from the peer
+   without a TLS ``close_notify`` alert is treated like a regular
+   shutdown instead of raising :exc:`SSLEOFError`. This mirrors the
+   behaviour of OpenSSL 1.1.1 and is enabled by default on every
+   :class:`SSLContext`.
+
+   .. warning::
+
+      With this option an attacker able to close the connection can
+      truncate the data stream without being detected. Protocols that do
+      not delimit their messages themselves (e.g. HTTP/1.0 responses
+      without ``Content-Length``) should clear it:
+      ``context.options &= ~ssl.OP_IGNORE_UNEXPECTED_EOF``.
 
    This option is only available with OpenSSL 3.0.0 and later.
 
-   .. versionadded:: 3.10
+   .. versionadded:: 3.6.15
+      Backported for OpenSSL 3 support (added in Python 3.10).
 
 .. data:: HAS_ALPN
 

Misc/NEWS.d/next/Library/2026-09-25-00-00-00.bpo-43788.oSSL3a.rst

@@ -0,0 +1,6 @@
+The :mod:`ssl` and :mod:`hashlib` modules build against OpenSSL 1.0.2
+through 3.x. When built against OpenSSL 3 they use only the OpenSSL 3.0
+API: version-specific TLS methods, ``DH``/``EC_KEY`` parameter handling,
+``RAND_pseudo_bytes()`` and other deprecated functions are replaced, and
+digests are fetched from providers with ``EVP_MD_fetch()``. Certificate
+verification errors now include the reason for the failure.