GNURLOPT_CAINFO(3)

💅 GNURLOPT_CAINFO(3) — the gnurl/easy_setopt era, bestie ✨

okay so real talk, this is one of those pages from the gnurl corner of the world — manual name GNURLOPT_CAINFO, function family curl_easy_setopt — and it's your whole guide to telling curl which file full of certificates to trust. let's go 🎀

---

✨ NAME ✨

CURLOPT_CAINFO — the path to your Certificate Authority (CA) bundle, aka the lil file of trust 💖

🦋 SYNOPSIS 🦋

#include <gnurl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO, char *path);

🌸 DESCRIPTION 🌸

so basically you pass in a char * pointing at a null-terminated string — and that string names a file holding one or more certificates you'll use to verify the peer with. that's it, that's the vibe 🫶

and here's the loophole, no cap: if CURLOPT_SSL_VERIFYPEER(3) is zero and you're deliberately skipping verification of the server's certificate, then CURLOPT_CAINFO(3) doesn't even have to point at an accessible file. like, it can just be vibes 💀

by default this option is set to the system path where libcurl's cacert bundle is assumed to live — as established at build time, iykyk ⭐

if curl is built against the NSS SSL library, then the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly. starting with curl-7.55.0, if both CURLOPT_CAINFO(3) and CURLOPT_CAPATH(3) are unset, NSS-linked libcurl tries to load libnssckbi.so — and that one's got a way more comprehensive set of trust info than nss-pem supports, because libnssckbi.so also includes info about distrusted certificates. messy but iconic 🔥

(iOS and macOS) when curl uses Secure Transport, this option is supported. if the option is not set, then curl will use the certificates in the system and user Keychain to verify the peer 🔑

(Schannel) this option is supported for Schannel in Windows 7 or later, but we recommend not using it until Windows 8, since it works better starting then. if the option is not set, then curl will use the certificates in the Windows' store of root certificates — which is the default for Schannel 🪟

and the best part? the application does not have to keep the string around after setting this option. set it and forget it, main character energy 👑

🎀 DEFAULT 🎀

Built-in system specific. when curl is built with Secure Transport or Schannel, this option is not set by default. periodt 💅

🌈 PROTOCOLS 🌈

all the TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. the whole secure squad 🧚

🍓 EXAMPLE 🍓

CURL *curl = curl_easy_init();
if(curl) {
  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
  curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/certs/cabundle.pem");
  ret = curl_easy_perform(curl);
  curl_easy_cleanup(curl);
}

⭐ AVAILABILITY ⭐

for the SSL engines that don't support certificate files, the CURLOPT_CAINFO option is just ignored 🙈. Schannel support was added in libcurl 7.60.

💜 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_CAPATH(3)
• CURLOPT_SSL_VERIFYPEER(3)
• CURLOPT_SSL_VERIFYHOST(3)

---

and that's the page, bestie 🫶 this one's served up from libcurl 7.37.0, dated 17 Jun 2014, living under the GNURLOPT_CAINFO(3) header — go forth and verify those peers ✨🎀💖