docs: improve cipher options documentation

Closes #14407
2024-08-16 11:45:26 +02:00 · 2024-08-16 11:45:26 +02:00 · 88727f7ed0
--- 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
--- 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
--- 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.
--- 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.
--- 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.
+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 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 setting TLS 1.3 ciphers see CURLOPT_PROXY_TLS13_CIPHERS(3).

-For wolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**,
-**AES256-SHA:AES256-SHA256**, etc.
+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 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.
+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.
--- 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,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.
-
-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%

--- 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.
+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 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 setting TLS 1.3 ciphers see CURLOPT_TLS13_CIPHERS(3).

-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.
+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.
--- 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,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.
-
-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%

--- 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 */
--- 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>",
--- 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 {