docs: improve cipher options documentation

Closes #14407

diff --git a/docs/cmdline-opts/ciphers.md b/docs/cmdline-opts/ciphers.md
index 9d7e0c6fe039caa2e345fefd07214ec95ce64cdd..6a597a2c8fb192c5add8a3677e4c8b5827d75dd1 100644 (file)
--- a/docs/cmdline-opts/ciphers.md
+++ b/docs/cmdline-opts/ciphers.md
@@ -2,23 +2,24 @@
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ciphers
-Arg: <list of ciphers>
-Help: SSL ciphers to use
+Arg: <list>
+Help: TLS 1.2 (1.1, 1.0) ciphers to use
 Protocols: TLS
 Category: tls
 Added: 7.9
 Multi: single
 See-also:
-  - tlsv1.3
   - tls13-ciphers
   - proxy-ciphers
+  - curves
 Example:
-  - --ciphers ECDHE-ECDSA-AES256-CCM8 $URL
+  - --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256 $URL
 ---
 
 # `--ciphers`
 
-Specifies which ciphers to use in the connection. The list of ciphers must
-specify valid ciphers. Read up on SSL cipher list details on this URL:
+Specifies which cipher suites to use in the connection if it negotiates
+TLS 1.2 (1.1, 1.0). The list of ciphers suites must specify valid ciphers.
+Read up on cipher suite details on this URL:
 
 https://curl.se/docs/ssl-ciphers.html

diff --git a/docs/cmdline-opts/proxy-ciphers.md b/docs/cmdline-opts/proxy-ciphers.md
index 065d44953069f5e0f29820e72f4b43b8efa5ec50..420e7563bdd79e47cfe4cec1ed9bd89d2a548c0d 100644 (file)
--- a/docs/cmdline-opts/proxy-ciphers.md
+++ b/docs/cmdline-opts/proxy-ciphers.md
@@ -3,24 +3,25 @@ c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: proxy-ciphers
 Arg: <list>
-Help: SSL ciphers to use for proxy
+Help: TLS 1.2 (1.1, 1.0) ciphers to use for proxy
+Protocols: TLS
 Added: 7.52.0
 Category: proxy tls
 Multi: single
 See-also:
+  - proxy-tls13-ciphers
   - ciphers
-  - curves
   - proxy
 Example:
-  - --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy $URL
+  - --proxy-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256 -x https://proxy $URL
 ---
 
 # `--proxy-ciphers`
 
 Same as --ciphers but used in HTTPS proxy context.
 
-Specifies which ciphers to use in the connection to the HTTPS proxy. The list
-of ciphers must specify valid ciphers. Read up on SSL cipher list details on
-this URL:
+Specify which cipher suites to use in the connection to your HTTPS proxy when
+it negotiates TLS 1.2 (1.1, 1.0). The list of ciphers suites must specify
+valid ciphers. Read up on cipher suite details on this URL:
 
 https://curl.se/docs/ssl-ciphers.html

diff --git a/docs/cmdline-opts/proxy-tls13-ciphers.md b/docs/cmdline-opts/proxy-tls13-ciphers.md
index 002fd0b0f4c1e92508888f7ded1509688969a9d0..7a03b0f7c9cb5060847fbc7e4e167cac942a19e7 100644 (file)
--- a/docs/cmdline-opts/proxy-tls13-ciphers.md
+++ b/docs/cmdline-opts/proxy-tls13-ciphers.md
@@ -2,28 +2,32 @@
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: proxy-tls13-ciphers
-Arg: <ciphersuite list>
+Arg: <list>
 help: TLS 1.3 proxy cipher suites
 Protocols: TLS
 Category: proxy tls
 Added: 7.61.0
 Multi: single
 See-also:
-  - tls13-ciphers
-  - curves
   - proxy-ciphers
+  - tls13-ciphers
+  - proxy
 Example:
   - --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy $URL
 ---
 
 # `--proxy-tls13-ciphers`
 
+Same as --tls13-ciphers but used in HTTPS proxy context.
+
 Specify which cipher suites to use in the connection to your HTTPS proxy when
 it negotiates TLS 1.3. The list of ciphers suites must specify valid ciphers.
 Read up on TLS 1.3 cipher suite details on this URL:
 
 https://curl.se/docs/ssl-ciphers.html
 
-This option is currently used only when curl is built to use OpenSSL 1.1.1 or
-later. If you are using a different SSL backend you can try setting TLS 1.3
-cipher suites by using the --proxy-ciphers option.
+This option is used when curl is built to use OpenSSL 1.1.1 or later,
+Schannel, wolfSSL, or mbedTLS 3.6.0 or later.
+
+Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
+by using the --proxy-ciphers option.

diff --git a/docs/cmdline-opts/tls13-ciphers.md b/docs/cmdline-opts/tls13-ciphers.md
index 55145aacf9cd6470ea7e37a266f173c4a627adc6..0f1ff33ce8c18ebb4b5323e5550ee53ff0c13f23 100644 (file)
--- a/docs/cmdline-opts/tls13-ciphers.md
+++ b/docs/cmdline-opts/tls13-ciphers.md
@@ -10,8 +10,8 @@ Added: 7.61.0
 Multi: single
 See-also:
   - ciphers
-  - curves
   - proxy-tls13-ciphers
+  - curves
 Example:
   - --tls13-ciphers TLS_AES_128_GCM_SHA256 $URL
 ---
@@ -24,6 +24,8 @@ cipher suite details on this URL:
 
 https://curl.se/docs/ssl-ciphers.html
 
-This option is currently used only when curl is built to use OpenSSL 1.1.1 or
-later, or Schannel. If you are using a different SSL backend you can try
-setting TLS 1.3 cipher suites by using the --ciphers option.
+This option is used when curl is built to use OpenSSL 1.1.1 or later,
+Schannel, wolfSSL, or mbedTLS 3.6.0 or later.
+
+Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
+by using the --ciphers option.

diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md
index 0c64abbc95fdebc4774f8a40c59123b557bc3bf0..5e4c2fa9e1d5a87063d0dd764250e7cc698e1775 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md
+++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md
@@ -18,8 +18,8 @@ TLS-backend:
   - Schannel
   - Secure Transport
   - wolfSSL
-  - GnuTLS
   - mbedTLS
+  - rustls
 Added-in: 7.52.0
 ---
 
@@ -39,25 +39,20 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_CIPHER_LIST,
 # DESCRIPTION
 
 Pass a char pointer, pointing to a null-terminated string holding the list of
-ciphers to use for the connection to the HTTPS proxy. The list must be
-syntactically correct, it consists of one or more cipher strings separated by
-colons. Commas or spaces are also acceptable separators but colons are
-normally used, &!, &- and &+ can be used as operators.
-
-For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**,
-**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally
-set when you compile OpenSSL.
-
-For wolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**,
-**AES256-SHA:AES256-SHA256**, etc.
-
-For mbedTLS and BearSSL, valid examples of cipher lists include
-**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using
-IANA names
-**TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**,
-etc. With mbedTLS and BearSSL you do not add/remove ciphers. If one uses this
-option then all known ciphers are disabled and only those passed in are
-enabled.
+cipher suites to use for the TLS 1.2 (1.1, 1.0) connection to the HTTPS proxy.
+The list must be syntactically correct, it consists of one or more cipher suite
+strings separated by colons.
+
+For setting TLS 1.3 ciphers see CURLOPT_PROXY_TLS13_CIPHERS(3).
+
+A valid example of a cipher list is:
+~~~c
+"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
+"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
+~~~
+
+For Schannel, you can use this option to set algorithms but not specific
+cipher suites. Refer to the ciphers lists document for algorithms.
 
 Find more details about cipher lists on this URL:
 
@@ -82,16 +77,26 @@ int main(void)
     CURLcode res;
     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
     curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost");
-    curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST, "TLSv1");
+    curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST,
+                     "ECDHE-ECDSA-CHACHA20-POLY1305:"
+                     "ECDHE-RSA-CHACHA20-POLY1305");
     res = curl_easy_perform(curl);
     curl_easy_cleanup(curl);
   }
 }
 ~~~
 
+# HISTORY
+
+OpenSSL support added in 7.52.0.
+wolfSSL, Schannel, Secure Transport, and BearSSL support added in 7.87.0
+mbedTLS support added in 8.8.0.
+rustls support added in 8.10.0.
+
+Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported.
+
 # %AVAILABILITY%
 
 # RETURN VALUE
 
-Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
-CURLE_OUT_OF_MEMORY if there was insufficient heap space.
+Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.

diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md
index 37470518d1e5a729b78d26c67dfdb7e5e402659a..5567f2dfd4cd423d1b04a22d497ab94116a24dfa 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md
+++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md
@@ -17,6 +17,7 @@ TLS-backend:
   - Schannel
   - wolfSSL
   - mbedTLS
+  - rustls
 Added-in: 7.61.0
 ---
 
@@ -40,15 +41,16 @@ cipher suites to use for the TLS 1.3 connection to a proxy. The list must be
 syntactically correct, it consists of one or more cipher suite strings
 separated by colons.
 
-Find more details about cipher lists on this URL:
+For setting TLS 1.2 (1.1, 1.0) ciphers see CURLOPT_PROXY_SSL_CIPHER_LIST(3).
 
- https://curl.se/docs/ssl-ciphers.html
+A valid example of a cipher list is:
+~~~c
+"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256"
+~~~
 
-This option is used when curl is built to use OpenSSL 1.1.1 or later,
-Schannel, wolfSSL, or mbedTLS 3.6.0 or later.
+Find more details about cipher lists on this URL:
 
-Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
-by using the CURLOPT_PROXY_SSL_CIPHER_LIST(3) option.
+ https://curl.se/docs/ssl-ciphers.html
 
 The application does not have to keep the string around after setting this
 option.
@@ -78,13 +80,15 @@ int main(void)
 
 # HISTORY
 
-Added in 7.61.0 for OpenSSL. Available when built with OpenSSL \>= 1.1.1.
-
-Added in 7.85.0 for Schannel.
+OpenSSL support added in 7.61.0, available when built with OpenSSL \>= 1.1.1.
+Schannel support added in 7.87.0.
+LibreSSL support added in 8.3.0, available when built with LibreSSL \>= 3.4.1.
+wolfSSL support added in 8.10.0.
+mbedTLS support added in 8.10.0, available when built with mbedTLS \>= 3.6.0.
+rustls support added in 8.10.0.
 
-Added in 8.10.0 for wolfSSL.
-
-Added in 8.10.0 for mbedTLS. Available when built with mbedTLS \>= 3.6.0.
+Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
+by using the CURLOPT_PROXY_SSL_CIPHER_LIST(3) option.
 
 # %AVAILABILITY%
 

diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md
index c8923e66b31465096ebcf06d3b0cf982c9908236..97561e793cc7642ea21ac71d8b58bd9ec6417433 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md
+++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md
@@ -18,8 +18,8 @@ TLS-backend:
   - Schannel
   - Secure Transport
   - wolfSSL
-  - GnuTLS
   - mbedTLS
+  - rustls
 Added-in: 7.9
 ---
 
@@ -38,25 +38,17 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list);
 # DESCRIPTION
 
 Pass a char pointer, pointing to a null-terminated string holding the list of
-ciphers to use for the SSL connection. The list must be syntactically correct,
-it consists of one or more cipher strings separated by colons. Commas or
-spaces are also acceptable separators but colons are normally used, !, - and
-+ can be used as operators.
-
-For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**,
-**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally set when
-you compile OpenSSL.
-
-For wolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**,
-**AES256-SHA:AES256-SHA256**, etc.
-
-For mbedTLS and BearSSL, valid examples of cipher lists include
-**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using
-IANA names
-**TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**,
-etc. With mbedTLS and BearSSL you do not add/remove ciphers. If one uses this
-option then all known ciphers are disabled and only those passed in are
-enabled.
+cipher suites to use for the TLS 1.2 (1.1, 1.0) connection. The list must
+be syntactically correct, it consists of one or more cipher suite strings
+separated by colons.
+
+For setting TLS 1.3 ciphers see CURLOPT_TLS13_CIPHERS(3).
+
+A valid example of a cipher list is:
+~~~c
+"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
+"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
+~~~
 
 For Schannel, you can use this option to set algorithms but not specific
 cipher suites. Refer to the ciphers lists document for algorithms.
@@ -83,7 +75,9 @@ int main(void)
   if(curl) {
     CURLcode res;
     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
-    curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, "TLSv1");
+    curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST,
+                     "ECDHE-ECDSA-CHACHA20-POLY1305:"
+                     "ECDHE-RSA-CHACHA20-POLY1305");
     res = curl_easy_perform(curl);
     curl_easy_cleanup(curl);
   }
@@ -92,11 +86,18 @@ int main(void)
 
 # HISTORY
 
-Added in 7.9, in 7.83.0 for BearSSL, in 8.8.0 for mbedTLS
+OpenSSL support added in 7.9.
+wolfSSL support added in 7.53.0.
+Schannel support added in 7.61.0.
+Secure Transport support added in 7.77.0.
+BearSSL support added in 7.83.0.
+mbedTLS support added in 8.8.0.
+rustls support added in 8.10.0.
+
+Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported.
 
 # %AVAILABILITY%
 
 # RETURN VALUE
 
-Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
-CURLE_OUT_OF_MEMORY if there was insufficient heap space.
+Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.

diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md
index 16fccdb7d10d082184f19fc51c037df3dfaa4016..a2543d2703a24a4839e3b22ff48ea473a2f416c8 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md
+++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md
@@ -18,6 +18,7 @@ TLS-backend:
   - Schannel
   - wolfSSL
   - mbedTLS
+  - rustls
 Added-in: 7.61.0
 ---
 
@@ -40,15 +41,16 @@ cipher suites to use for the TLS 1.3 connection. The list must be
 syntactically correct, it consists of one or more cipher suite strings
 separated by colons.
 
-Find more details about cipher lists on this URL:
+For setting TLS 1.2 (1.1, 1.0) ciphers see CURLOPT_SSL_CIPHER_LIST(3).
 
- https://curl.se/docs/ssl-ciphers.html
+A valid example of a cipher list is:
+~~~c
+"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256"
+~~~
 
-This option is used when curl is built to use OpenSSL 1.1.1 or later,
-Schannel, wolfSSL, or mbedTLS 3.6.0 or later.
+Find more details about cipher lists on this URL:
 
-Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
-by using the CURLOPT_SSL_CIPHER_LIST(3) option.
+ https://curl.se/docs/ssl-ciphers.html
 
 The application does not have to keep the string around after setting this
 option.
@@ -78,13 +80,15 @@ int main(void)
 
 # HISTORY
 
-Added in 7.61.0 for OpenSSL. Available when built with OpenSSL \>= 1.1.1.
-
-Added in 7.85.0 for Schannel.
+OpenSSL support added in 7.61.0, available when built with OpenSSL \>= 1.1.1.
+Schannel support added in 7.85.0.
+LibreSSL support added in 8.3.0, available when built with LibreSSL \>= 3.4.1.
+wolfSSL support added in 8.10.0.
+mbedTLS support added in 8.10.0, available when built with mbedTLS \>= 3.6.0.
+rustls support added in 8.10.0.
 
-Added in 8.10.0 for wolfSSL.
-
-Added in 8.10.0 for mbedTLS. Available when built with mbedTLS \>= 3.6.0.
+Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
+by using the CURLOPT_SSL_CIPHER_LIST(3) option.
 
 # %AVAILABILITY%
 

diff --git a/include/curl/curl.h b/include/curl/curl.h
index 29e025c318cd35b2c2e7ab714687752cef58b8b3..840c2864cb03a0a8a698c24e0395d7387e675e60 100644 (file)
--- a/include/curl/curl.h
+++ b/include/curl/curl.h
@@ -1398,7 +1398,7 @@ typedef enum {
      operation. Set filename to "-" (dash) to make it go to stdout. */
   CURLOPT(CURLOPT_COOKIEJAR, CURLOPTTYPE_STRINGPOINT, 82),
 
-  /* Specify which SSL ciphers to use */
+  /* Specify which TLS 1.2 (1.1, 1.0) ciphers to use */
   CURLOPT(CURLOPT_SSL_CIPHER_LIST, CURLOPTTYPE_STRINGPOINT, 83),
 
   /* Specify which HTTP version to use! This must be set to one of the
@@ -2022,7 +2022,7 @@ typedef enum {
   /* password for the SSL private key for proxy */
   CURLOPT(CURLOPT_PROXY_KEYPASSWD, CURLOPTTYPE_STRINGPOINT, 258),
 
-  /* Specify which SSL ciphers to use for proxy */
+  /* Specify which TLS 1.2 (1.1, 1.0) ciphers to use for proxy */
   CURLOPT(CURLOPT_PROXY_SSL_CIPHER_LIST, CURLOPTTYPE_STRINGPOINT, 259),
 
   /* CRL file for proxy */

diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c
index 1c5b5e9ef7fccf57ae63d2e5b02be95bf8add458..43635c22e0abac101dbba9423f656c0840e0e0f2 100644 (file)
--- a/src/tool_listhelp.c
+++ b/src/tool_listhelp.c
@@ -69,8 +69,8 @@ const struct helptxt helptext[] = {
   {"    --cert-type <type>",
    "Certificate type (DER/PEM/ENG/P12)",
    CURLHELP_TLS},
-  {"    --ciphers <list of ciphers>",
-   "SSL ciphers to use",
+  {"    --ciphers <list>",
+   "TLS 1.2 (1.1, 1.0) ciphers to use",
    CURLHELP_TLS},
   {"    --compressed",
    "Request compressed response",
@@ -515,7 +515,7 @@ const struct helptxt helptext[] = {
    "Client certificate type for HTTPS proxy",
    CURLHELP_PROXY | CURLHELP_TLS},
   {"    --proxy-ciphers <list>",
-   "SSL ciphers to use for proxy",
+   "TLS 1.2 (1.1, 1.0) ciphers to use for proxy",
    CURLHELP_PROXY | CURLHELP_TLS},
   {"    --proxy-crlfile <file>",
    "Set a CRL list for proxy",
@@ -559,7 +559,7 @@ const struct helptxt helptext[] = {
   {"    --proxy-ssl-auto-client-cert",
    "Auto client certificate for proxy",
    CURLHELP_PROXY | CURLHELP_TLS},
-  {"    --proxy-tls13-ciphers <ciphersuite list>",
+  {"    --proxy-tls13-ciphers <list>",
    "TLS 1.3 proxy cipher suites",
    CURLHELP_PROXY | CURLHELP_TLS},
   {"    --proxy-tlsauthtype <type>",

diff --git a/tests/test1275.pl b/tests/test1275.pl
index 353391d2f3d9f76272ffc0bddd6fb45861f0d716..e5f54c627e9beb7a7170e2688228504020316652 100755 (executable)
--- a/tests/test1275.pl
+++ b/tests/test1275.pl
@@ -32,7 +32,9 @@ my $errors;
 my %accepted=('curl' => 1,
               'libcurl' => 1,
               'macOS' => 1,
+              'wolfSSL' => 1,
               'mbedTLS' => 1,
+              'rustls' => 1,
               'c-ares' => 1);
 
 sub checkfile {