CURLINFO_TLS_SSL_PTR(3)

📦
version 8.18.0 · 25 versions
, in fedora 44

💅 CURLINFO_TLS_SSL_PTR(3) — the libcurl manual page, bestie edition 🎀

okay so this is a page from the Library Functions Manual and it's all about CURLINFO_TLS_SSL_PTR, which is literally your backstage pass to the actual TLS session object your connection is using. no cap, it's a vibe. 🦋

✨ NAME ✨

CURLINFO_TLS_SSL_PTR — TLS session info 🫶

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
                           struct curl_tlssessioninfo **session);

💖 DESCRIPTION 💖

So you pass in a pointer to a struct curl_tlssessioninfo *. That pointer gets initialized to point at a struct curl_tlssessioninfo * that holds two things: an enum telling you which SSL library did the handshake, and a pointer to that library's own internal TLS session struct. it's giving "peek behind the curtain" energy. 👑

This option is lowkey useful when you wanna, say, pull certificate info out in a format that's convenient for further processing — like manual validation. but pls read the LIMITATIONS section first, bestie, fr fr.

struct curl_tlssessioninfo {
  curl_sslbackend backend;
  void *internals;
};

The backend struct member is one of these defines: CURLSSLBACKEND_NONE (that's when it's built without TLS support), CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL or CURLSSLBACKEND_SCHANNEL. (and yes, note that the OpenSSL forks are all reported as just OpenSSL here — they get lumped together, iykyk.)

The internals struct member points to a TLS library specific pointer for the active ("in use") SSL connection, with these underlying types 💅

Since 7.48.0 the internals member can point to these other SSL backends as well:

  • mbedTLS — mbedTLS_ssl_context *
  • Secure Channel — CtxtHandle *
  • wolfSSL — SSL *

If the internals pointer is NULL then either the SSL backend is not supported, an SSL session has not yet been established, or the connection is no longer associated with the easy handle (e.g. curl_easy_perform(3) has returned). so like, NULL is the "nothing to see here" of pointers 😭

💀 LIMITATIONS 💀

This option has some limitations that could make it unsafe when it comes to the manual verification of certificates. not me being dramatic — this is literally in the docs. 🚨

This option only retrieves the first in-use SSL session pointer for your easy handle, however your easy handle may have more than one in-use SSL session if using FTP over SSL. That is because the FTP protocol has a control channel and a data channel and one or both may be over SSL. Currently there is no way to retrieve a second in-use SSL session associated with an easy handle. one pointer per handle, that's the rule. 🙈

This option has not been thoroughly tested with clear text protocols that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it is possible that before you can do that, data (including auth) may have already been sent over a connection after it was upgraded. bestie that's your credentials out there, be careful 😭

Renegotiation. If unsafe renegotiation or renegotiation in a way that the certificate is allowed to change is allowed by your SSL library this may occur and the certificate may change, and data may continue to be sent or received after renegotiation but before you are able to get the (possibly) changed SSL pointer, with the (possibly) changed certificate information. it's giving race condition, and not the slay kind 💀

Instead of using this option to poll for certificate changes use CURLOPT_SSL_CTX_FUNCTION(3) to set a verification callback, if supported. That is safer and does not suffer from any of the problems above. do this instead, seriously, it's the main character move. 👑

How are you using this option? Are you affected by any of these limitations? Please let us know by making a comment at https://github.com/curl/curl/issues/685 — the curl girlies genuinely wanna hear from you 🫶

🌈 PROTOCOLS 🌈

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

This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, mbedTLS and wolfSSL ✅

⭐ EXAMPLE ⭐

#include <curl/curl.h>
#include <openssl/ssl.h>

CURL *curl;
static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
{
  const struct curl_tlssessioninfo *info = NULL;
  CURLcode result = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
  if(info && !result) {
    if(CURLSSLBACKEND_OPENSSL == info->backend) {
      printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
    }
  }
  return size * nmemb;
}

int main(int argc, char **argv)
{
  CURLcode result;
  curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
  return result;
}

look at her go, printing the OpenSSL version from inside a write callback. iconic. 🎀

🦋 HISTORY 🦋

This option supersedes CURLINFO_TLS_SESSION(3) which was added in 7.34.0. This option is exactly the same as that option except in the case of OpenSSL. glow-up secured ✨

🧚 AVAILABILITY 🧚

Added in curl 7.48.0

🍓 RETURN VALUE 🍓

curl_easy_getinfo(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3). zero is the slay outcome, anything else, check the errors page 💜

👑 SEE ALSO 👑

that's the whole page bestie, go forth and inspect your TLS sessions responsibly 💅✨

libcurl · 2026-10-12 · mwah, xoxo, your local manpage girlie 🎀💖

📦 where this page comes from