1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_TLS13_CIPHERS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_PROXY_SSLVERSION (3)
9  - CURLOPT_PROXY_SSL_CIPHER_LIST (3)
10  - CURLOPT_PROXY_TLS13_CIPHERS (3)
11  - CURLOPT_SSLVERSION (3)
12  - CURLOPT_SSL_CIPHER_LIST (3)
13  - CURLOPT_USE_SSL (3)
14Protocol:
15  - TLS
16TLS-backend:
17  - OpenSSL
18  - Schannel
19  - wolfSSL
20  - mbedTLS
21  - rustls
22Added-in: 7.61.0
23---
24
25# NAME
26
27CURLOPT_TLS13_CIPHERS - ciphers suites to use for TLS 1.3
28
29# SYNOPSIS
30
31~~~c
32#include <curl/curl.h>
33
34CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLS13_CIPHERS, char *list);
35~~~
36
37# DESCRIPTION
38
39Pass a char pointer, pointing to a null-terminated string holding the list of
40cipher suites to use for the TLS 1.3 connection. The list must be
41syntactically correct, it consists of one or more cipher suite strings
42separated by colons.
43
44For setting TLS 1.2 (1.1, 1.0) ciphers see CURLOPT_SSL_CIPHER_LIST(3).
45
46A valid example of a cipher list is:
47~~~c
48"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256"
49~~~
50
51Find more details about cipher lists on this URL:
52
53 https://curl.se/docs/ssl-ciphers.html
54
55The application does not have to keep the string around after setting this
56option.
57
58Using this option multiple times makes the last set string override the
59previous ones. Set it to NULL to restore to internal default.
60
61# DEFAULT
62
63NULL, use internal built-in
64
65# %PROTOCOLS%
66
67# EXAMPLE
68
69~~~c
70int main(void)
71{
72  CURL *curl = curl_easy_init();
73  if(curl) {
74    CURLcode res;
75    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
76    curl_easy_setopt(curl, CURLOPT_TLS13_CIPHERS,
77                     "TLS_CHACHA20_POLY1305_SHA256");
78    res = curl_easy_perform(curl);
79    curl_easy_cleanup(curl);
80  }
81}
82~~~
83
84# HISTORY
85
86OpenSSL support added in 7.61.0, available when built with OpenSSL \>= 1.1.1.
87Schannel support added in 7.85.0.
88LibreSSL support added in 8.3.0, available when built with LibreSSL \>= 3.4.1.
89wolfSSL support added in 8.10.0.
90mbedTLS support added in 8.10.0, available when built with mbedTLS \>= 3.6.0.
91Rustls support added in 8.10.0.
92
93Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites were set
94by using the CURLOPT_SSL_CIPHER_LIST(3) option.
95
96# %AVAILABILITY%
97
98# RETURN VALUE
99
100Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.
101