docs: improve cipher options documentation

Closes #14407

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>
+Arg: <list>
-Help: SSL ciphers to use
+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
+Specifies which cipher suites to use in the connection if it negotiates
-specify valid ciphers. Read up on SSL cipher list details on this URL:
+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

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
+Specify which cipher suites to use in the connection to your HTTPS proxy when
-of ciphers must specify valid ciphers. Read up on SSL cipher list details on
+it negotiates TLS 1.2 (1.1, 1.0). The list of ciphers suites must specify
-this URL:
+valid ciphers. Read up on cipher suite details on this URL:
 
 https://curl.se/docs/ssl-ciphers.html

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
+This option is used when curl is built to use OpenSSL 1.1.1 or later,
-later. If you are using a different SSL backend you can try setting TLS 1.3
+Schannel, wolfSSL, or mbedTLS 3.6.0 or later.
-cipher suites by using the --proxy-ciphers option.
+
+Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
+by using the --proxy-ciphers option.

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
+This option is used when curl is built to use OpenSSL 1.1.1 or later,
-later, or Schannel. If you are using a different SSL backend you can try
+Schannel, wolfSSL, or mbedTLS 3.6.0 or later.
-setting TLS 1.3 cipher suites by using the --ciphers option.
+
+Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set
+by using the --ciphers option.

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
+cipher suites to use for the TLS 1.2 (1.1, 1.0) connection to the HTTPS proxy.
-syntactically correct, it consists of one or more cipher strings separated by
+The list must be syntactically correct, it consists of one or more cipher suite
-colons. Commas or spaces are also acceptable separators but colons are
+strings separated by colons.
-normally used, &!, &- and &+ can be used as operators.
 
-For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**,
+For setting TLS 1.3 ciphers see CURLOPT_PROXY_TLS13_CIPHERS(3).
-**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**,
+A valid example of a cipher list is:
-**AES256-SHA:AES256-SHA256**, etc.
+~~~c
+"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
+"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
+~~~
 
-For mbedTLS and BearSSL, valid examples of cipher lists include
+For Schannel, you can use this option to set algorithms but not specific
-**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using
+cipher suites. Refer to the ciphers lists document for algorithms.
-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.
 
 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
+Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.
-CURLE_OUT_OF_MEMORY if there was insufficient heap space.

docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md

@@ -17,6 +17,7 @@ TLS-backend:
   - Schannel
   - wolfSSL
   - mbedTLS
+  - rustls
 Added-in: 7.61.0
 ---
 
@@ -40,16 +41,17 @@ 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.
 
+For setting TLS 1.2 (1.1, 1.0) ciphers see CURLOPT_PROXY_SSL_CIPHER_LIST(3).
+
+A valid example of a cipher list is:
+~~~c
+"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256"
+~~~
+
 Find more details about cipher lists on this URL:
 
  https://curl.se/docs/ssl-ciphers.html
 
-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 CURLOPT_PROXY_SSL_CIPHER_LIST(3) option.
-
 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.
+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 7.85.0 for Schannel.
+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.
-Added in 8.10.0 for wolfSSL.
-
-Added in 8.10.0 for mbedTLS. Available when built with mbedTLS \>= 3.6.0.
 
 # %AVAILABILITY%
 

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,
+cipher suites to use for the TLS 1.2 (1.1, 1.0) connection. The list must
-it consists of one or more cipher strings separated by colons. Commas or
+be syntactically correct, it consists of one or more cipher suite strings
-spaces are also acceptable separators but colons are normally used, !, - and
+separated by colons.
-+ can be used as operators.
 
-For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**,
+For setting TLS 1.3 ciphers see CURLOPT_TLS13_CIPHERS(3).
-**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**,
+A valid example of a cipher list is:
-**AES256-SHA:AES256-SHA256**, etc.
+~~~c
-
+"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
-For mbedTLS and BearSSL, valid examples of cipher lists include
+"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
-**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.
 
 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
+Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.
-CURLE_OUT_OF_MEMORY if there was insufficient heap space.

docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md

@@ -18,6 +18,7 @@ TLS-backend:
   - Schannel
   - wolfSSL
   - mbedTLS
+  - rustls
 Added-in: 7.61.0
 ---
 
@@ -40,16 +41,17 @@ 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.
 
+For setting TLS 1.2 (1.1, 1.0) ciphers see CURLOPT_SSL_CIPHER_LIST(3).
+
+A valid example of a cipher list is:
+~~~c
+"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256"
+~~~
+
 Find more details about cipher lists on this URL:
 
  https://curl.se/docs/ssl-ciphers.html
 
-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 CURLOPT_SSL_CIPHER_LIST(3) option.
-
 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.
+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 7.85.0 for Schannel.
+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.
-Added in 8.10.0 for wolfSSL.
-
-Added in 8.10.0 for mbedTLS. Available when built with mbedTLS \>= 3.6.0.
 
 # %AVAILABILITY%
 

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 */

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>",
+  {"    --ciphers <list>",
-   "SSL ciphers to use",
+   "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>",

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 {