CIPHERS.md (11197B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 ## curl cipher options 8 9 A TLS handshake involves many parameters which take part in the negotiation 10 between client and server in order to agree on the TLS version and set of 11 algorithms to use for a connection. 12 13 What has become known as a "cipher" or better "cipher suite" in TLS 14 are names for specific combinations of 15 [key exchange](https://en.wikipedia.org/wiki/Key_exchange), 16 [bulk encryption](https://en.wikipedia.org/wiki/Link_encryption), 17 [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code) 18 and with TLSv1.3 the 19 [authenticated encryption](https://en.wikipedia.org/wiki/Authenticated_encryption). 20 In addition, there are other parameters that influence the TLS handshake, like 21 [DHE](https://en.wikipedia.org/wiki/Diffie%e2%80%93Hellman_key_exchange) "groups" 22 and [ECDHE](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%e2%80%93Hellman) 23 with its "curves". 24 25 ### History 26 27 curl's way of letting users configure these settings closely followed OpenSSL 28 in its API. TLS learned new parameters, OpenSSL added new API functions and 29 curl added command line options. 30 31 Several other TLS backends followed the OpenSSL approach, more or less closely, 32 and curl maps the command line options to these TLS backends. Some TLS 33 backends do not support all of it and command line options are either 34 ignored or lead to an error. 35 36 Many examples below show the OpenSSL-like use of these options. GnuTLS 37 however chose a different approach. These are described in a separate 38 section further below. 39 40 ## ciphers, the OpenSSL way 41 42 With curl's option 43 [`--tls13-ciphers`](https://curl.se/docs/manpage.html#--tls13-ciphers) 44 or 45 [`CURLOPT_TLS13_CIPHERS`](https://curl.se/libcurl/c/CURLOPT_TLS13_CIPHERS.html) 46 users can control which cipher suites to consider when negotiating TLS 1.3 47 connections. With option 48 [`--ciphers`](https://curl.se/docs/manpage.html#--ciphers) 49 or 50 [`CURLOPT_SSL_CIPHER_LIST`](https://curl.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html) 51 users can control which cipher suites to consider when negotiating 52 TLS 1.2 (1.1, 1.0) connections. 53 54 By default, curl may negotiate TLS 1.3 and TLS 1.2 connections, so the cipher 55 suites considered when negotiating a TLS connection are a union of the TLS 1.3 56 and TLS 1.2 cipher suites. If you want curl to consider only TLS 1.3 cipher 57 suites for the connection, you have to set the minimum TLS version to 1.3 by 58 using [`--tlsv1.3`](https://curl.se/docs/manpage.html#--tlsv13) 59 or [`CURLOPT_SSLVERSION`](https://curl.se/libcurl/c/CURLOPT_SSLVERSION.html) 60 with `CURL_SSLVERSION_TLSv1_3`. 61 62 Both the TLS 1.3 and TLS 1.2 cipher options expect a list of cipher suites 63 separated by colons (`:`). This list is parsed opportunistically, cipher suites 64 that are not recognized or implemented are ignored. As long as there is at 65 least one recognized cipher suite in the list, the list is considered valid. 66 67 For both the TLS 1.3 and TLS 1.2 cipher options, the order in which the 68 cipher suites are specified determine the preference of them. When negotiating 69 a TLS connection the server picks a cipher suite from the intersection of the 70 cipher suites supported by the server and the cipher suites sent by curl. If 71 the server is configured to honor the client's cipher preference, the first 72 common cipher suite in the list sent by curl is chosen. 73 74 ### TLS 1.3 cipher suites 75 76 Setting TLS 1.3 cipher suites is supported by curl with 77 OpenSSL (1.1.1+, curl 7.61.0+), LibreSSL (3.4.1+, curl 8.3.0+), 78 wolfSSL (curl 8.10.0+) and mbedTLS (3.6.0+, curl 8.10.0+). 79 80 The list of cipher suites that can be used for the `--tls13-ciphers` option: 81 ``` 82 TLS_AES_128_GCM_SHA256 83 TLS_AES_256_GCM_SHA384 84 TLS_CHACHA20_POLY1305_SHA256 85 TLS_AES_128_CCM_SHA256 86 TLS_AES_128_CCM_8_SHA256 87 ``` 88 89 #### wolfSSL notes 90 91 In addition to above list the following cipher suites can be used: 92 `TLS_SM4_GCM_SM3` `TLS_SM4_CCM_SM3` `TLS_SHA256_SHA256` `TLS_SHA384_SHA384`. 93 Usage of these cipher suites is not recommended. (The last two cipher suites 94 are NULL ciphers, offering no encryption whatsoever.) 95 96 ### TLS 1.2 (1.1, 1.0) cipher suites 97 98 Setting TLS 1.2 cipher suites is supported by curl with OpenSSL, LibreSSL, 99 BoringSSL, mbedTLS (curl 8.8.0+), wolfSSL (curl 7.53.0+). Schannel does not 100 support setting cipher suites directly, but does support setting algorithms 101 (curl 7.61.0+), see Schannel notes below. 102 103 For TLS 1.2 cipher suites there are multiple naming schemes, the two most used 104 are with OpenSSL names (e.g. `ECDHE-RSA-AES128-GCM-SHA256`) and IANA names 105 (e.g. `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`). IANA names of TLS 1.2 cipher 106 suites look similar to TLS 1.3 cipher suite names, to distinguish them note 107 that TLS 1.2 names contain `_WITH_`, while TLS 1.3 names do not. When setting 108 TLS 1.2 cipher suites with curl it is recommended that you use OpenSSL names 109 as these are most widely recognized by the supported SSL backends. 110 111 The complete list of cipher suites that may be considered for the `--ciphers` 112 option is extensive, it consists of more than 300 ciphers suites. However, 113 nowadays for most of them their usage is discouraged, and support for a lot of 114 them have been removed from the various SSL backends, if ever implemented at 115 all. 116 117 A shortened list (based on [recommendations by 118 Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)) of cipher suites, 119 which are (mostly) supported by all SSL backends, that can be used for the 120 `--ciphers` option: 121 ``` 122 ECDHE-ECDSA-AES128-GCM-SHA256 123 ECDHE-RSA-AES128-GCM-SHA256 124 ECDHE-ECDSA-AES256-GCM-SHA384 125 ECDHE-RSA-AES256-GCM-SHA384 126 ECDHE-ECDSA-CHACHA20-POLY1305 127 ECDHE-RSA-CHACHA20-POLY1305 128 DHE-RSA-AES128-GCM-SHA256 129 DHE-RSA-AES256-GCM-SHA384 130 DHE-RSA-CHACHA20-POLY1305 131 ECDHE-ECDSA-AES128-SHA256 132 ECDHE-RSA-AES128-SHA256 133 ECDHE-ECDSA-AES128-SHA 134 ECDHE-RSA-AES128-SHA 135 ECDHE-ECDSA-AES256-SHA384 136 ECDHE-RSA-AES256-SHA384 137 ECDHE-ECDSA-AES256-SHA 138 ECDHE-RSA-AES256-SHA 139 DHE-RSA-AES128-SHA256 140 DHE-RSA-AES256-SHA256 141 AES128-GCM-SHA256 142 AES256-GCM-SHA384 143 AES128-SHA256 144 AES256-SHA256 145 AES128-SHA 146 AES256-SHA 147 DES-CBC3-SHA 148 ``` 149 150 See this [list](https://github.com/curl/curl/blob/master/docs/CIPHERS-TLS12.md) 151 for a complete list of TLS 1.2 cipher suites. 152 153 #### OpenSSL notes 154 155 In addition to specifying a list of cipher suites, OpenSSL also accepts a 156 format with specific cipher strings (like `TLSv1.2`, `AESGCM`, `CHACHA20`) and 157 `!`, `-` and `+` operators. Refer to the 158 [OpenSSL cipher documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-list-format) 159 for further information on that format. 160 161 #### Schannel notes 162 163 Schannel does not support setting individual TLS 1.2 cipher suites directly. 164 It only allows the enabling and disabling of encryption algorithms. These are 165 in the form of `CALG_xxx`, see the [Schannel `ALG_ID` 166 documentation](https://docs.microsoft.com/windows/desktop/SecCrypto/alg-id) 167 for a list of these algorithms. Also, (since curl 7.77.0) 168 `SCH_USE_STRONG_CRYPTO` can be given to pass that flag to Schannel, lookup the 169 [documentation for the Windows version in 170 use](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel) 171 to see how that affects the cipher suite selection. When not specifying the 172 `--ciphers` and `--tls13-ciphers` options curl passes this flag by default. 173 174 ### Examples 175 176 ```sh 177 curl \ 178 --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \ 179 --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:\ 180 ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \ 181 https://example.com/ 182 ``` 183 Restrict ciphers to `aes128-gcm` and `chacha20`. Works with OpenSSL, LibreSSL, 184 mbedTLS and wolfSSL. 185 186 ```sh 187 curl \ 188 --tlsv1.3 \ 189 --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \ 190 https://example.com/ 191 ``` 192 Restrict to only TLS 1.3 with `aes128-gcm` and `chacha20` ciphers. Works with 193 OpenSSL, LibreSSL, mbedTLS, wolfSSL and Schannel. 194 195 ```sh 196 curl \ 197 --ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:\ 198 ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \ 199 https://example.com/ 200 ``` 201 Restrict TLS 1.2 ciphers to `aes128-gcm` and `chacha20`, use default TLS 1.3 202 ciphers (if TLS 1.3 is available). Works with OpenSSL, LibreSSL, BoringSSL, 203 mbedTLS and wolfSSL. 204 205 ## ciphers, the GnuTLS way 206 207 With GnuTLS, curl allows configuration of all TLS parameters via option 208 [`--ciphers`](https://curl.se/docs/manpage.html#--ciphers) 209 or 210 [`CURLOPT_SSL_CIPHER_LIST`](https://curl.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html) 211 only. The option 212 [`--tls13-ciphers`](https://curl.se/docs/manpage.html#--tls13-ciphers) 213 or 214 [`CURLOPT_TLS13_CIPHERS`](https://curl.se/libcurl/c/CURLOPT_TLS13_CIPHERS.html) 215 is being ignored. 216 217 `--ciphers` is used to set the GnuTLS **priority string** in 218 the following way: 219 220 * When the set string starts with '+', '-' or '!' it is *appended* to the 221 priority string libcurl itself generates (separated by ':'). This initial 222 priority depends other settings such as CURLOPT_SSLVERSION(3), 223 CURLOPT_TLSAUTH_USERNAME(3) (for SRP) or if HTTP/3 (QUIC) 224 is being negotiated. 225 * Otherwise, the set string fully *replaces* the libcurl generated one. While 226 giving full control to the application, the set priority needs to 227 provide for everything the transfer may need to negotiate. Example: if 228 the set priority only allows TLSv1.2, all HTTP/3 attempts fail. 229 230 Users may specify via `--ciphers` anything that GnuTLS supports: ciphers, 231 key exchange, MAC, compression, TLS versions, signature algorithms, groups, 232 elliptic curves, certificate types. In addition, GnuTLS has a variety of 233 other keywords that tweak its operations. Applications or a system 234 may define new alias names for priority strings that can then be used here. 235 236 Since the order of items in priority strings is significant, it makes no 237 sense for curl to puzzle other ssl options somehow together. `--ciphers` 238 is the single way to change priority. 239 240 ### Examples 241 242 ```sh 243 curl \ 244 --ciphers '-CIPHER_ALL:+AES-128-GCM:+CHACHA20-POLY1305' \ 245 https://example.com/ 246 ``` 247 Restrict ciphers to `aes128-gcm` and `chacha20` in GnuTLS. 248 249 ```sh 250 curl \ 251 --ciphers 'NORMAL:-VERS-ALL:+TLS1.3:-AES-256-GCM' \ 252 https://example.com/ 253 ``` 254 Restrict to only TLS 1.3 without the `aes256-gcm` cipher. 255 256 ```sh 257 curl \ 258 --ciphers 'NORMAL:-VERS-ALL:+TLS1.2:-CIPHER_ALL:+CAMELLIA-128-GCM' \ 259 https://example.com/ 260 ``` 261 Restrict to only TLS 1.2 with the `CAMELLIA-128-GCM` cipher. 262 263 ## Further reading 264 - [OpenSSL cipher suite names documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-suite-names) 265 - [wolfSSL cipher support documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter04.html#cipher-support) 266 - [mbedTLS cipher suites reference](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/ssl__ciphersuites_8h/) 267 - [Schannel cipher suites documentation](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel) 268 - [IANA cipher suites list](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4) 269 - [Wikipedia cipher suite article](https://en.wikipedia.org/wiki/Cipher_suite) 270 - [GnuTLS Priority Strings](https://gnutls.org/manual/html_node/Priority-Strings.html)