Annotation of embedaddon/curl/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3, revision 1.1.1.1
1.1 misho 1: .\" **************************************************************************
2: .\" * _ _ ____ _
3: .\" * Project ___| | | | _ \| |
4: .\" * / __| | | | |_) | |
5: .\" * | (__| |_| | _ <| |___
6: .\" * \___|\___/|_| \_\_____|
7: .\" *
8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
9: .\" *
10: .\" * This software is licensed as described in the file COPYING, which
11: .\" * you should have received as part of this distribution. The terms
12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13: .\" *
14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15: .\" * copies of the Software, and permit persons to whom the Software is
16: .\" * furnished to do so, under the terms of the COPYING file.
17: .\" *
18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19: .\" * KIND, either express or implied.
20: .\" *
21: .\" **************************************************************************
22: .\"
23: .TH CURLINFO_TLS_SSL_PTR 3 "March 04, 2020" "libcurl 7.70.0" "curl_easy_getinfo options"
24:
25: .SH NAME
26: CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info
27: .SH SYNOPSIS
28: .nf
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: .SH DESCRIPTION
40: Pass a pointer to a 'struct curl_tlssessioninfo *'. The pointer will be
41: initialized to refer to a 'struct curl_tlssessioninfo *' that will contain an
42: enum indicating the SSL library used for the handshake and a pointer to the
43: respective internal TLS session structure of this underlying SSL library.
44:
45: This option may be useful for example to extract certificate information in a
46: format convenient for further processing, such as manual validation. Refer to
47: the \fBLIMITATIONS\fP section.
48:
49: .nf
50: struct curl_tlssessioninfo {
51: curl_sslbackend backend;
52: void *internals;
53: };
54: .fi
55:
56: The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_*
57: series: CURLSSLBACKEND_NONE (when built without TLS support),
58: CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_DARWINSSL, CURLSSLBACKEND_GNUTLS,
59: CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS,
60: CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_SCHANNEL or
61: CURLSSLBACKEND_MESALINK. (Note that the OpenSSL forks are all reported as just
62: OpenSSL here.)
63:
64: The \fIinternals\fP struct member will point to a TLS library specific pointer
65: for the active ("in use") SSL connection, with the following underlying types:
66: .RS
67: .IP GnuTLS
68: gnutls_session_t
69: .IP gskit
70: gsk_handle
71: .IP NSS
72: PRFileDesc *
73: .IP OpenSSL
74: CURLINFO_TLS_SESSION: SSL_CTX *
75:
76: CURLINFO_TLS_SSL_PTR: SSL *
77: .RE
78: Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends
79: as well:
80: .RS
81: .IP mbedTLS
82: mbedtls_ssl_context *
83: .IP "Secure Channel"
84: CtxtHandle *
85: .IP "Secure Transport"
86: SSLContext *
87: .IP "wolfSSL"
88: SSL *
89: .IP "MesaLink"
90: SSL *
91: .RE
92:
93: If the \fIinternals\fP pointer is NULL then either the SSL backend is not
94: supported, an SSL session has not yet been established or the connection is no
95: longer associated with the easy handle (eg curl_easy_perform has returned).
96: .SH LIMITATIONS
97: This option has some limitations that could make it unsafe when it comes to
98: the manual verification of certificates.
99:
100: This option only retrieves the first in-use SSL session pointer for your easy
101: handle, however your easy handle may have more than one in-use SSL session if
102: using FTP over SSL. That is because the FTP protocol has a control channel and
103: a data channel and one or both may be over SSL. Currently there is no way to
104: retrieve a second in-use SSL session associated with an easy handle.
105:
106: This option has not been thoroughly tested with plaintext protocols that can
107: be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with
108: \fICURLOPT_USE_SSL(3)\fP. Though you will be able to retrieve the SSL pointer,
109: it's possible that before you can do that data (including auth) may have
110: already been sent over a connection after it was upgraded.
111:
112: Renegotiation. If unsafe renegotiation or renegotiation in a way that the
113: certificate is allowed to change is allowed by your SSL library this may occur
114: and the certificate may change, and data may continue to be sent or received
115: after renegotiation but before you are able to get the (possibly) changed SSL
116: pointer, with the (possibly) changed certificate information.
117:
118: If you are using OpenSSL or wolfSSL then \fICURLOPT_SSL_CTX_FUNCTION(3)\fP can
119: be used to set a certificate verification callback in the CTX. That is safer
120: than using this option to poll for certificate changes and doesn't suffer from
121: any of the problems above. There is currently no way in libcurl to set a
122: verification callback for the other SSL backends.
123:
124: How are you using this option? Are you affected by any of these limitations?
125: Please let us know by making a comment at
126: https://github.com/curl/curl/issues/685
127: .SH PROTOCOLS
128: All TLS-based
129: .SH EXAMPLE
130: .nf
131: #include <curl/curl.h>
132: #include <openssl/ssl.h>
133:
134: CURL *curl;
135: static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
136: {
137: const struct curl_tlssessioninfo *info = NULL;
138: CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
139: if(info && !res) {
140: if(CURLSSLBACKEND_OPENSSL == info->backend) {
141: printf("OpenSSL ver. %s\\n", SSL_get_version((SSL*)info->internals));
142: }
143: }
144: return size * nmemb;
145: }
146:
147: int main(int argc, char** argv)
148: {
149: CURLcode res;
150: curl = curl_easy_init();
151: if(curl) {
152: curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
153: curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
154: res = curl_easy_perform(curl);
155: curl_easy_cleanup(curl);
156: }
157: return res;
158: }
159: .fi
160: .SH AVAILABILITY
161: Added in 7.48.0.
162:
163: This option supersedes \fICURLINFO_TLS_SESSION(3)\fP which was added in 7.34.0.
164: This option is exactly the same as that option except in the case of OpenSSL.
165: .SH RETURN VALUE
166: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
167: .SH "SEE ALSO"
168: .BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
169: .BR CURLINFO_TLS_SESSION "(3), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to CURLINFO_TLS_SSL_PTR.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts