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_DARWINSSL, CURLSSLBACK‐
39 END_GNUTLS, CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_MBEDTLS, CURLSSLBACK‐
40 END_NSS, CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_POLARSSL, CURLSSLBACK‐
41 END_SCHANNEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL forks
42 are all reported 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 PolarSSL
65 ssl_context *
66 Secure Channel
68 CtxtHandle *
69 Secure Transport
71 SSLContext *
72 wolfSSL
74 SSL *
75 MesaLink
77 SSL *
78 If the internals pointer is NULL then either the SSL backend is not
80 supported, an SSL session has not yet been established or the connec‐
81 tion is no longer associated with the easy handle (eg curl_easy_perform
82 has returned).
83
85 This option has some limitations that could make it unsafe when it
86 comes to the manual verification of certificates.
87 This option only retrieves the first in-use SSL session pointer for
89 your easy handle, however your easy handle may have more than one in-
90 use SSL session if using FTP over SSL. That is because the FTP protocol
91 has a control channel and a data channel and one or both may be over
92 SSL. Currently there is no way to retrieve a second in-use SSL session
93 associated with an easy handle.
94 This option has not been thoroughly tested with plaintext protocols
96 that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when
97 used with CURLOPT_USE_SSL(3). Though you will be able to retrieve the
98 SSL pointer, it's possible that before you can do that data (including
99 auth) may have already been sent over a connection after it was
100 upgraded.
101 Renegotiation. If unsafe renegotiation or renegotiation in a way that
103 the certificate is allowed to change is allowed by your SSL library
104 this may occur and the certificate may change, and data may continue to
105 be sent or received after renegotiation but before you are able to get
106 the (possibly) changed SSL pointer, with the (possibly) changed cer‐
107 tificate information.
108 If you are using OpenSSL or wolfSSL then CURLOPT_SSL_CTX_FUNCTION(3)
110 can be used to set a certificate verification callback in the CTX. That
111 is safer than using this option to poll for certificate changes and
112 doesn't suffer from any of the problems above. There is currently no
113 way in libcurl to set a verification callback for the other SSL back‐
114 ends.
115 How are you using this option? Are you affected by any of these limita‐
117 tions? Please let us know by making a comment at
118 https://github.com/curl/curl/issues/685
119
121 All TLS-based
122
124 #include <curl/curl.h>
125 #include <openssl/ssl.h>
126 CURL *curl;
128 static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
129 {
130 const struct curl_tlssessioninfo *info = NULL;
131 CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
132 if(info && !res) {
133 if(CURLSSLBACKEND_OPENSSL == info->backend) {
134 printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
135 }
136 }
137 return size * nmemb;
138 }
139 int main(int argc, char** argv)
141 {
142 CURLcode res;
143 curl = curl_easy_init();
144 if(curl) {
145 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
146 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
147 res = curl_easy_perform(curl);
148 curl_easy_cleanup(curl);
149 }
150 return res;
151 }
152
154 Added in 7.48.0.
155 This option supersedes CURLINFO_TLS_SESSION(3) which was added in
157 7.34.0. This option is exactly the same as that option except in the
158 case of OpenSSL.
159
161 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION
162 if not.
163
165 curl_easy_getinfo(3), curl_easy_setopt(3), CURLINFO_TLS_SESSION(3),
166libcurl 7.66.0 July 16, 2019 CURLINFO_TLS_SSL_PTR(3)