GNURLOPT_PROXY_ISSUERCERT(3)

Okay so bestie, this is the GNURLOPT_P..._ISSUERCERT(3) page from the curl_easy_setopt options manual — and it's giving “make sure your HTTPS proxy's issuer cert is exactly who you think it is.” No cap. 💖

🎀 NAME 🎀

• CURLOPT_PROXY_ISSUERCERT — proxy issuer SSL certificate filename 💅

✨ SYNOPSIS ✨

#include <gnurl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT, char
*file);

💅 DESCRIPTION 💅

Pass a char * to a null-terminated string that names a file holding a CA certificate in PEM format. Once this option is set, there's an extra check against the peer certificate: it verifies that the issuer of the HTTPS proxy is actually the one associated with the certificate you provided in the option. This extra check is lowkey iconic in multi-level PKI, where you need to enforce that the peer certificate comes from a specific branch of the tree. 🌳

⚠️ Vibe check: this option only makes sense when used together with the CURLOPT_PROXY_SSL_VERIFYPEER(3) option. Otherwise, the result of the check is not considered a failure. Periodt.

There's a specific error code, CURLE_SSL_ISSUER_ERROR, defined with this option. It gets returned if setting up the SSL/TLS session failed because of a mismatch with the issuer of the peer certificate — and yes, CURLOPT_PROXY_SSL_VERIFYPEER(3) has to be set too for the check to fail. 💀

The application does not have to keep the string around after setting this option. Set it and let it go, bestie. 🦋

🦋 DEFAULT 🦋

NULL

🌈 PROTOCOLS 🌈

All TLS-based protocols ✨

🍓 EXAMPLE 🍓

Here's the whole scenario — HTTPS proxy, custom issuer cert file, all the good stuff:

CURL *curl = curl_easy_init();
if(curl) {
  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
  /* using an HTTPS proxy */
  curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
  curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT, "/etc/certs/cacert.pem");
  ret = curl_easy_perform(curl);
  curl_easy_cleanup(curl);
}

⭐ AVAILABILITY ⭐

Added in libcurl 7.71.0. This option is supported by the OpenSSL backends.

👑 RETURN VALUE 👑

Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. 🫶

💜 SEE ALSO 💜

• CURLOPT_PROXY_SSL_VERIFYPEER(3)
• CURLOPT_PROXY_SSL_VERIFYHOST(3)
• CURLOPT_SSL_VERIFYPEER(3)
• CURLOPT_SSL_VERIFYHOST(3)

This page is from libcurl 7.71.0, dated 24 Jun 2020, and it's the GNURLOPT_P..._ISSUERCERT(3) page. Bye bestie — go make those issuers verified! 💖✨