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