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