CURLOPT_PROXY_SSL_OPTIONS(3)

📦
version 8.18.0 · 25 versions
, in fedora 44

💅 CURLOPT_PROXY_SSL_OPTIONS(3) ✨

okay bestie, welcome to the libcurl manual, Library Functions Manual section, and today's main character is CURLOPT_PROXY_SSL_OPTIONS — literally the vibe-check dial for how libcurl does SSL with your HTTPS proxy. 🎀

🌸 NAME 🌸

CURLOPT_PROXY_SSL_OPTIONS — HTTPS proxy SSL behavior options. that's it, that's the whole name, and honestly? iconic.

✨ SYNOPSIS ✨

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_OPTIONS,
                          long bitmask);

🦋 DESCRIPTION 🦋

so you pass a long that's a bitmask, and it tells libcurl all about the specific SSL behaviors you want. it's giving "settings menu but make it binary." here are the available bits, no cap:

🌈 the bits

  • CURLSSLOPT_ALLOW_BEAST — tells libcurl to not attempt any workarounds for a security flaw in the SSL3 and TLS1.0 protocols. if you don't use this option, or this bit is set to 0, the SSL layer libcurl uses may use a work-around for this flaw — which honestly might cause interoperability problems with some (older) SSL implementations. ⚠️ WARNING: avoiding this work-around lessens the security, and by setting this option to 1 you are asking for exactly that. yes, you read that right. this option is only supported for Secure Transport and OpenSSL.
  • CURLSSLOPT_NO_REVOKE — tells libcurl to disable certificate revocation checks for those SSL backends where such behavior is present. this one's only supported for Schannel (the native Windows SSL library), with an exception in the case of Windows' Untrusted Publishers block list, which it seems cannot be bypassed. 😭 rude.
  • CURLSSLOPT_NO_PARTIALCHAIN — tells libcurl to not accept "partial" certificate chains, which it otherwise does by default. this option fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. 💀
    • works with OpenSSL and its forks (LibreSSL, BoringSSL, etc). (Added in 7.68.0)
    • works with Schannel if the user specified certificates to verify the peer. (Added in 8.15.0)
  • CURLSSLOPT_REVOKE_BEST_EFFORT — tells libcurl to ignore certificate revocation checks in case of missing or offline distribution points, for those SSL backends where such behavior is present. only supported for Schannel (the native Windows SSL library). if you combine it with CURLSSLOPT_NO_REVOKE, the latter takes precedence. (Added in 7.70.0)
  • CURLSSLOPT_NATIVE_CA — tell libcurl to use the operating system's native CA store for certificate verification. this option is independent of other CA certificate locations set at run time or build time — those locations are searched in addition to the native CA store. 🫶
    • works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), macOS, Android and iOS (added in 8.3.0); with GnuTLS (added in 8.5.0) and with OpenSSL and its forks (LibreSSL, BoringSSL, etc) on Windows (Added in 7.71.0).
  • CURLSSLOPT_AUTO_CLIENT_CERT — tell libcurl to automatically locate and use a client certificate for authentication, when requested by the server. only supported for Schannel (the native Windows SSL library). prior to 7.77.0 this was the default behavior in libcurl with Schannel. and listen — since the server can request any certificate that supports client authentication in the OS certificate store, it could be a privacy violation and unexpected. 🙈 (Added in 7.77.0)

🍓 DEFAULT 🍓

0

💜 PROTOCOLS 💜

this functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. 🌈

all TLS backends support this option. slay.

🔥 EXAMPLE 🔥

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
    curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy.example");
    /* weaken TLS only for use with silly proxies */
    curl_easy_setopt(curl, CURLOPT_PROXY_SSL_OPTIONS,
                     CURLSSLOPT_ALLOW_BEAST | CURLSSLOPT_NO_REVOKE);
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

look at that comment. "weaken TLS only for use with silly proxies." the honesty. the audacity. we stan. 👑

⭐ HISTORY ⭐

CURLSSLOPT_* macros became long types in 8.15.0. prior to this version, a long cast was necessary when passed to curl_easy_setopt(3). glow-up era fr fr.

🧚 AVAILABILITY 🧚

Added in curl 7.52.0. vintage but still relevant bestie.

👑 RETURN VALUE 👑

curl_easy_setopt(3) returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, and non-zero means an error occurred — see libcurl-errors(3). 💖

🌸 SEE ALSO 🌸

go read them, iykyk 🦋

and that's the whole page, bestie — brought to you by libcurl, dated 2026-10-12, and yes the header said CURLOPT_PROXY_SSL_OPTIONS(3) in section 3 all along. mwah 💋✨

📦 where this page comes from