gh-138252: Add support in SSL module for getting and setting TLS signature algorithms

Doc/library/ssl.rst

@@ -215,6 +215,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
 ^^^^^^^^^^
 
@@ -1297,6 +1316,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``
@@ -1725,6 +1760,35 @@ to speed up repeated connections from the same clients.
 
  .. versionadded:: next
 
+.. 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(protocols)
 
  Specify which protocols the socket should advertise during the SSL/TLS
@@ -2876,7 +2940,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::

Doc/whatsnew/3.15.rst

@@ -433,6 +433,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
 -------

Lib/ssl.py

@@ -13,6 +13,9 @@
 
 Functions:
 
+ get_sigalgs -- return a list of all available TLS signature
+ algorithms (requires OpenSSL 3.4 or later)
+
  cert_time_to_seconds -- convert time string used for certificate
  notBefore and notAfter functions to integer
  seconds past the Epoch (the time values
@@ -112,6 +115,7 @@
 except ImportError:
  # RAND_egd is not supported on some platforms
  pass
+from _ssl import get_sigalgs
 
 
 from _ssl import (
@@ -935,6 +939,14 @@ def group(self):
  """Return the currently selected key agreement group name."""
  return self._sslobj.group()
 
+ def client_sigalg(self):
+ """Return the selected client authentication signature algorithm."""
+ return self._sslobj.client_sigalg()
+
+ def server_sigalg(self):
+ """Return the selected server handshake signature algorithm."""
+ return self._sslobj.server_sigalg()
+
  def shared_ciphers(self):
  """Return a list of ciphers shared by the client during the handshake or
  None if this is not a valid server connection.
@@ -1222,6 +1234,22 @@ def group(self):
  else:
  return self._sslobj.group()
 
+ @_sslcopydoc
+ def client_sigalg(self):
+ self._checkClosed()
+ if self._sslobj is None:
+ return None
+ else:
+ return self._sslobj.client_sigalg()
+
+ @_sslcopydoc
+ def server_sigalg(self):
+ self._checkClosed()
+ if self._sslobj is None:
+ return None
+ else:
+ return self._sslobj.server_sigalg()
+
  @_sslcopydoc
  def shared_ciphers(self):
  self._checkClosed()

Lib/test/test_ssl.py

@@ -51,6 +51,10 @@
 CAN_GET_SELECTED_OPENSSL_GROUP = ssl.OPENSSL_VERSION_INFO >= (3, 2)
 CAN_IGNORE_UNKNOWN_OPENSSL_GROUPS = ssl.OPENSSL_VERSION_INFO >= (3, 3)
 CAN_GET_AVAILABLE_OPENSSL_GROUPS = ssl.OPENSSL_VERSION_INFO >= (3, 5)
+CAN_GET_AVAILABLE_OPENSSL_SIGALGS = ssl.OPENSSL_VERSION_INFO >= (3, 4)
+CAN_SET_CLIENT_SIGALGS = "AWS-LC" not in ssl.OPENSSL_VERSION
+CAN_IGNORE_UNKNOWN_OPENSSL_SIGALGS = ssl.OPENSSL_VERSION_INFO >= (3, 3)
+CAN_GET_SELECTED_OPENSSL_SIGALG = ssl.OPENSSL_VERSION_INFO >= (3, 5)
 PY_SSL_DEFAULT_CIPHERS = sysconfig.get_config_var('PY_SSL_DEFAULT_CIPHERS')
 
 PROTOCOL_TO_TLS_VERSION = {}
@@ -294,7 +298,8 @@ def test_wrap_socket(sock, *,
 USE_SAME_TEST_CONTEXT = False
 _TEST_CONTEXT = None
 
-def testing_context(server_cert=SIGNED_CERTFILE, *, server_chain=True):
+def testing_context(server_cert=SIGNED_CERTFILE, *, server_chain=True,
+ client_cert=None):
  """Create context
 
  client_context, server_context, hostname = testing_context()
@@ -321,6 +326,10 @@ def testing_context(server_cert=SIGNED_CERTFILE, *, server_chain=True):
  if server_chain:
  server_context.load_verify_locations(SIGNING_CA)
 
+ if client_cert:
+ client_context.load_cert_chain(client_cert)
+ server_context.verify_mode = ssl.CERT_REQUIRED
+
  if USE_SAME_TEST_CONTEXT:
  if _TEST_CONTEXT is not None:
  _TEST_CONTEXT = client_context, server_context, hostname
@@ -990,6 +999,37 @@ def test_get_groups(self):
  self.assertNotIn('P-256', ctx.get_groups())
  self.assertIn('P-256', ctx.get_groups(include_aliases=True))
 
+ @unittest.skipUnless(CAN_GET_AVAILABLE_OPENSSL_SIGALGS,
+ "SSL library doesn't support getting sigalgs")
+ def test_get_sigalgs(self):
+ self.assertIn('rsa_pss_rsae_sha256', ssl.get_sigalgs())
+
+ @unittest.skipUnless(CAN_SET_CLIENT_SIGALGS,
+ "SSL library doesn't support setting client sigalgs")
+ def test_set_client_sigalgs(self):
+ ctx = ssl.create_default_context()
+
+ self.assertIsNone(ctx.set_client_sigalgs('rsa_pss_rsae_sha256'))
+
+ self.assertRaises(ssl.SSLError, ctx.set_client_sigalgs,
+ 'rsa_pss_rsae_sha256:foo')
+
+ # Ignoring unknown sigalgs is only supported since OpenSSL 3.3.
+ if CAN_IGNORE_UNKNOWN_OPENSSL_SIGALGS:
+ self.assertIsNone(ctx.set_client_sigalgs('rsa_pss_rsae_sha256:?foo'))
+
+ def test_set_server_sigalgs(self):
+ ctx = ssl.create_default_context()
+
+ self.assertIsNone(ctx.set_server_sigalgs('rsa_pss_rsae_sha256'))
+
+ self.assertRaises(ssl.SSLError, ctx.set_server_sigalgs,
+ 'rsa_pss_rsae_sha256:foo')
+
+ # Ignoring unknown sigalgs is only supported since OpenSSL 3.3.
+ if CAN_IGNORE_UNKNOWN_OPENSSL_SIGALGS:
+ self.assertIsNone(ctx.set_server_sigalgs('rsa_pss_rsae_sha256:?foo'))
+
  def test_options(self):
  # Test default SSLContext options
  ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
@@ -2814,6 +2854,9 @@ def server_params_test(client_context, server_context, indata=b"FOO\n",
  })
  if CAN_GET_SELECTED_OPENSSL_GROUP:
  stats.update({'group': s.group()})
+ if CAN_GET_SELECTED_OPENSSL_SIGALG:
+ stats.update({'client_sigalg': s.client_sigalg()})
+ stats.update({'server_sigalg': s.server_sigalg()})
  s.close()
  stats['server_alpn_protocols'] = server.selected_alpn_protocols
  stats['server_shared_ciphers'] = server.shared_ciphers
@@ -4273,6 +4316,71 @@ def test_groups(self):
  chatty=True, connectionchatty=True,
  sni_name=hostname)
 
+ @unittest.skipUnless(CAN_SET_CLIENT_SIGALGS,
+ "SSL library doesn't support setting client sigalgs")
+ def test_client_sigalgs(self):
+ # no mutual auth, so cient_sigalg should be None
+ client_context, server_context, hostname = testing_context()
+ stats = server_params_test(client_context, server_context,
+ chatty=True, connectionchatty=True,
+ sni_name=hostname)
+ if CAN_GET_SELECTED_OPENSSL_SIGALG:
+ self.assertIsNone(stats['client_sigalg'])
+
+ # server auto, client rsa_pss_rsae_sha384
+ sigalg = "rsa_pss_rsae_sha384"
+ client_context, server_context, hostname = \
+ testing_context(client_cert=SIGNED_CERTFILE)
+ client_context.set_client_sigalgs(sigalg)
+ stats = server_params_test(client_context, server_context,
+ chatty=True, connectionchatty=True,
+ sni_name=hostname)
+ if CAN_GET_SELECTED_OPENSSL_SIGALG:
+ self.assertEqual(stats['client_sigalg'], sigalg)
+
+ @unittest.skipUnless(CAN_SET_CLIENT_SIGALGS,
+ "SSL library doesn't support setting client sigalgs")
+ def test_client_sigalgs_mismatch(self):
+ client_context, server_context, hostname = \
+ testing_context(client_cert=SIGNED_CERTFILE)
+ client_context.set_client_sigalgs("rsa_pss_rsae_sha256")
+ server_context.set_client_sigalgs("rsa_pss_rsae_sha384")
+
+ # Some systems return ConnectionResetError on handshake failures
+ with self.assertRaises((ssl.SSLError, ConnectionResetError)):
+ server_params_test(client_context, server_context,
+ chatty=True, connectionchatty=True,
+ sni_name=hostname)
+
+ def test_server_sigalgs(self):
+ # server rsa_pss_rsae_sha384, client auto
+ sigalg = "rsa_pss_rsae_sha384"
+ client_context, server_context, hostname = testing_context()
+ server_context.set_server_sigalgs(sigalg)
+ stats = server_params_test(client_context, server_context,
+ chatty=True, connectionchatty=True,
+ sni_name=hostname)
+ if CAN_GET_SELECTED_OPENSSL_SIGALG:
+ self.assertEqual(stats['server_sigalg'], sigalg)
+
+ # server auto, client rsa_pss_rsae_sha384
+ client_context, server_context, hostname = testing_context()
+ client_context.set_server_sigalgs(sigalg)
+ stats = server_params_test(client_context, server_context,
+ chatty=True, connectionchatty=True,
+ sni_name=hostname)
+ if CAN_GET_SELECTED_OPENSSL_SIGALG:
+ self.assertEqual(stats['server_sigalg'], sigalg)
+
+ def test_server_sigalgs_mismatch(self):
+ client_context, server_context, hostname = testing_context()
+ client_context.set_server_sigalgs("rsa_pss_rsae_sha256")
+ server_context.set_server_sigalgs("rsa_pss_rsae_sha384")
+ with self.assertRaises(ssl.SSLError):
+ server_params_test(client_context, server_context,
+ chatty=True, connectionchatty=True,
+ sni_name=hostname)
+
  def test_selected_alpn_protocol(self):
  # selected_alpn_protocol() is None unless ALPN is used.
  client_context, server_context, hostname = testing_context()

Misc/NEWS.d/next/Library/2025-08-30-17-58-04.gh-issue-138252.CDiEby.rst

@@ -0,0 +1,4 @@
+:mod:`ssl`: :class:`~ssl.SSLContext` objects can now set client and server
+TLS signature algorithms. If Python has been built with OpenSSL 3.5 or later,
+:class:`~ssl.SSLSocket` objects can return the signature algorithms selected
+on a connection.