TLS: add CURLOPT_SSL_SIGNATURE_ALGORITHMS and --sigalgs

Fixes #12982
Closes #16964

docs/TODO

@@ -122,7 +122,6 @@
  13.11 Some TLS options are not offered for HTTPS proxies
  13.13 Make sure we forbid TLS 1.3 post-handshake authentication
  13.14 Support the clienthello extension
- 13.15 Select signature algorithms
  13.16 Share the CA cache
  13.17 Add missing features to TLS backends
 
@@ -900,14 +899,6 @@
  https://datatracker.ietf.org/doc/html/rfc7685
  https://github.com/curl/curl/issues/2299
 
-13.15 Select signature algorithms
-
- Consider adding an option or a way for users to select TLS signature
- algorithm. The signature algorithms set by a client are used directly in the
- supported signature algorithm in the client hello message.
-
- https://github.com/curl/curl/issues/12982
-
 13.16 Share the CA cache
 
  For TLS backends that supports CA caching, it makes sense to allow the share

docs/cmdline-opts/Makefile.inc

@@ -253,6 +253,7 @@ DPAGES = \
   show-error.md \
   show-headers.md \
   silent.md \
+  sigalgs.md \
   skip-existing.md \
   socks4.md \
   socks4a.md \

docs/cmdline-opts/sigalgs.md

@@ -0,0 +1,33 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+SPDX-License-Identifier: curl
+Long: sigalgs
+Arg: <list>
+Help: TLS signature algorithms to use
+Protocols: TLS
+Added: 8.14.0
+Category: tls
+Multi: single
+See-also:
+  - ciphers
+Example:
+  - --sigalgs ecdsa_secp256r1_sha256 $URL
+---
+
+# `--sigalgs`
+
+Set specific signature algorithms to use during SSL session establishment according to RFC
+5246, 7.4.1.4.1.
+
+An algorithm can use either a signature algorithm and a hash algorithm pair separated by a
+`+` (e.g. `ECDSA+SHA224`), or its TLS 1.3 signature scheme name (e.g. `ed25519`).
+
+Multiple algorithms can be provided by separating them with `:`
+(e.g. `DSA+SHA256:rsa_pss_pss_sha256`). The parameter is available as `-sigalgs` in the
+OpenSSL `s_client` and `s_server` utilities.
+
+`--sigalgs` allows a OpenSSL powered curl to make SSL-connections with exactly
+the signature algorithms requested by the client, avoiding nontransparent client/server
+negotiations.
+
+If this option is set, the default signature algorithm list built into OpenSSL are ignored.

docs/libcurl/curl_easy_setopt.md

@@ -1128,6 +1128,10 @@ Control SSL behavior. See CURLOPT_SSL_OPTIONS(3)
 
 Disable SSL session-id cache. See CURLOPT_SSL_SESSIONID_CACHE(3)
 
+## CURLOPT_SSL_SIGNATURE_ALGORITHMS
+
+TLS signature algorithms to use. See CURLOPT_SSL_SIGNATURE_ALGORITHMS(3)
+
 ## CURLOPT_SSL_VERIFYHOST
 
 Verify the hostname in the SSL certificate. See CURLOPT_SSL_VERIFYHOST(3)

docs/libcurl/opts/CURLOPT_SSL_SIGNATURE_ALGORITHMS.md

@@ -0,0 +1,84 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+SPDX-License-Identifier: curl
+Title: CURLOPT_SSL_SIGNATURE_ALGORITHMS
+Section: 3
+Source: libcurl
+See-also:
+  - CURLOPT_SSL_CIPHER_LIST (3)
+  - CURLOPT_SSL_EC_CURVES (3)
+  - CURLOPT_SSLVERSION (3)
+  - CURLOPT_USE_SSL (3)
+Protocol:
+  - TLS
+TLS-backend:
+  - OpenSSL
+Added-in: 8.14.0
+---
+
+# NAME
+
+CURLOPT_SSL_SIGNATURE_ALGORITHMS - signature algorithms to use for TLS
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_SIGNATURE_ALGORITHMS, char *list);
+~~~
+
+# DESCRIPTION
+
+Pass a char pointer, pointing to a null-terminated string holding the list of
+signature algorithms to use for the TLS connection. The list must be syntactically
+correct, it consists of one or more signature algorithm strings separated by colons.
+
+A valid example of a signature algorithms list with OpenSSL is:
+~~~
+"DSA+SHA256:rsa_pss_pss_sha256"
+~~~
+
+The application does not have to keep the string around after setting this
+option.
+
+Using this option multiple times makes the last set string override the
+previous ones. Set it to NULL to disable its use again.
+
+Works with OpenSSL and its BoringSSL fork (added in 8.14.0).
+
+# DEFAULT
+
+NULL, use built-in list
+
+# %PROTOCOLS%
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
+    curl_easy_setopt(curl, CURLOPT_SSL_SIGNATURE_ALGORITHMS,
+                     "DSA+SHA256:rsa_pss_pss_sha256");
+    res = curl_easy_perform(curl);
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# HISTORY
+
+OpenSSL support added in 8.14.0.
+
+# %AVAILABILITY%
+
+# RETURN VALUE
+
+curl_easy_setopt(3) returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/opts/Makefile.inc

@@ -367,6 +367,7 @@ man_MANS =                                      \
   CURLOPT_SSL_FALSESTART.3                      \
   CURLOPT_SSL_OPTIONS.3                         \
   CURLOPT_SSL_SESSIONID_CACHE.3                 \
+  CURLOPT_SSL_SIGNATURE_ALGORITHMS.3            \
   CURLOPT_SSL_VERIFYHOST.3                      \
   CURLOPT_SSL_VERIFYPEER.3                      \
   CURLOPT_SSL_VERIFYSTATUS.3                    \

docs/libcurl/symbols-in-versions

@@ -849,6 +849,7 @@ CURLOPT_SSL_ENABLE_NPN          7.36.0        7.86.0
 CURLOPT_SSL_FALSESTART          7.42.0
 CURLOPT_SSL_OPTIONS             7.25.0
 CURLOPT_SSL_SESSIONID_CACHE     7.16.0
+CURLOPT_SSL_SIGNATURE_ALGORITHMS 8.14.0
 CURLOPT_SSL_VERIFYHOST          7.8.1
 CURLOPT_SSL_VERIFYPEER          7.4.2
 CURLOPT_SSL_VERIFYSTATUS        7.41.0

docs/options-in-versions

@@ -218,6 +218,7 @@
 --show-error (-S)                    5.9
 --show-headers (-i)                  4.8
 --silent (-s)                        4.0
+--sigalgs                            8.14.0
 --skip-existing                      8.10.0
 --socks4                             7.15.2
 --socks4a                            7.18.0