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