1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SSLVERSION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTP_VERSION (3)
9  - CURLOPT_IPRESOLVE (3)
10  - CURLOPT_PROXY_SSLVERSION (3)
11  - CURLOPT_USE_SSL (3)
12Protocol:
13  - TLS
14TLS-backend:
15  - All
16Added-in: 7.1
17---
18
19# NAME
20
21CURLOPT_SSLVERSION - preferred TLS/SSL version
22
23# SYNOPSIS
24
25~~~c
26#include <curl/curl.h>
27
28CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLVERSION, long version);
29~~~
30
31# DESCRIPTION
32
33Pass a long as parameter to control which version range of SSL/TLS versions to
34use.
35
36The SSL and TLS versions have typically developed from the most insecure
37version to be more and more secure in this order through history: SSL v2,
38SSLv3, TLS v1.0, TLS v1.1, TLS v1.2 and the most recent TLS v1.3.
39
40Use one of the available defines for this purpose. The available options are:
41
42## CURL_SSLVERSION_DEFAULT
43
44The default acceptable version range. The minimum acceptable version is by
45default TLS v1.0 since 7.39.0 (unless the TLS library has a stricter rule).
46
47## CURL_SSLVERSION_TLSv1
48
49TLS v1.0 or later
50
51## CURL_SSLVERSION_SSLv2
52
53SSL v2 - refused
54
55## CURL_SSLVERSION_SSLv3
56
57SSL v3 - refused
58
59## CURL_SSLVERSION_TLSv1_0
60
61TLS v1.0 or later (Added in 7.34.0)
62
63## CURL_SSLVERSION_TLSv1_1
64
65TLS v1.1 or later (Added in 7.34.0)
66
67## CURL_SSLVERSION_TLSv1_2
68
69TLS v1.2 or later (Added in 7.34.0)
70
71## CURL_SSLVERSION_TLSv1_3
72
73TLS v1.3 or later (Added in 7.52.0)
74
75##
76
77The maximum TLS version can be set by using *one* of the
78CURL_SSLVERSION_MAX_ macros below. It is also possible to OR *one* of the
79CURL_SSLVERSION_ macros with *one* of the CURL_SSLVERSION_MAX_ macros.
80
81## CURL_SSLVERSION_MAX_DEFAULT
82
83The flag defines the maximum supported TLS version by libcurl, or the default
84value from the SSL library is used. libcurl uses a sensible default maximum,
85which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then - assuming
86the TLS library support it. (Added in 7.54.0)
87
88## CURL_SSLVERSION_MAX_TLSv1_0
89
90The flag defines maximum supported TLS version as TLS v1.0.
91(Added in 7.54.0)
92
93## CURL_SSLVERSION_MAX_TLSv1_1
94
95The flag defines maximum supported TLS version as TLS v1.1.
96(Added in 7.54.0)
97
98## CURL_SSLVERSION_MAX_TLSv1_2
99
100The flag defines maximum supported TLS version as TLS v1.2.
101(Added in 7.54.0)
102
103## CURL_SSLVERSION_MAX_TLSv1_3
104
105The flag defines maximum supported TLS version as TLS v1.3.
106(Added in 7.54.0)
107
108##
109
110In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were
111documented to allow *only* the specified TLS version, but behavior was
112inconsistent depending on the TLS library.
113
114# DEFAULT
115
116CURL_SSLVERSION_DEFAULT
117
118# %PROTOCOLS%
119
120# EXAMPLE
121
122~~~c
123int main(void)
124{
125  CURL *curl = curl_easy_init();
126  if(curl) {
127    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
128
129    /* ask libcurl to use TLS version 1.0 or later */
130    curl_easy_setopt(curl, CURLOPT_SSLVERSION, (long)CURL_SSLVERSION_TLSv1);
131
132    /* Perform the request */
133    curl_easy_perform(curl);
134  }
135}
136~~~
137
138# HISTORY
139
140SSLv2 is disabled by default since 7.18.1. Other SSL versions availability may
141vary depending on which backend libcurl has been built to use.
142
143SSLv3 is disabled by default since 7.39.0.
144
145SSLv2 and SSLv3 are refused completely since curl 7.77.0
146
147Since 8.10.0 wolfSSL is fully supported. Before 8.10.0 the MAX macros were not
148supported with wolfSSL and the other macros did not set a minimum, but
149restricted the TLS version to only the specified one.
150
151Rustls support added in 8.10.0.
152
153# %AVAILABILITY%
154
155# RETURN VALUE
156
157Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
158