Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

CURLINFO_TLS_SSL_PTR (3)

Name

CURLINFO_TLS_SSL_PTR - get TLS session info

Synopsis

#include <curl/curl.h>

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

/* if you need compatibility with libcurl < 7.48.0 use
CURLINFO_TLS_SESSION instead: */

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

Description

CURLINFO_TLS_SSL_PTR(3)    curl_easy_getinfo options   CURLINFO_TLS_SSL_PTR(3)



NAME
       CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR - get TLS session info

SYNOPSIS
       #include <curl/curl.h>

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

       /* if you need compatibility with libcurl < 7.48.0 use
          CURLINFO_TLS_SESSION instead: */

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

DESCRIPTION
       Pass  a  pointer to a 'struct curl_tlssessioninfo *'.  The pointer will
       be initialized to refer to a 'struct curl_tlssessioninfo *'  that  will
       contain an enum indicating the SSL library used for the handshake and a
       pointer to the respective internal TLS session structure of this under-
       lying SSL library.

       This  option  may be useful for example to extract certificate informa-
       tion in a format convenient for further processing, such as manual val-
       idation. Refer to the LIMITATIONS section.

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

       The backend struct member is one of the defines in the CURLSSLBACKEND_*
       series:  CURLSSLBACKEND_NONE  (when   built   without   TLS   support),
       CURLSSLBACKEND_CYASSL, CURLSSLBACKEND_DARWINSSL, CURLSSLBACKEND_GNUTLS,
       CURLSSLBACKEND_GSKIT,    CURLSSLBACKEND_MBEDTLS,    CURLSSLBACKEND_NSS,
       CURLSSLBACKEND_OPENSSL,  CURLSSLBACKEND_POLARSSL, CURLSSLBACKEND_SCHAN-
       NEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL  forks  are  all
       reported as just OpenSSL here.)

       The  internals  struct  member  will  point  to  a TLS library specific
       pointer for the active ("in use") SSL connection,  with  the  following
       underlying types:

              GnuTLS gnutls_session_t

              gskit  gsk_handle

              NSS    PRFileDesc *

              OpenSSL
                     CURLINFO_TLS_SESSION: SSL_CTX *

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

              mbedTLS
                     mbedtls_ssl_context *

              PolarSSL
                     ssl_context *

              Secure Channel
                     CtxtHandle *

              Secure Transport (DarwinSSL)
                     SSLContext *

              WolfSSL (formerly CyaSSL)
                     SSL *

              MesaLink
                     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 connec-
       tion is no longer associated with the easy handle (eg curl_easy_perform
       has returned).

LIMITATIONS
       This  option  has  some  limitations  that could make it unsafe when it
       comes to the manual verification of certificates.

       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.

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

       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  cer-
       tificate information.

       If  you  are  using OpenSSL or wolfSSL then CURLOPT_SSL_CTX_FUNCTION(3)
       can be used to set a certificate verification callback in the CTX. That
       is  safer  than  using  this option to poll for certificate changes and
       doesn't suffer from any of the problems above. There  is  currently  no
       way  in  libcurl to set a verification callback for the other SSL back-
       ends.

       How are you using this option? Are you affected by any of these limita-
       tions?     Please    let    us    know   by   making   a   comment   at
       https://github.com/curl/curl/issues/685

PROTOCOLS
       All TLS-based

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 res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
         if(info && !res) {
           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 res;
         curl = curl_easy_init();
         if(curl) {
           curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
           curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
           res = curl_easy_perform(curl);
           curl_easy_cleanup(curl);
         }
         return res;
       }

AVAILABILITY
       Added in 7.48.0.

       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.

RETURN VALUE
       Returns CURLE_OK if the option is supported,  and  CURLE_UNKNOWN_OPTION
       if not.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | web/curl         |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
SEE ALSO
       curl_easy_getinfo(3), curl_easy_setopt(3), CURLINFO_TLS_SESSION(3),



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source    was    downloaded    from    https://github.com/curl/curl/ar-
       chive/curl-7_64_0.zip

       Further information about this software can be found on the open source
       community website at http://curl.haxx.se/.



libcurl 7.48.0                    23 Feb 2016          CURLINFO_TLS_SSL_PTR(3)