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