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_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 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 axTLS SSL *
62 mbedTLS
64 mbedtls_ssl_context *
65 PolarSSL
67 ssl_context *
68 Secure Channel (WinSSL)
70 CtxtHandle *
71 Secure Transport (DarwinSSL)
73 SSLContext *
74 WolfSSL (formerly CyaSSL)
76 SSL *
77 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
84 This option has some limitations that could make it unsafe when it
85 comes to the manual verification of certificates.
86 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 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 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 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 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
120 All TLS-based
121
123 #include <curl/curl.h>
124 #include <openssl/ssl.h>
125 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 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
153 Added in 7.48.0.
154 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
160 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION
161 if not.
162
164 curl_easy_getinfo(3), curl_easy_setopt(3), CURLINFO_TLS_SESSION(3),
165libcurl 7.61.1 June 28, 2018 CURLINFO_TLS_SSL_PTR(3)