1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SSL_OPTIONS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_PROXY_SSL_OPTIONS (3)
9  - CURLOPT_SSLVERSION (3)
10  - CURLOPT_SSL_CIPHER_LIST (3)
11Protocol:
12  - TLS
13TLS-backend:
14  - All
15---
16
17# NAME
18
19CURLOPT_SSL_OPTIONS - SSL behavior options
20
21# SYNOPSIS
22
23~~~c
24#include <curl/curl.h>
25
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask);
27~~~
28
29# DESCRIPTION
30
31Pass a long with a bitmask to tell libcurl about specific SSL
32behaviors. Available bits:
33
34## CURLSSLOPT_ALLOW_BEAST
35
36Tells libcurl to not attempt to use any workarounds for a security flaw in the
37SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0,
38the SSL layer libcurl uses may use a work-around for this flaw although it
39might cause interoperability problems with some (older) SSL implementations.
40WARNING: avoiding this work-around lessens the security, and by setting this
41option to 1 you ask for exactly that. This option is only supported for Secure
42Transport and OpenSSL.
43
44## CURLSSLOPT_NO_REVOKE
45
46Tells libcurl to disable certificate revocation checks for those SSL backends
47where such behavior is present. This option is only supported for Schannel
48(the native Windows SSL library), with an exception in the case of Windows'
49Untrusted Publishers block list which it seems cannot be bypassed. (Added in
507.44.0)
51
52## CURLSSLOPT_NO_PARTIALCHAIN
53
54Tells libcurl to not accept "partial" certificate chains, which it otherwise
55does by default. This option is only supported for OpenSSL and fails the
56certificate verification if the chain ends with an intermediate certificate
57and not with a root cert. (Added in 7.68.0)
58
59## CURLSSLOPT_REVOKE_BEST_EFFORT
60
61Tells libcurl to ignore certificate revocation checks in case of missing or
62offline distribution points for those SSL backends where such behavior is
63present. This option is only supported for Schannel (the native Windows SSL
64library). If combined with *CURLSSLOPT_NO_REVOKE*, the latter takes
65precedence. (Added in 7.70.0)
66
67## CURLSSLOPT_NATIVE_CA
68
69Tell libcurl to use the operating system's native CA store for certificate
70verification. If you set this option and also set a CA certificate file or
71directory then during verification those certificates are searched in addition
72to the native CA store.
73
74Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL),
75macOS, Android and iOS (added in 8.3.0), with GnuTLS (added in 8.5.0) or on
76Windows when built to use OpenSSL (Added in 7.71.0).
77
78## CURLSSLOPT_AUTO_CLIENT_CERT
79
80Tell libcurl to automatically locate and use a client certificate for
81authentication, when requested by the server. This option is only supported
82for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the
83default behavior in libcurl with Schannel. Since the server can request any
84certificate that supports client authentication in the OS certificate store it
85could be a privacy violation and unexpected.
86(Added in 7.77.0)
87
88# DEFAULT
89
900
91
92# EXAMPLE
93
94~~~c
95int main(void)
96{
97  CURL *curl = curl_easy_init();
98  if(curl) {
99    CURLcode res;
100    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
101    /* weaken TLS only for use with silly servers */
102    curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, (long)CURLSSLOPT_ALLOW_BEAST |
103                     CURLSSLOPT_NO_REVOKE);
104    res = curl_easy_perform(curl);
105    curl_easy_cleanup(curl);
106  }
107}
108~~~
109
110# AVAILABILITY
111
112Added in 7.25.0
113
114# RETURN VALUE
115
116Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
117