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 be
22 initialized to refer to a struct curl_tlssessioninfo * that will con‐
23 tain 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(3): SSL_CTX *
56 CURLINFO_TLS_SSL_PTR(3): 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 If the internals pointer is NULL then either the SSL backend is not
74 supported, an SSL session has not yet been established or the connec‐
75 tion is no longer associated with the easy handle (e.g. curl_easy_per‐
76 form has returned).
77
79 This option has some limitations that could make it unsafe when it
80 comes to the manual verification of certificates.
81 This option only retrieves the first in-use SSL session pointer for
83 your easy handle, however your easy handle may have more than one in-
84 use SSL session if using FTP over SSL. That is because the FTP protocol
85 has a control channel and a data channel and one or both may be over
86 SSL. Currently there is no way to retrieve a second in-use SSL session
87 associated with an easy handle.
88 This option has not been thoroughly tested with clear text protocols
90 that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when
91 used with CURLOPT_USE_SSL(3). Though you will be able to retrieve the
92 SSL pointer, it's possible that before you can do that data (including
93 auth) may have already been sent over a connection after it was up‐
94 graded.
95 Renegotiation. If unsafe renegotiation or renegotiation in a way that
97 the certificate is allowed to change is allowed by your SSL library
98 this may occur and the certificate may change, and data may continue to
99 be sent or received after renegotiation but before you are able to get
100 the (possibly) changed SSL pointer, with the (possibly) changed cer‐
101 tificate information.
102 If you are using OpenSSL or wolfSSL then CURLOPT_SSL_CTX_FUNCTION(3)
104 can be used to set a certificate verification callback. That is safer
105 than using this option to poll for certificate changes and does not
106 suffer from any of the problems above. There is currently no way in
107 libcurl to set a verification callback for the other SSL backends.
108 How are you using this option? Are you affected by any of these limita‐
110 tions? Please let us know by making a comment at
111 https://github.com/curl/curl/issues/685
112
114 All TLS-based
115
117 #include <curl/curl.h>
118 #include <openssl/ssl.h>
119 CURL *curl;
121 static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
122 {
123 const struct curl_tlssessioninfo *info = NULL;
124 CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
125 if(info && !res) {
126 if(CURLSSLBACKEND_OPENSSL == info->backend) {
127 printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
128 }
129 }
130 return size * nmemb;
131 }
132 int main(int argc, char** argv)
134 {
135 CURLcode res;
136 curl = curl_easy_init();
137 if(curl) {
138 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
139 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
140 res = curl_easy_perform(curl);
141 curl_easy_cleanup(curl);
142 }
143 return res;
144 }
145
147 Added in 7.48.0.
148 This option supersedes CURLINFO_TLS_SESSION(3) which was added in
150 7.34.0. This option is exactly the same as that option except in the
151 case of OpenSSL.
152
154 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION
155 if not.
156
158 curl_easy_getinfo(3), curl_easy_setopt(3), CURLINFO_TLS_SESSION(3),
159libcurl 8.0.1 January 02, 2023 CURLINFO_TLS_SSL_PTR(3)