CURLOPT_SSL_OPTIONS.md (4611B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: CURLOPT_SSL_OPTIONS 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_PROXY_SSL_OPTIONS (3) 9 - CURLOPT_SSLVERSION (3) 10 - CURLOPT_SSL_CIPHER_LIST (3) 11 Protocol: 12 - TLS 13 TLS-backend: 14 - All 15 Added-in: 7.25.0 16 --- 17 18 # NAME 19 20 CURLOPT_SSL_OPTIONS - SSL behavior options 21 22 # SYNOPSIS 23 24 ~~~c 25 #include <curl/curl.h> 26 27 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask); 28 ~~~ 29 30 # DESCRIPTION 31 32 Pass a long with a bitmask to tell libcurl about specific SSL 33 behaviors. Available bits: 34 35 ## CURLSSLOPT_ALLOW_BEAST 36 37 Tells libcurl to not attempt to use any workarounds for a security flaw in the 38 SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, 39 the SSL layer libcurl uses may use a work-around for this flaw although it 40 might cause interoperability problems with some (older) SSL implementations. 41 WARNING: avoiding this work-around lessens the security, and by setting this 42 option to 1 you ask for exactly that. This option is only supported for Secure 43 Transport and OpenSSL. 44 45 ## CURLSSLOPT_NO_REVOKE 46 47 Tells libcurl to disable certificate revocation checks for those SSL backends 48 where such behavior is present. This option is only supported for Schannel 49 (the native Windows SSL library), with an exception in the case of Windows' 50 Untrusted Publishers block list which it seems cannot be bypassed. (Added in 51 7.44.0) 52 53 ## CURLSSLOPT_NO_PARTIALCHAIN 54 55 Tells libcurl to not accept "partial" certificate chains, which it otherwise 56 does by default. This option fails the certificate verification if the chain 57 ends with an intermediate certificate and not with a root cert. 58 59 Works with OpenSSL and its forks (LibreSSL, BoringSSL, etc). (Added in 7.68.0) 60 61 Works with Schannel if the user specified certificates to verify the peer. 62 (Added in 8.15.0) 63 64 ## CURLSSLOPT_REVOKE_BEST_EFFORT 65 66 Tells libcurl to ignore certificate revocation checks in case of missing or 67 offline distribution points for those SSL backends where such behavior is 68 present. This option is only supported for Schannel (the native Windows SSL 69 library). If combined with *CURLSSLOPT_NO_REVOKE*, the latter takes 70 precedence. (Added in 7.70.0) 71 72 ## CURLSSLOPT_NATIVE_CA 73 74 Tell libcurl to use the operating system's native CA store for certificate 75 verification. This option is independent of other CA certificate locations set 76 at run time or build time. Those locations are searched in addition to the 77 native CA store. 78 79 Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), 80 macOS, Android and iOS (added in 8.3.0); with GnuTLS (added in 8.5.0) and with 81 OpenSSL and its forks (LibreSSL, BoringSSL, etc) on Windows (Added in 7.71.0). 82 83 This works with rustls on Windows, macOS, Android and iOS. On Linux it is 84 equivalent to using the Mozilla CA certificate bundle. When used with rustls 85 _only_ the native CA store is consulted, not other locations set at run time or 86 build time. (Added in 8.13.0) 87 88 ## CURLSSLOPT_AUTO_CLIENT_CERT 89 90 Tell libcurl to automatically locate and use a client certificate for 91 authentication, when requested by the server. This option is only supported 92 for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the 93 default behavior in libcurl with Schannel. Since the server can request any 94 certificate that supports client authentication in the OS certificate store it 95 could be a privacy violation and unexpected. 96 (Added in 7.77.0) 97 98 ## CURLSSLOPT_EARLYDATA 99 100 Tell libcurl to try sending application data as TLS1.3 early data. This option 101 is supported for GnuTLS, wolfSSL, quictls and OpenSSL (but not BoringSSL 102 or AWS-LC). It works on TCP and QUIC connections using ngtcp2. 103 This option works on a best effort basis, 104 in cases when it wasn't possible to send early data the request is resent 105 normally post-handshake. 106 This option does not work when using QUIC. 107 (Added in 8.11.0 for GnuTLS and 8.13.0 for wolfSSL, quictls and OpenSSL) 108 109 # DEFAULT 110 111 0 112 113 # %PROTOCOLS% 114 115 # EXAMPLE 116 117 ~~~c 118 int main(void) 119 { 120 CURL *curl = curl_easy_init(); 121 if(curl) { 122 CURLcode res; 123 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); 124 /* weaken TLS only for use with silly servers */ 125 curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, (long)CURLSSLOPT_ALLOW_BEAST | 126 CURLSSLOPT_NO_REVOKE); 127 res = curl_easy_perform(curl); 128 curl_easy_cleanup(curl); 129 } 130 } 131 ~~~ 132 133 # %AVAILABILITY% 134 135 # RETURN VALUE 136 137 curl_easy_setopt(3) returns a CURLcode indicating success or error. 138 139 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 140 libcurl-errors(3).