xref: /curl/docs/CIPHERS.md (revision 6238888c) 
1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3
4SPDX-License-Identifier: curl
5-->
6
7## curl cipher options
8
9With curl's option
10[`--tls13-ciphers`](https://curl.se/docs/manpage.html#--tls13-ciphers)
11or
12[`CURLOPT_TLS13_CIPHERS`](https://curl.se/libcurl/c/CURLOPT_TLS13_CIPHERS.html)
13users can control which cipher suites to consider when negotiating TLS 1.3
14connections. With option
15[`--ciphers`](https://curl.se/docs/manpage.html#--ciphers)
16or
17[`CURLOPT_SSL_CIPHER_LIST`](https://curl.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html)
18users can control which cipher suites to consider when negotiating
19TLS 1.2 (1.1, 1.0) connections.
20
21By default, curl may negotiate TLS 1.3 and TLS 1.2 connections, so the cipher
22suites considered when negotiating a TLS connection are a union of the TLS 1.3
23and TLS 1.2 cipher suites. If you want curl to consider only TLS 1.3 cipher
24suites for the connection, you have to set the minimum TLS version to 1.3 by
25using [`--tlsv1.3`](https://curl.se/docs/manpage.html#--tlsv13)
26or [`CURLOPT_SSLVERSION`](https://curl.se/libcurl/c/CURLOPT_SSLVERSION.html)
27with `CURL_SSLVERSION_TLSv1_3`.
28
29Both the TLS 1.3 and TLS 1.2 cipher options expect a list of cipher suites
30separated by colons (`:`). This list is parsed opportunistically, cipher suites
31that are not recognized or implemented are ignored. As long as there is at
32least one recognized cipher suite in the list, the list is considered valid.
33
34For both the TLS 1.3 and TLS 1.2 cipher options, the order in which the
35cipher suites are specified determine the preference of them. When negotiating
36a TLS connection the server picks a cipher suite from the intersection of the
37cipher suites supported by the server and the cipher suites sent by curl. If
38the server is configured to honor the client's cipher preference, the first
39common cipher suite in the list sent by curl is chosen.
40
41## TLS 1.3 cipher suites
42
43Setting TLS 1.3 cipher suites is supported by curl with
44OpenSSL (1.1.1+, curl 7.61.0+), LibreSSL (3.4.1+, curl 8.3.0+),
45wolfSSL (curl 8.10.0+) and mbedTLS (3.6.0+, curl 8.10.0+).
46
47The list of cipher suites that can be used for the `--tls13-ciphers` option:
48```
49TLS_AES_128_GCM_SHA256
50TLS_AES_256_GCM_SHA384
51TLS_CHACHA20_POLY1305_SHA256
52TLS_AES_128_CCM_SHA256
53TLS_AES_128_CCM_8_SHA256
54```
55
56### wolfSSL notes
57
58In addition to above list the following cipher suites can be used:
59`TLS_SM4_GCM_SM3` `TLS_SM4_CCM_SM3` `TLS_SHA256_SHA256` `TLS_SHA384_SHA384`.
60Usage of these cipher suites is not recommended. (The last two cipher suites
61are NULL ciphers, offering no encryption whatsoever.)
62
63## TLS 1.2 (1.1, 1.0) cipher suites
64
65Setting TLS 1.2 cipher suites is supported by curl with OpenSSL, LibreSSL,
66BoringSSL, mbedTLS (curl 8.8.0+), wolfSSL (curl 7.53.0+),
67Secure Transport (curl 7.77.0+) and BearSSL (curl 7.83.0+). Schannel does not
68support setting cipher suites directly, but does support setting algorithms
69(curl 7.61.0+), see Schannel notes below.
70
71For TLS 1.2 cipher suites there are multiple naming schemes, the two most used
72are with OpenSSL names (e.g. `ECDHE-RSA-AES128-GCM-SHA256`) and IANA names
73(e.g. `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`). IANA names of TLS 1.2 cipher
74suites look similar to TLS 1.3 cipher suite names, to distinguish them note
75that TLS 1.2 names contain `_WITH_`, while TLS 1.3 names do not. When setting
76TLS 1.2 cipher suites with curl it is recommended that you use OpenSSL names
77as these are most widely recognized by the supported SSL backends.
78
79The complete list of cipher suites that may be considered for the `--ciphers`
80option is extensive, it consists of more than 300 ciphers suites. However,
81nowadays for most of them their usage is discouraged, and support for a lot of
82them have been removed from the various SSL backends, if ever implemented at
83all.
84
85A shortened list (based on [recommendations by
86Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)) of cipher suites,
87which are (mostly) supported by all SSL backends, that can be used for the
88`--ciphers` option:
89```
90ECDHE-ECDSA-AES128-GCM-SHA256
91ECDHE-RSA-AES128-GCM-SHA256
92ECDHE-ECDSA-AES256-GCM-SHA384
93ECDHE-RSA-AES256-GCM-SHA384
94ECDHE-ECDSA-CHACHA20-POLY1305
95ECDHE-RSA-CHACHA20-POLY1305
96DHE-RSA-AES128-GCM-SHA256
97DHE-RSA-AES256-GCM-SHA384
98DHE-RSA-CHACHA20-POLY1305
99ECDHE-ECDSA-AES128-SHA256
100ECDHE-RSA-AES128-SHA256
101ECDHE-ECDSA-AES128-SHA
102ECDHE-RSA-AES128-SHA
103ECDHE-ECDSA-AES256-SHA384
104ECDHE-RSA-AES256-SHA384
105ECDHE-ECDSA-AES256-SHA
106ECDHE-RSA-AES256-SHA
107DHE-RSA-AES128-SHA256
108DHE-RSA-AES256-SHA256
109AES128-GCM-SHA256
110AES256-GCM-SHA384
111AES128-SHA256
112AES256-SHA256
113AES128-SHA
114AES256-SHA
115DES-CBC3-SHA
116```
117
118See this [list](https://github.com/curl/curl/blob/master/docs/CIPHERS-TLS12.md)
119for a complete list of TLS 1.2 cipher suites.
120
121### OpenSSL notes
122
123In addition to specifying a list of cipher suites, OpenSSL also accepts a
124format with specific cipher strings (like `TLSv1.2`, `AESGCM`, `CHACHA20`) and
125`!`, `-` and `+` operators. Refer to the
126[OpenSSL cipher documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-list-format)
127for further information on that format.
128
129### Schannel notes
130
131Schannel does not support setting individual TLS 1.2 cipher suites directly.
132It only allows the enabling and disabling of encryption algorithms. These are
133in the form of `CALG_xxx`, see the [Schannel `ALG_ID`
134documentation](https://docs.microsoft.com/windows/desktop/SecCrypto/alg-id)
135for a list of these algorithms. Also, (since curl 7.77.0)
136`SCH_USE_STRONG_CRYPTO` can be given to pass that flag to Schannel, lookup the
137[documentation for the Windows version in
138use](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel)
139to see how that affects the cipher suite selection. When not specifying the
140`--chiphers` and `--tl13-ciphers` options curl passes this flag by default.
141
142## Examples
143
144```sh
145curl \
146  --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \
147  --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:\
148ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \
149  https://example.com/
150```
151Restrict ciphers to `aes128-gcm` and `chacha20`. Works with OpenSSL, LibreSSL,
152mbedTLS and wolfSSL.
153
154```sh
155curl \
156  --tlsv1.3 \
157  --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \
158  https://example.com/
159```
160Restrict to only TLS 1.3 with `aes128-gcm` and `chacha20` ciphers. Works with
161OpenSSL, LibreSSL, mbedTLS, wolfSSL and Schannel.
162
163```sh
164curl \
165  --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:\
166ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \
167  https://example.com/
168```
169Restrict TLS 1.2 ciphers to `aes128-gcm` and `chacha20`, use default TLS 1.3
170ciphers (if TLS 1.3 is available). Works with OpenSSL, LibreSSL, BoringSSL,
171mbedTLS, wolfSSL, Secure Transport and BearSSL.
172
173## Further reading
174- [OpenSSL cipher suite names documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-suite-names)
175- [wolfSSL cipher support documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter04.html#cipher-support)
176- [mbedTLS cipher suites reference](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/ssl__ciphersuites_8h/)
177- [Schannel cipher suites documentation](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel)
178- [BearSSL supported crypto](https://www.bearssl.org/support.html)
179- [Secure Transport cipher suite values](https://developer.apple.com/documentation/security/1550981-ssl_cipher_suite_values)
180- [IANA cipher suites list](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4)
181- [Wikipedia cipher suite article](https://en.wikipedia.org/wiki/Cipher_suite)
182