xref: /curl/docs/CIPHERS.md (revision 3040971d) 
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+), mbedTLS (3.6.0+, curl 8.10.0+) and
46Schannel (curl 7.85.0+).
47
48The list of cipher suites that can be used for the `--tls13-ciphers` option:
49```
50TLS_AES_128_GCM_SHA256
51TLS_AES_256_GCM_SHA384
52TLS_CHACHA20_POLY1305_SHA256
53TLS_AES_128_CCM_SHA256
54TLS_AES_128_CCM_8_SHA256
55```
56
57### wolfSSL notes
58
59In addition to above list the following cipher suites can be used:
60`TLS_SM4_GCM_SM3` `TLS_SM4_CCM_SM3` `TLS_SHA256_SHA256` `TLS_SHA384_SHA384`.
61Usage of these cipher suites is not recommended. (The last two cipher suites
62are NULL ciphers, offering no encryption whatsoever.)
63
64### Schannel notes
65
66Schannel does not support setting individual TLS 1.3 cipher suites directly.
67To support `--tls13-ciphers` curl emulates it by adding or restricting
68algorithms to use. Due to this the specified order of preference of the
69cipher suites is not taken into account.
70
71## TLS 1.2 (1.1, 1.0) cipher suites
72
73Setting TLS 1.2 cipher suites is supported by curl with OpenSSL, LibreSSL,
74BoringSSL, mbedTLS (curl 8.8.0+), wolfSSL (curl 7.53.0+),
75Secure Transport (curl 7.77.0+) and BearSSL (curl 7.83.0+). Schannel does not
76support setting cipher suites directly, but does support setting algorithms
77(curl 7.61.0+), see Schannel notes below.
78
79For TLS 1.2 cipher suites there are multiple naming schemes, the two most used
80are with OpenSSL names (e.g. `ECDHE-RSA-AES128-GCM-SHA256`) and IANA names
81(e.g. `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`). IANA names of TLS 1.2 cipher
82suites look similar to TLS 1.3 cipher suite names, to distinguish them note
83that TLS 1.2 names contain `_WITH_`, while TLS 1.3 names do not. When setting
84TLS 1.2 cipher suites with curl it is recommended that you use OpenSSL names
85as these are most widely recognized by the supported SSL backends.
86
87The complete list of cipher suites that may be considered for the `--ciphers`
88option is extensive, it consists of more than 300 ciphers suites. However,
89nowadays for most of them their usage is discouraged, and support for a lot of
90them have been removed from the various SSL backends, if ever implemented at
91all.
92
93A shortened list (based on [recommendations by
94Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)) of cipher suites,
95which are (mostly) supported by all SSL backends, that can be used for the
96`--ciphers` option:
97```
98ECDHE-ECDSA-AES128-GCM-SHA256
99ECDHE-RSA-AES128-GCM-SHA256
100ECDHE-ECDSA-AES256-GCM-SHA384
101ECDHE-RSA-AES256-GCM-SHA384
102ECDHE-ECDSA-CHACHA20-POLY1305
103ECDHE-RSA-CHACHA20-POLY1305
104DHE-RSA-AES128-GCM-SHA256
105DHE-RSA-AES256-GCM-SHA384
106DHE-RSA-CHACHA20-POLY1305
107ECDHE-ECDSA-AES128-SHA256
108ECDHE-RSA-AES128-SHA256
109ECDHE-ECDSA-AES128-SHA
110ECDHE-RSA-AES128-SHA
111ECDHE-ECDSA-AES256-SHA384
112ECDHE-RSA-AES256-SHA384
113ECDHE-ECDSA-AES256-SHA
114ECDHE-RSA-AES256-SHA
115DHE-RSA-AES128-SHA256
116DHE-RSA-AES256-SHA256
117AES128-GCM-SHA256
118AES256-GCM-SHA384
119AES128-SHA256
120AES256-SHA256
121AES128-SHA
122AES256-SHA
123DES-CBC3-SHA
124```
125
126See this [list](https://github.com/curl/curl/blob/master/docs/CIPHERS-TLS12.md)
127for a complete list of TLS 1.2 cipher suites.
128
129### OpenSSL notes
130
131In addition to specifying a list of cipher suites, OpenSSL also accepts a
132format with specific cipher strings (like `TLSv1.2`, `AESGCM`, `CHACHA20`) and
133`!`, `-` and `+` operators. Refer to the
134[OpenSSL cipher documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-list-format)
135for further information on that format.
136
137### Schannel notes
138
139Schannel does not support setting individual TLS 1.2 cipher suites directly.
140It only allows the enabling and disabling of encryption algorithms. These are
141in the form of `CALG_xxx`, see the [Schannel `ALG_ID`
142documentation](https://docs.microsoft.com/windows/desktop/SecCrypto/alg-id)
143for a list of these algorithms. Also, (since curl 7.77.0)
144`SCH_USE_STRONG_CRYPTO` can be given to pass that flag to Schannel, lookup the
145[documentation for the Windows version in
146use](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel)
147to see how that affects the cipher suite selection. When not specifying the
148`--chiphers` and `--tl13-ciphers` options curl passes this flag by default.
149
150## Examples
151
152```sh
153curl \
154  --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \
155  --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:\
156ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \
157  https://example.com/
158```
159Restrict ciphers to `aes128-gcm` and `chacha20`. Works with OpenSSL, LibreSSL,
160mbedTLS and wolfSSL.
161
162```sh
163curl \
164  --tlsv1.3 \
165  --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \
166  https://example.com/
167```
168Restrict to only TLS 1.3 with `aes128-gcm` and `chacha20` ciphers. Works with
169OpenSSL, LibreSSL, mbedTLS, wolfSSL and Schannel.
170
171```sh
172curl \
173  --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:\
174ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \
175  https://example.com/
176```
177Restrict TLS 1.2 ciphers to `aes128-gcm` and `chacha20`, use default TLS 1.3
178ciphers (if TLS 1.3 is available). Works with OpenSSL, LibreSSL, BoringSSL,
179mbedTLS, wolfSSL, Secure Transport and BearSSL.
180
181## Further reading
182- [OpenSSL cipher suite names documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-suite-names)
183- [wolfSSL cipher support documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter04.html#cipher-support)
184- [mbedTLS cipher suites reference](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/ssl__ciphersuites_8h/)
185- [Schannel cipher suites documentation](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel)
186- [BearSSL supported crypto](https://www.bearssl.org/support.html)
187- [Secure Transport cipher suite values](https://developer.apple.com/documentation/security/1550981-ssl_cipher_suite_values)
188- [IANA cipher suites list](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4)
189- [Wikipedia cipher suite article](https://en.wikipedia.org/wiki/Cipher_suite)
190