Skip to content

[pull] main from python:main #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 5 commits into from
Sep 8, 2025
Merged

[pull] main from python:main #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
919c7e8
GH-123299: Copyedit 3.14 What's New: Build Changes (#138488)
AA-Turner Sep 8, 2025
6401823
gh-138252: Add support in SSL module for getting and setting TLS sign…
ronf Sep 8, 2025
057ee17
gh-136264: Fix ``--relative-paths`` for PEP 739's build-details.json …
AA-Turner Sep 8, 2025
3255c0c
gh-138633: synchronize documented signatures of SSL objects with runt…
picnixz Sep 8, 2025
097c563
gh-137210: Move PYTHON_API_VERSION & PYTHON_ABI_VERSION to patchlevel…
encukou Sep 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 89 additions & 21 deletions Doc/library/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,8 @@ Context creation
A convenience function helps create :class:`SSLContext` objects for common
purposes.

.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, *,\
cafile=None, capath=None, cadata=None)

Return a new :class:`SSLContext` object with default settings for
the given *purpose*. The settings are chosen by the :mod:`ssl` module,
Expand Down Expand Up @@ -215,6 +216,25 @@ purposes.
:data:`VERIFY_X509_STRICT` in its default verify flags.


Signature algorithms
^^^^^^^^^^^^^^^^^^^^

.. function:: get_sigalgs()

Return a list of available TLS signature algorithm names used
by servers to complete the TLS handshake or clients requesting
certificate-based authentication. For example::

>>> ssl.get_sigalgs() # doctest: +SKIP
['ecdsa_secp256r1_sha256', 'ecdsa_secp384r1_sha384', ...]

These names can be used when building string values to pass to the
:meth:`SSLContext.set_client_sigalgs` and
:meth:`SSLContext.set_server_sigalgs` methods.

.. versionadded:: next


Exceptions
^^^^^^^^^^

Expand Down Expand Up @@ -314,7 +334,7 @@ Exceptions
Random generation
^^^^^^^^^^^^^^^^^

.. function:: RAND_bytes(num)
.. function:: RAND_bytes(num, /)

Return *num* cryptographically strong pseudo-random bytes. Raises an
:class:`SSLError` if the PRNG has not been seeded with enough data or if the
Expand All @@ -338,7 +358,7 @@ Random generation
:func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness of
the pseudo-random number generator.

.. function:: RAND_add(bytes, entropy)
.. function:: RAND_add(bytes, entropy, /)

Mix the given *bytes* into the SSL pseudo-random number generator. The
parameter *entropy* (a float) is a lower bound on the entropy contained in
Expand Down Expand Up @@ -406,12 +426,12 @@ Certificate handling
.. versionchanged:: 3.10
The *timeout* parameter was added.

.. function:: DER_cert_to_PEM_cert(DER_cert_bytes)
.. function:: DER_cert_to_PEM_cert(der_cert_bytes)

Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
string version of the same certificate.

.. function:: PEM_cert_to_DER_cert(PEM_cert_string)
.. function:: PEM_cert_to_DER_cert(pem_cert_string)

Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
bytes for that same certificate.
Expand Down Expand Up @@ -1141,10 +1161,10 @@ SSL sockets also have the following additional methods and attributes:
.. deprecated:: 3.6
Use :meth:`~SSLSocket.recv` instead of :meth:`~SSLSocket.read`.

.. method:: SSLSocket.write(buf)
.. method:: SSLSocket.write(data)

Write *buf* to the SSL socket and return the number of bytes written. The
*buf* argument must be an object supporting the buffer interface.
Write *data* to the SSL socket and return the number of bytes written. The
*data* argument must be an object supporting the buffer interface.

Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is
:ref:`non-blocking <ssl-nonblocking>` and the write would block.
Expand All @@ -1154,7 +1174,7 @@ SSL sockets also have the following additional methods and attributes:

.. versionchanged:: 3.5
The socket timeout is no longer reset each time bytes are received or sent.
The socket timeout is now the maximum total duration to write *buf*.
The socket timeout is now the maximum total duration to write *data*.

.. deprecated:: 3.6
Use :meth:`~SSLSocket.send` instead of :meth:`~SSLSocket.write`.
Expand All @@ -1171,10 +1191,13 @@ SSL sockets also have the following additional methods and attributes:
:meth:`~socket.socket.recv` and :meth:`~socket.socket.send` instead of these
methods.

.. method:: SSLSocket.do_handshake()
.. method:: SSLSocket.do_handshake(block=False)

Perform the SSL setup handshake.

If *block* is true and the timeout obtained by :meth:`~socket.gettimeout`
is zero, the socket is set in blocking mode until the handshake is performed.

.. versionchanged:: 3.4
The handshake method also performs :func:`match_hostname` when the
:attr:`~SSLContext.check_hostname` attribute of the socket's
Expand Down Expand Up @@ -1297,6 +1320,22 @@ SSL sockets also have the following additional methods and attributes:

.. versionadded:: next

.. method:: SSLSocket.client_sigalg()

Return the signature algorithm used for performing certificate-based client
authentication on this connection, or ``None`` if no connection has been
established or client authentication didn't occur.

.. versionadded:: next

.. method:: SSLSocket.server_sigalg()

Return the signature algorithm used by the server to complete the TLS
handshake on this connection, or ``None`` if no connection has been
established or the cipher suite has no signature.

.. versionadded:: next

.. method:: SSLSocket.compression()

Return the compression algorithm being used as a string, or ``None``
Expand Down Expand Up @@ -1682,7 +1721,7 @@ to speed up repeated connections from the same clients.
provided as part of the operating system, though, it is likely to be
configured properly.

.. method:: SSLContext.set_ciphers(ciphers)
.. method:: SSLContext.set_ciphers(ciphers, /)

Set the allowed ciphers for sockets created with this context when
connecting using TLS 1.2 and earlier. The *ciphers* argument should
Expand All @@ -1698,7 +1737,7 @@ to speed up repeated connections from the same clients.
When connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
return details about the negotiated cipher.

.. method:: SSLContext.set_ciphersuites(ciphersuites)
.. method:: SSLContext.set_ciphersuites(ciphersuites, /)

Set the allowed ciphers for sockets created with this context when
connecting using TLS 1.3. The *ciphersuites* argument should be a
Expand All @@ -1712,7 +1751,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: next

.. method:: SSLContext.set_groups(groups)
.. method:: SSLContext.set_groups(groups, /)

Set the groups allowed for key agreement for sockets created with this
context. It should be a string in the `OpenSSL group list format
Expand All @@ -1725,7 +1764,36 @@ to speed up repeated connections from the same clients.

.. versionadded:: next

.. method:: SSLContext.set_alpn_protocols(protocols)
.. method:: SSLContext.set_client_sigalgs(sigalgs, /)

Set the signature algorithms allowed for certificate-based client
authentication. It should be a string in the `OpenSSL client sigalgs
list format
<https://docs.openssl.org/master/man3/SSL_CTX_set1_client_sigalgs_list/>`_.

.. note::

When connected, the :meth:`SSLSocket.client_sigalg` method of SSL
sockets will return the signature algorithm used for performing
certificate-based client authentication on that connection.

.. versionadded:: next

.. method:: SSLContext.set_server_sigalgs(sigalgs, /)

Set the signature algorithms allowed for the server to complete the TLS
handshake. It should be a string in the `OpenSSL sigalgs list format
<https://docs.openssl.org/master/man3/SSL_CTX_set1_sigalgs_list/>`_.

.. note::

When connected, the :meth:`SSLSocket.server_sigalg` method of SSL
sockets will return the signature algorithm used by the server to
complete the TLS handshake on that connection.

.. versionadded:: next

.. method:: SSLContext.set_alpn_protocols(alpn_protocols)

Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of ASCII strings, like ``['http/1.1',
Expand All @@ -1739,7 +1807,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.5

.. method:: SSLContext.set_npn_protocols(protocols)
.. method:: SSLContext.set_npn_protocols(npn_protocols)

Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``,
Expand Down Expand Up @@ -1806,7 +1874,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.7

.. attribute:: SSLContext.set_servername_callback(server_name_callback)
.. method:: SSLContext.set_servername_callback(server_name_callback)

This is a legacy API retained for backwards compatibility. When possible,
you should use :attr:`sni_callback` instead. The given *server_name_callback*
Expand All @@ -1820,7 +1888,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.4

.. method:: SSLContext.load_dh_params(dhfile)
.. method:: SSLContext.load_dh_params(dhfile, /)

Load the key generation parameters for Diffie-Hellman (DH) key exchange.
Using DH key exchange improves forward secrecy at the expense of
Expand All @@ -1833,7 +1901,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.3

.. method:: SSLContext.set_ecdh_curve(curve_name)
.. method:: SSLContext.set_ecdh_curve(curve_name, /)

Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
exchange. ECDH is significantly faster than regular DH while arguably
Expand Down Expand Up @@ -2707,12 +2775,12 @@ purpose. It wraps an OpenSSL memory BIO (Basic IO) object:
A boolean indicating whether the memory BIO is current at the end-of-file
position.

.. method:: MemoryBIO.read(n=-1)
.. method:: MemoryBIO.read(n=-1, /)

Read up to *n* bytes from the memory buffer. If *n* is not specified or
negative, all bytes are returned.

.. method:: MemoryBIO.write(buf)
.. method:: MemoryBIO.write(buf, /)

Write the bytes from *buf* to the memory BIO. The *buf* argument must be an
object supporting the buffer protocol.
Expand Down Expand Up @@ -2876,7 +2944,7 @@ of TLS/SSL. Some new TLS 1.3 features are not yet available.
process certificate requests while they send or receive application data
from the server.
- TLS 1.3 features like early data, deferred TLS client cert request,
signature algorithm configuration, and rekeying are not supported yet.
and rekeying are not supported yet.


.. seealso::
Expand Down
91 changes: 67 additions & 24 deletions Doc/whatsnew/3.14.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ and improvements in user-friendliness and correctness.
* :ref:`PEP 741: Python configuration C API <whatsnew314-pep741>`
* :ref:`PEP 750: Template strings <whatsnew314-pep750>`
* :ref:`PEP 758: Allow except and except* expressions without parentheses <whatsnew314-pep758>`
* :ref:`PEP 761: Discontinuation of PGP signatures <whatsnew314-pep761>`
* :ref:`PEP 761: Discontinuation of PGP signatures <whatsnew314-no-more-pgp>`
* :ref:`PEP 765: Disallow return/break/continue that exit a finally block <whatsnew314-pep765>`
* :ref:`Free-threaded mode improvements <whatsnew314-free-threaded-cpython>`
* :ref:`PEP 768: Safe external debugger interface for CPython <whatsnew314-pep768>`
Expand Down Expand Up @@ -2820,29 +2820,6 @@ CPython bytecode changes
(Contributed by Irit Katriel in :gh:`100239`.)


Build changes
=============

* GNU Autoconf 2.72 is now required to generate :file:`configure`.
(Contributed by Erlend Aasland in :gh:`115765`.)

* ``#pragma``-based linking with ``python3*.lib`` can now be switched off
with :c:expr:`Py_NO_LINK_LIB`. (Contributed by Jean-Christophe
Fillion-Robin in :gh:`82909`.)

.. _whatsnew314-pep761:

PEP 761: Discontinuation of PGP signatures
------------------------------------------

PGP signatures will not be available for CPython 3.14 and onwards.
Users verifying artifacts must use `Sigstore verification materials`_ for
verifying CPython artifacts. This change in release process is specified
in :pep:`761`.

.. _Sigstore verification materials: https://www.python.org/downloads/metadata/sigstore/


C API changes
=============

Expand Down Expand Up @@ -3120,6 +3097,72 @@ Removed
(Removed in :gh:`133079`, see also :gh:`130396`.)


Build Changes
=============

* GNU Autoconf 2.72 is now required to generate :file:`configure`.
(Contributed by Erlend Aasland in :gh:`115765`.)

* ``wasm32-unknown-emscripten`` is now a :pep:`11` tier 3 platform.
(Contributed by R. Hood Chatham in :gh:`127146`, :gh:`127683`, and :gh:`136931`.)

* ``#pragma``-based linking with ``python3*.lib`` can now be switched off
with :c:expr:`Py_NO_LINK_LIB`.
(Contributed by Jean-Christophe Fillion-Robin in :gh:`82909`.)

* CPython now enables a set of recommended compiler options by default
for improved security.
Use the :option:`--disable-safety` :file:`configure` option to disable them,
or the :option:`--enable-slower-safety` option for a larger set
of compiler options, albeit with a performance cost.

* The ``WITH_FREELISTS`` macro and ``--without-freelists`` :file:`configure`
option have been removed.

* The new :file:`configure` option :option:`--with-tail-call-interp`
may be used to enable the experimental tail call interpreter.
See :ref:`whatsnew314-tail-call` for further details.

* To disable the new remote debugging support, use the
:option:`--without-remote-debug` :file:`configure` option.
This may be useful for security reasons.

.. _whatsnew314-build_details:

:file:`build-details.json`
--------------------------

Installations of Python now contain a new file, :file:`build-details.json`.
This is a static JSON document containing build details for CPython,
to allow for introspection without needing to run code.
This is helpful for use-cases such as Python launchers, cross-compilation,
and so on.

:file:`build-details.json` must be installed in the platform-independent
standard library directory. This corresponds to the :ref:`'stdlib'
<installation_paths>` :mod:`sysconfig` installation path,
which can be found by running ``sysconfig.get_path('stdlib')``.

.. seealso::
:pep:`739` -- ``build-details.json`` 1.0 -- a static description file
for Python build details

.. _whatsnew314-no-more-pgp:

Discontinuation of PGP signatures
---------------------------------

PGP (Pretty Good Privacy) signatures will not be provided
for releases of Python 3.14 or future versions.
To verify CPython artifacts, users must use `Sigstore verification materials
<https://www.python.org/downloads/metadata/sigstore/>`__.
Releases have been signed using Sigstore_ since Python 3.11.

This change in release process was specified in :pep:`761`.

.. _Sigstore: https://www.sigstore.dev/


Porting to Python 3.14
======================

Expand Down
17 changes: 17 additions & 0 deletions Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,23 @@ ssl
connection is made.
(Contributed by Ron Frederick in :gh:`137197`.)

* Added new methods for managing signature algorithms:

* :func:`ssl.get_sigalgs` returns a list of all available TLS signature
algorithms. This call requires OpenSSL 3.4 or later.
* :meth:`ssl.SSLContext.set_client_sigalgs` sets the signature algorithms
allowed for certificate-based client authentication.
* :meth:`ssl.SSLContext.set_server_sigalgs` sets the signature algorithms
allowed for the server to complete the TLS handshake.
* :meth:`ssl.SSLSocket.client_sigalg` returns the signature algorithm
selected for client authentication on the current connection. This call
requires OpenSSL 3.5 or later.
* :meth:`ssl.SSLSocket.server_sigalg` returns the signature algorithm
selected for the server to complete the TLS handshake on the current
connection. This call requires OpenSSL 3.5 or later.

(Contributed by Ron Frederick in :gh:`138252`.)


tarfile
-------
Expand Down
Loading
Loading