1CURLINFO_TLS_SSL_PTR(3) curl_easy_getinfo options CURLINFO_TLS_SSL_PTR(3)
2
6 CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR - get TLS session info
7
9 #include <curl/curl.h>
10 CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
12 struct curl_tlssessioninfo **session);
13 /* if you need compatibility with libcurl < 7.48.0 use
15 CURLINFO_TLS_SESSION instead: */
16 CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
18 struct curl_tlssessioninfo **session);
19
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 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 struct curl_tlssessioninfo {
32 curl_sslbackend backend;
33 void *internals;
34 };
35 The backend struct member is one of the defines in the CURLSSLBACKEND_*
37 series: CURLSSLBACKEND_NONE (when built without TLS support),
38 CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACK‐
39 END_GNUTLS, CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_MBEDTLS, CURLSSLBACK‐
40 END_NSS, CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_SCHANNEL or
41 CURLSSLBACKEND_MESALINK. (Note that the OpenSSL forks are all reported
42 as just OpenSSL here.)
43 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 GnuTLS gnutls_session_t
49 gskit gsk_handle
51 NSS PRFileDesc *
53 OpenSSL
55 CURLINFO_TLS_SESSION: SSL_CTX *
56 CURLINFO_TLS_SSL_PTR: SSL *
58 Since 7.48.0 the internals member can point to these other SSL backends
59 as well:
60 mbedTLS
62 mbedtls_ssl_context *
63 Secure Channel
65 CtxtHandle *
66 Secure Transport
68 SSLContext *
69 wolfSSL
71 SSL *
72 MesaLink
74 SSL *
75 If the internals pointer is NULL then either the SSL backend is not
77 supported, an SSL session has not yet been established or the connec‐
78 tion is no longer associated with the easy handle (eg curl_easy_perform
79 has returned).
80
82 This option has some limitations that could make it unsafe when it
83 comes to the manual verification of certificates.
84 This option only retrieves the first in-use SSL session pointer for
86 your easy handle, however your easy handle may have more than one in-
87 use SSL session if using FTP over SSL. That is because the FTP protocol
88 has a control channel and a data channel and one or both may be over
89 SSL. Currently there is no way to retrieve a second in-use SSL session
90 associated with an easy handle.
91 This option has not been thoroughly tested with plaintext protocols
93 that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when
94 used with CURLOPT_USE_SSL(3). Though you will be able to retrieve the
95 SSL pointer, it's possible that before you can do that data (including
96 auth) may have already been sent over a connection after it was up‐
97 graded.
98 Renegotiation. If unsafe renegotiation or renegotiation in a way that
100 the certificate is allowed to change is allowed by your SSL library
101 this may occur and the certificate may change, and data may continue to
102 be sent or received after renegotiation but before you are able to get
103 the (possibly) changed SSL pointer, with the (possibly) changed cer‐
104 tificate information.
105 If you are using OpenSSL or wolfSSL then CURLOPT_SSL_CTX_FUNCTION(3)
107 can be used to set a certificate verification callback in the CTX. That
108 is safer than using this option to poll for certificate changes and
109 doesn't suffer from any of the problems above. There is currently no
110 way in libcurl to set a verification callback for the other SSL back‐
111 ends.
112 How are you using this option? Are you affected by any of these limita‐
114 tions? Please let us know by making a comment at
115 https://github.com/curl/curl/issues/685
116
118 All TLS-based
119
121 #include <curl/curl.h>
122 #include <openssl/ssl.h>
123 CURL *curl;
125 static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
126 {
127 const struct curl_tlssessioninfo *info = NULL;
128 CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
129 if(info && !res) {
130 if(CURLSSLBACKEND_OPENSSL == info->backend) {
131 printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
132 }
133 }
134 return size * nmemb;
135 }
136 int main(int argc, char** argv)
138 {
139 CURLcode res;
140 curl = curl_easy_init();
141 if(curl) {
142 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
143 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
144 res = curl_easy_perform(curl);
145 curl_easy_cleanup(curl);
146 }
147 return res;
148 }
149
151 Added in 7.48.0.
152 This option supersedes CURLINFO_TLS_SESSION(3) which was added in
154 7.34.0. This option is exactly the same as that option except in the
155 case of OpenSSL.
156
158 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION
159 if not.
160
162 curl_easy_getinfo(3), curl_easy_setopt(3), CURLINFO_TLS_SESSION(3),
163libcurl 7.76.1 November 04, 2020 CURLINFO_TLS_SSL_PTR(3)