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  - mbedTLS
22  - rustls
23Added-in: 7.9
24---
25
26# NAME
27
28CURLOPT_SSL_CIPHER_LIST - ciphers to use for TLS
29
30# SYNOPSIS
31
32~~~c
33#include <curl/curl.h>
34
35CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list);
36~~~
37
38# DESCRIPTION
39
40Pass a char pointer, pointing to a null-terminated string holding the list of
41cipher suites to use for the TLS 1.2 (1.1, 1.0) connection. The list must
42be syntactically correct, it consists of one or more cipher suite strings
43separated by colons.
44
45For setting TLS 1.3 ciphers see CURLOPT_TLS13_CIPHERS(3).
46
47A valid example of a cipher list is:
48~~~
49"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
50"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
51~~~
52
53For Schannel, you can use this option to set algorithms but not specific
54cipher suites. Refer to the ciphers lists document for algorithms.
55
56Find more details about cipher lists on this URL:
57
58 https://curl.se/docs/ssl-ciphers.html
59
60The application does not have to keep the string around after setting this
61option.
62
63Using this option multiple times makes the last set string override the
64previous ones. Set it to NULL to disable its use again.
65
66# DEFAULT
67
68NULL, use built-in list
69
70# %PROTOCOLS%
71
72# EXAMPLE
73
74~~~c
75int main(void)
76{
77  CURL *curl = curl_easy_init();
78  if(curl) {
79    CURLcode res;
80    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
81    curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST,
82                     "ECDHE-ECDSA-CHACHA20-POLY1305:"
83                     "ECDHE-RSA-CHACHA20-POLY1305");
84    res = curl_easy_perform(curl);
85    curl_easy_cleanup(curl);
86  }
87}
88~~~
89
90# HISTORY
91
92OpenSSL support added in 7.9.
93wolfSSL support added in 7.53.0.
94Schannel support added in 7.61.0.
95Secure Transport support added in 7.77.0.
96BearSSL support added in 7.83.0.
97mbedTLS support added in 8.8.0.
98Rustls support added in 8.10.0.
99
100Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported.
101
102# %AVAILABILITY%
103
104# RETURN VALUE
105
106Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.
107