1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SSL_CIPHER_LIST
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_PROXY_SSL_CIPHER_LIST (3)
9  - CURLOPT_PROXY_TLS13_CIPHERS (3)
10  - CURLOPT_SSLVERSION (3)
11  - CURLOPT_TLS13_CIPHERS (3)
12  - CURLOPT_USE_SSL (3)
13Protocol:
14  - TLS
15TLS-backend:
16  - OpenSSL
17  - BearSSL
18  - Schannel
19  - Secure Transport
20  - wolfSSL
21  - GnuTLS
22  - mbedTLS
23---
24
25# NAME
26
27CURLOPT_SSL_CIPHER_LIST - ciphers to use for TLS
28
29# SYNOPSIS
30
31~~~c
32#include <curl/curl.h>
33
34CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list);
35~~~
36
37# DESCRIPTION
38
39Pass a char pointer, pointing to a null-terminated string holding the list of
40ciphers to use for the SSL connection. The list must be syntactically correct,
41it consists of one or more cipher strings separated by colons. Commas or
42spaces are also acceptable separators but colons are normally used, !, - and
43+ can be used as operators.
44
45For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**,
46**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally set when
47you compile OpenSSL.
48
49For WolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**,
50**AES256-SHA:AES256-SHA256**, etc.
51
52For mbedTLS and BearSSL, valid examples of cipher lists include
53**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using
54IANA names
55**TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**,
56etc. With mbedTLS and BearSSL you do not add/remove ciphers. If one uses this
57option then all known ciphers are disabled and only those passed in are
58enabled.
59
60For Schannel, you can use this option to set algorithms but not specific
61cipher suites. Refer to the ciphers lists document for algorithms.
62
63Find more details about cipher lists on this URL:
64
65 https://curl.se/docs/ssl-ciphers.html
66
67The application does not have to keep the string around after setting this
68option.
69
70# DEFAULT
71
72NULL, use internal default
73
74# EXAMPLE
75
76~~~c
77int main(void)
78{
79  CURL *curl = curl_easy_init();
80  if(curl) {
81    CURLcode res;
82    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
83    curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, "TLSv1");
84    res = curl_easy_perform(curl);
85    curl_easy_cleanup(curl);
86  }
87}
88~~~
89
90# AVAILABILITY
91
92Added in 7.9, in 7.83.0 for BearSSL, in 8.8.0 for mbedTLS
93
94If built TLS enabled.
95
96# RETURN VALUE
97
98Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
99CURLE_OUT_OF_MEMORY if there was insufficient heap space.
100