• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLINFO_TLS_SSL_PTR
5Section: 3
6Source: libcurl
7See-also:
8  - CURLINFO_TLS_SESSION (3)
9  - curl_easy_getinfo (3)
10  - curl_easy_setopt (3)
11---
12
13# NAME
14
15CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR - get TLS session info
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
23                           struct curl_tlssessioninfo **session);
24
25/* if you need compatibility with libcurl < 7.48.0 use
26   CURLINFO_TLS_SESSION instead: */
27
28CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
29                           struct curl_tlssessioninfo **session);
30~~~
31
32# DESCRIPTION
33
34Pass a pointer to a *struct curl_tlssessioninfo **. The pointer is initialized
35to refer to a *struct curl_tlssessioninfo ** that contains an enum indicating
36the SSL library used for the handshake and a pointer to the respective
37internal TLS session structure of this underlying SSL library.
38
39This option may be useful for example to extract certificate information in a
40format convenient for further processing, such as manual validation. Refer to
41the **LIMITATIONS** section.
42
43~~~c
44struct curl_tlssessioninfo {
45  curl_sslbackend backend;
46  void *internals;
47};
48~~~
49
50The *backend* struct member is one of the defines in the CURLSSLBACKEND_*
51series: CURLSSLBACKEND_NONE (when built without TLS support),
52CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS,
53CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL,
54CURLSSLBACKEND_SCHANNEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL
55forks are all reported as just OpenSSL here.)
56
57The *internals* struct member points to a TLS library specific pointer for
58the active ("in use") SSL connection, with the following underlying types:
59
60## GnuTLS
61
62**gnutls_session_t**
63
64## NSS
65
66**PRFileDesc ***
67
68## OpenSSL
69
70CURLINFO_TLS_SESSION(3): **SSL_CTX ***
71
72CURLINFO_TLS_SSL_PTR(3): **SSL ***
73Since 7.48.0 the *internals* member can point to these other SSL backends
74as well:
75
76## mbedTLS
77
78**mbedTLS_ssl_context ***
79
80## Secure Channel
81
82**CtxtHandle ***
83
84## Secure Transport
85
86**SSLContext ***
87
88## wolfSSL
89
90**SSL ***
91
92If the *internals* pointer is NULL then either the SSL backend is not
93supported, an SSL session has not yet been established or the connection is no
94longer associated with the easy handle (e.g. curl_easy_perform(3) has
95returned).
96
97# LIMITATIONS
98
99This option has some limitations that could make it unsafe when it comes to
100the manual verification of certificates.
101
102This option only retrieves the first in-use SSL session pointer for your easy
103handle, however your easy handle may have more than one in-use SSL session if
104using FTP over SSL. That is because the FTP protocol has a control channel and
105a data channel and one or both may be over SSL. Currently there is no way to
106retrieve a second in-use SSL session associated with an easy handle.
107
108This option has not been thoroughly tested with clear text protocols that can
109be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with
110CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it is possible
111that before you can do that, data (including auth) may have already been sent
112over a connection after it was upgraded.
113
114Renegotiation. If unsafe renegotiation or renegotiation in a way that the
115certificate is allowed to change is allowed by your SSL library this may occur
116and the certificate may change, and data may continue to be sent or received
117after renegotiation but before you are able to get the (possibly) changed SSL
118pointer, with the (possibly) changed certificate information.
119
120Instead of using this option to poll for certificate changes use
121CURLOPT_SSL_CTX_FUNCTION(3) to set a verification callback, if supported.
122That is safer and does not suffer from any of the problems above.
123
124How are you using this option? Are you affected by any of these limitations?
125Please let us know by making a comment at
126https://github.com/curl/curl/issues/685
127
128# PROTOCOLS
129
130All TLS-based
131
132# EXAMPLE
133
134~~~c
135#include <curl/curl.h>
136#include <openssl/ssl.h>
137
138CURL *curl;
139static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
140{
141  const struct curl_tlssessioninfo *info = NULL;
142  CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
143  if(info && !res) {
144    if(CURLSSLBACKEND_OPENSSL == info->backend) {
145      printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
146    }
147  }
148  return size * nmemb;
149}
150
151int main(int argc, char **argv)
152{
153  CURLcode res;
154  curl = curl_easy_init();
155  if(curl) {
156    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
157    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
158    res = curl_easy_perform(curl);
159    curl_easy_cleanup(curl);
160  }
161  return res;
162}
163~~~
164
165# AVAILABILITY
166
167Added in 7.48.0.
168
169This option supersedes CURLINFO_TLS_SESSION(3) which was added in 7.34.0.
170This option is exactly the same as that option except in the case of OpenSSL.
171
172# RETURN VALUE
173
174Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
175