1CURLINFO_TLS_SSL_PTR(3)    curl_easy_getinfo options   CURLINFO_TLS_SSL_PTR(3)
2
3
4

NAME

6       CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR - get TLS session info
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
12                                  struct curl_tlssessioninfo **session);
13
14       /* if you need compatibility with libcurl < 7.48.0 use
15          CURLINFO_TLS_SESSION instead: */
16
17       CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
18                                  struct curl_tlssessioninfo **session);
19

DESCRIPTION

21       Pass  a  pointer to a 'struct curl_tlssessioninfo *'.  The pointer will
22       be initialized to refer to a 'struct curl_tlssessioninfo *'  that  will
23       contain an enum indicating the SSL library used for the handshake and a
24       pointer to the respective internal TLS session structure of this under‐
25       lying SSL library.
26
27       This  option  may be useful for example to extract certificate informa‐
28       tion in a format convenient for further processing, such as manual val‐
29       idation. Refer to the LIMITATIONS section.
30
31       struct curl_tlssessioninfo {
32         curl_sslbackend backend;
33         void *internals;
34       };
35
36       The backend struct member is one of the defines in the CURLSSLBACKEND_*
37       series:  CURLSSLBACKEND_NONE  (when   built   without   TLS   support),
38       CURLSSLBACKEND_AXTLS,  CURLSSLBACKEND_CYASSL, CURLSSLBACKEND_DARWINSSL,
39       CURLSSLBACKEND_GNUTLS,  CURLSSLBACKEND_GSKIT,   CURLSSLBACKEND_MBEDTLS,
40       CURLSSLBACKEND_NSS,  CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_POLARSSL or
41       CURLSSLBACKEND_SCHANNEL. (Note that the OpenSSL forks are all  reported
42       as just OpenSSL here.)
43
44       The  internals  struct  member  will  point  to  a TLS library specific
45       pointer for the active ("in use") SSL connection,  with  the  following
46       underlying types:
47
48              GnuTLS gnutls_session_t
49
50              gskit  gsk_handle
51
52              NSS    PRFileDesc *
53
54              OpenSSL
55                     CURLINFO_TLS_SESSION: SSL_CTX *
56
57                     CURLINFO_TLS_SSL_PTR: SSL *
58       Since 7.48.0 the internals member can point to these other SSL backends
59       as well:
60
61              axTLS  SSL *
62
63              mbedTLS
64                     mbedtls_ssl_context *
65
66              PolarSSL
67                     ssl_context *
68
69              Secure Channel (WinSSL)
70                     CtxtHandle *
71
72              Secure Transport (DarwinSSL)
73                     SSLContext *
74
75              WolfSSL (formerly CyaSSL)
76                     SSL *
77
78       If the internals pointer is NULL then either the  SSL  backend  is  not
79       supported,  an  SSL session has not yet been established or the connec‐
80       tion is no longer associated with the easy handle (eg curl_easy_perform
81       has returned).
82

LIMITATIONS

84       This  option  has  some  limitations  that could make it unsafe when it
85       comes to the manual verification of certificates.
86
87       This option only retrieves the first in-use  SSL  session  pointer  for
88       your  easy  handle, however your easy handle may have more than one in-
89       use SSL session if using FTP over SSL. That is because the FTP protocol
90       has  a  control  channel and a data channel and one or both may be over
91       SSL. Currently there is no way to retrieve a second in-use SSL  session
92       associated with an easy handle.
93
94       This  option  has  not  been thoroughly tested with plaintext protocols
95       that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when
96       used  with  CURLOPT_USE_SSL(3). Though you will be able to retrieve the
97       SSL pointer, it's possible that before you can do that data  (including
98       auth)  may  have  already  been  sent  over  a  connection after it was
99       upgraded.
100
101       Renegotiation. If unsafe renegotiation or renegotiation in a  way  that
102       the  certificate  is  allowed  to change is allowed by your SSL library
103       this may occur and the certificate may change, and data may continue to
104       be  sent or received after renegotiation but before you are able to get
105       the (possibly) changed SSL pointer, with the  (possibly)  changed  cer‐
106       tificate information.
107
108       If  you  are  using OpenSSL or wolfSSL then CURLOPT_SSL_CTX_FUNCTION(3)
109       can be used to set a certificate verification callback in the CTX. That
110       is  safer  than  using  this option to poll for certificate changes and
111       doesn't suffer from any of the problems above. There  is  currently  no
112       way  in  libcurl to set a verification callback for the other SSL back‐
113       ends.
114
115       How are you using this option? Are you affected by any of these limita‐
116       tions?     Please    let    us    know   by   making   a   comment   at
117       https://github.com/curl/curl/issues/685
118

PROTOCOLS

120       All TLS-based
121

EXAMPLE

123       #include <curl/curl.h>
124       #include <openssl/ssl.h>
125
126       CURL *curl;
127       static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
128       {
129         const struct curl_tlssessioninfo *info = NULL;
130         CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
131         if(info && !res) {
132           if(CURLSSLBACKEND_OPENSSL == info->backend) {
133              printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
134           }
135         }
136         return size * nmemb;
137       }
138
139       int main(int argc, char** argv)
140       {
141         CURLcode res;
142         curl = curl_easy_init();
143         if(curl) {
144           curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
145           curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
146           res = curl_easy_perform(curl);
147           curl_easy_cleanup(curl);
148         }
149         return res;
150       }
151

AVAILABILITY

153       Added in 7.48.0.
154
155       This option  supersedes  CURLINFO_TLS_SESSION(3)  which  was  added  in
156       7.34.0.   This  option is exactly the same as that option except in the
157       case of OpenSSL.
158

RETURN VALUE

160       Returns CURLE_OK if the option is supported,  and  CURLE_UNKNOWN_OPTION
161       if not.
162

SEE ALSO

164       curl_easy_getinfo(3), curl_easy_setopt(3), CURLINFO_TLS_SESSION(3),
165
166
167
168libcurl 7.61.1                   June 28, 2018         CURLINFO_TLS_SSL_PTR(3)
Impressum