mirror of
https://github.com/curl/curl.git
synced 2025-01-24 14:15:18 +08:00
getinfo: CURLINFO_TLS_SSL_PTR supersedes CURLINFO_TLS_SESSION
The two options are almost the same, except in the case of OpenSSL: CURLINFO_TLS_SESSION OpenSSL session internals is SSL_CTX *. CURLINFO_TLS_SSL_PTR OpenSSL session internals is SSL *. For backwards compatibility we couldn't modify CURLINFO_TLS_SESSION to return an SSL pointer for OpenSSL. Also, add support for the 'internals' member to point to SSL object for the other backends axTLS, PolarSSL, Secure Channel, Secure Transport and wolfSSL. Bug: https://github.com/curl/curl/issues/234 Reported-by: dkjjr89@users.noreply.github.com Bug: https://curl.haxx.se/mail/lib-2015-09/0127.html Reported-by: Michael König
This commit is contained in:
Jay Satiro
parent
3438ce7f46
commit
332414a30e
@ -194,9 +194,9 @@ See \fICURLINFO_FTP_ENTRY_PATH(3)\fP
|
||||
Certificate chain.
|
||||
See \fICURLINFO_CERTINFO(3)\fP
|
||||
|
||||
.IP CURLINFO_TLS_SESSION
|
||||
.IP CURLINFO_TLS_SSL_PTR
|
||||
TLS session info that can be used for further processing.
|
||||
See \fICURLINFO_TLS_SESSION(3)\fP
|
||||
See \fICURLINFO_TLS_SSL_PTR(3)\fP
|
||||
|
||||
.IP CURLINFO_CONDITION_UNMET
|
||||
Whether or not a time conditional was met.
|
||||
|
||||
@ -30,44 +30,22 @@ CURLINFO_TLS_SESSION \- get TLS session info
|
||||
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
|
||||
struct curl_tlssessioninfo **session);
|
||||
.SH DESCRIPTION
|
||||
Pass a pointer to a 'struct curl_tlssessioninfo *'. The pointer will be
|
||||
initialized to refer to a 'struct curl_tlssessioninfo *' that will contain an
|
||||
enum indicating the SSL library used for the handshake and the respective
|
||||
internal TLS session structure of this underlying SSL library.
|
||||
\fBThis option has been superseded\fP by \fICURLINFO_TLS_SSL_PTR(3)\fP which
|
||||
was added in 7.48.0. The only reason you would use this option instead is if
|
||||
you could be using a version of libcurl earlier than 7.48.0.
|
||||
|
||||
This may then be used to extract certificate information in a format
|
||||
convenient for further processing, such as manual validation. NOTE: this
|
||||
option may not be available for all SSL backends; unsupported SSL backends
|
||||
will always return NULL in the \fIinternals\fP pointer to indicate that they
|
||||
are not supported.
|
||||
This option is exactly the same as \fICURLINFO_TLS_SSL_PTR(3)\fP except in the
|
||||
case of OpenSSL. If the session \fIbackend\fP is CURLSSLBACKEND_OPENSSL the
|
||||
session \fIinternals\fP pointer varies depending on the option:
|
||||
|
||||
.nf
|
||||
struct curl_tlssessioninfo {
|
||||
curl_sslbackend backend;
|
||||
void *internals;
|
||||
};
|
||||
.fi
|
||||
CURLINFO_TLS_SESSION OpenSSL session \fIinternals\fP is SSL_CTX *.
|
||||
|
||||
The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_*
|
||||
series: CURLSSLBACKEND_NONE (when built without TLS support),
|
||||
CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_NSS,
|
||||
CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_POLARSSL, CURLSSLBACKEND_CYASSL,
|
||||
CURLSSLBACKEND_SCHANNEL, CURLSSLBACKEND_DARWINSSL or
|
||||
CURLSSLBACKEND_AXTLS. (Note that the OpenSSL forks are all reported as just
|
||||
OpenSSL here.)
|
||||
CURLINFO_TLS_SSL_PTR OpenSSL session \fIinternals\fP is SSL *.
|
||||
|
||||
The \fIinternals\fP struct member will point to a TLS library specific pointer
|
||||
with the following underlying types:
|
||||
.RS
|
||||
.IP OpenSSL
|
||||
SSL_CTX *
|
||||
.IP GnuTLS
|
||||
gnutls_session_t
|
||||
.IP NSS
|
||||
PRFileDesc *
|
||||
.IP gskit
|
||||
gsk_handle
|
||||
.RE
|
||||
You can obtain an SSL_CTX pointer from an SSL pointer using OpenSSL function
|
||||
SSL_get_SSL_CTX. Therefore unless you need compatibility with older versions of
|
||||
libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to that document for more
|
||||
information.
|
||||
.SH PROTOCOLS
|
||||
All TLS-based
|
||||
.SH EXAMPLE
|
||||
@ -78,3 +56,4 @@ Added in 7.34.0
|
||||
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
|
||||
.SH "SEE ALSO"
|
||||
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
|
||||
.BR CURLINFO_TLS_SSL_PTR "(3), "
|
||||
|
||||
106
docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3
Normal file
106
docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3
Normal file
@ -0,0 +1,106 @@
|
||||
.\" **************************************************************************
|
||||
.\" * _ _ ____ _
|
||||
.\" * Project ___| | | | _ \| |
|
||||
.\" * / __| | | | |_) | |
|
||||
.\" * | (__| |_| | _ <| |___
|
||||
.\" * \___|\___/|_| \_\_____|
|
||||
.\" *
|
||||
.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
|
||||
.\" *
|
||||
.\" * This software is licensed as described in the file COPYING, which
|
||||
.\" * you should have received as part of this distribution. The terms
|
||||
.\" * are also available at http://curl.haxx.se/docs/copyright.html.
|
||||
.\" *
|
||||
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
||||
.\" * copies of the Software, and permit persons to whom the Software is
|
||||
.\" * furnished to do so, under the terms of the COPYING file.
|
||||
.\" *
|
||||
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
||||
.\" * KIND, either express or implied.
|
||||
.\" *
|
||||
.\" **************************************************************************
|
||||
.\"
|
||||
.TH CURLINFO_TLS_SSL_PTR 3 "23 Feb 2016" "libcurl 7.48.0" "curl_easy_getinfo options"
|
||||
.SH NAME
|
||||
CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
#include <curl/curl.h>
|
||||
|
||||
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
|
||||
struct curl_tlssessioninfo **session);
|
||||
|
||||
/* if you need compatibility with libcurl < 7.48.0 use
|
||||
CURLINFO_TLS_SESSION instead: */
|
||||
|
||||
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
|
||||
struct curl_tlssessioninfo **session);
|
||||
.SH DESCRIPTION
|
||||
Pass a pointer to a 'struct curl_tlssessioninfo *'. The pointer will be
|
||||
initialized to refer to a 'struct curl_tlssessioninfo *' that will contain an
|
||||
enum indicating the SSL library used for the handshake and a pointer to the
|
||||
respective internal TLS session structure of this underlying SSL library.
|
||||
|
||||
This may then be used to extract certificate information in a format
|
||||
convenient for further processing, such as manual validation. NOTE: this
|
||||
option may not be available for all SSL backends; unsupported SSL backends
|
||||
will always return NULL in the \fIinternals\fP pointer to indicate that they
|
||||
are not supported.
|
||||
|
||||
.nf
|
||||
struct curl_tlssessioninfo {
|
||||
curl_sslbackend backend;
|
||||
void *internals;
|
||||
};
|
||||
.fi
|
||||
|
||||
The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_*
|
||||
series: CURLSSLBACKEND_NONE (when built without TLS support),
|
||||
CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_NSS,
|
||||
CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_POLARSSL, CURLSSLBACKEND_CYASSL,
|
||||
CURLSSLBACKEND_SCHANNEL, CURLSSLBACKEND_DARWINSSL or
|
||||
CURLSSLBACKEND_AXTLS. (Note that the OpenSSL forks are all reported as just
|
||||
OpenSSL here.)
|
||||
|
||||
The \fIinternals\fP struct member will point to a TLS library specific pointer
|
||||
for the active ("in use") SSL connection, with the following underlying types:
|
||||
.RS
|
||||
.IP GnuTLS
|
||||
gnutls_session_t
|
||||
.IP gskit
|
||||
gsk_handle
|
||||
.IP NSS
|
||||
PRFileDesc *
|
||||
.IP OpenSSL
|
||||
CURLINFO_TLS_SESSION: SSL_CTX *
|
||||
|
||||
CURLINFO_TLS_SSL_PTR: SSL *
|
||||
.RE
|
||||
Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends
|
||||
as well:
|
||||
.RS
|
||||
.IP axTLS
|
||||
SSL *
|
||||
.IP PolarSSL
|
||||
ssl_session *
|
||||
.IP Secure Channel ("WinSSL")
|
||||
CtxtHandle *
|
||||
.IP Secure Transport ("DarwinSSL")
|
||||
SSLContext *
|
||||
.IP wolfSSL ("CyaSSL")
|
||||
SSL *
|
||||
.RE
|
||||
.SH PROTOCOLS
|
||||
All TLS-based
|
||||
.SH EXAMPLE
|
||||
TODO
|
||||
.SH AVAILABILITY
|
||||
Added in 7.48.0.
|
||||
|
||||
This option supersedes \fICURLINFO_TLS_SESSION(3)\fP which was added in 7.34.0.
|
||||
This option is exactly the same as that option except in the case of OpenSSL.
|
||||
.SH RETURN VALUE
|
||||
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
|
||||
.SH "SEE ALSO"
|
||||
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
|
||||
.BR CURLINFO_TLS_SESSION "(3), "
|
||||
@ -136,7 +136,8 @@ man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3 \
|
||||
CURLINFO_SIZE_UPLOAD.3 CURLINFO_SPEED_DOWNLOAD.3 \
|
||||
CURLINFO_SPEED_UPLOAD.3 CURLINFO_SSL_ENGINES.3 \
|
||||
CURLINFO_SSL_VERIFYRESULT.3 CURLINFO_STARTTRANSFER_TIME.3 \
|
||||
CURLINFO_TLS_SESSION.3 CURLINFO_TOTAL_TIME.3
|
||||
CURLINFO_TLS_SESSION.3 CURLINFO_TLS_SSL_PTR.3 \
|
||||
CURLINFO_TOTAL_TIME.3
|
||||
|
||||
HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \
|
||||
CURLOPT_ADDRESS_SCOPE.html CURLOPT_APPEND.html \
|
||||
@ -269,7 +270,8 @@ HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \
|
||||
CURLINFO_SIZE_UPLOAD.html CURLINFO_SPEED_DOWNLOAD.html \
|
||||
CURLINFO_SPEED_UPLOAD.html CURLINFO_SSL_ENGINES.html \
|
||||
CURLINFO_SSL_VERIFYRESULT.html CURLINFO_STARTTRANSFER_TIME.html \
|
||||
CURLINFO_TLS_SESSION.html CURLINFO_TOTAL_TIME.html
|
||||
CURLINFO_TLS_SESSION.html CURLINFO_TLS_SSL_PTR.html \
|
||||
CURLINFO_TOTAL_TIME.html
|
||||
|
||||
PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \
|
||||
CURLOPT_ADDRESS_SCOPE.pdf CURLOPT_APPEND.pdf CURLOPT_AUTOREFERER.pdf \
|
||||
@ -400,7 +402,7 @@ PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \
|
||||
CURLINFO_SPEED_DOWNLOAD.pdf CURLINFO_SPEED_UPLOAD.pdf \
|
||||
CURLINFO_SSL_ENGINES.pdf CURLINFO_SSL_VERIFYRESULT.pdf \
|
||||
CURLINFO_STARTTRANSFER_TIME.pdf CURLINFO_TLS_SESSION.pdf \
|
||||
CURLINFO_TOTAL_TIME.pdf
|
||||
CURLINFO_TLS_SSL_PTR.pdf CURLINFO_TOTAL_TIME.pdf
|
||||
|
||||
CLEANFILES = $(HTMLPAGES) $(PDFPAGES)
|
||||
|
||||
|
||||
@ -259,7 +259,8 @@ CURLINFO_SSL_VERIFYRESULT 7.5
|
||||
CURLINFO_STARTTRANSFER_TIME 7.9.2
|
||||
CURLINFO_STRING 7.4.1
|
||||
CURLINFO_TEXT 7.9.6
|
||||
CURLINFO_TLS_SESSION 7.34.0
|
||||
CURLINFO_TLS_SESSION 7.34.0 7.48.0
|
||||
CURLINFO_TLS_SSL_PTR 7.48.0
|
||||
CURLINFO_TOTAL_TIME 7.4.1
|
||||
CURLINFO_TYPEMASK 7.4.1
|
||||
CURLIOCMD_NOP 7.12.3
|
||||
|
||||
@ -2112,7 +2112,7 @@ typedef enum {
|
||||
|
||||
/* Information about the SSL library used and the respective internal SSL
|
||||
handle, which can be used to obtain further information regarding the
|
||||
connection. Asked for with CURLINFO_TLS_SESSION. */
|
||||
connection. Asked for with CURLINFO_TLS_SSL_PTR or CURLINFO_TLS_SESSION. */
|
||||
struct curl_tlssessioninfo {
|
||||
curl_sslbackend backend;
|
||||
void *internals;
|
||||
@ -2172,9 +2172,10 @@ typedef enum {
|
||||
CURLINFO_LOCAL_PORT = CURLINFO_LONG + 42,
|
||||
CURLINFO_TLS_SESSION = CURLINFO_SLIST + 43,
|
||||
CURLINFO_ACTIVESOCKET = CURLINFO_SOCKET + 44,
|
||||
CURLINFO_TLS_SSL_PTR = CURLINFO_SLIST + 45,
|
||||
/* Fill in new entries below here! */
|
||||
|
||||
CURLINFO_LASTONE = 44
|
||||
CURLINFO_LASTONE = 45
|
||||
} CURLINFO;
|
||||
|
||||
/* CURLINFO_RESPONSE_CODE is the new name for the option previously known as
|
||||
|
||||
@ -281,48 +281,55 @@ static CURLcode getinfo_slist(struct SessionHandle *data, CURLINFO info,
|
||||
*param_slistp = ptr.to_slist;
|
||||
break;
|
||||
case CURLINFO_TLS_SESSION:
|
||||
case CURLINFO_TLS_SSL_PTR:
|
||||
{
|
||||
struct curl_tlssessioninfo **tsip = (struct curl_tlssessioninfo **)
|
||||
param_slistp;
|
||||
struct curl_tlssessioninfo *tsi = &data->tsi;
|
||||
struct connectdata *conn = data->easy_conn;
|
||||
unsigned int sockindex = 0;
|
||||
void *internals = NULL;
|
||||
|
||||
*tsip = tsi;
|
||||
tsi->backend = Curl_ssl_backend();
|
||||
tsi->internals = NULL;
|
||||
|
||||
if(!conn)
|
||||
break;
|
||||
|
||||
/* Find the active ("in use") SSL connection, if any */
|
||||
while((sockindex < sizeof(conn->ssl) / sizeof(conn->ssl[0])) &&
|
||||
(!conn->ssl[sockindex].use))
|
||||
sockindex++;
|
||||
|
||||
if(sockindex == sizeof(conn->ssl) / sizeof(conn->ssl[0]))
|
||||
break; /* no SSL session found */
|
||||
|
||||
/* Return the TLS session information from the relevant backend */
|
||||
#ifdef USE_OPENSSL
|
||||
internals = conn->ssl[sockindex].ctx;
|
||||
if(conn && tsi->backend != CURLSSLBACKEND_NONE) {
|
||||
unsigned int i;
|
||||
for(i = 0; i < (sizeof(conn->ssl) / sizeof(conn->ssl[0])); ++i) {
|
||||
if(conn->ssl[i].use) {
|
||||
#ifdef USE_AXTLS
|
||||
tsi->internals = (void *)conn->ssl[i].ssl;
|
||||
#endif
|
||||
#ifdef USE_CYASSL
|
||||
tsi->internals = (void *)conn->ssl[i].handle;
|
||||
#endif
|
||||
#ifdef USE_DARWINSSL
|
||||
tsi->internals = (void *)conn->ssl[i].ssl_ctx;
|
||||
#endif
|
||||
#ifdef USE_GNUTLS
|
||||
internals = conn->ssl[sockindex].session;
|
||||
#endif
|
||||
#ifdef USE_NSS
|
||||
internals = conn->ssl[sockindex].handle;
|
||||
tsi->internals = (void *)conn->ssl[i].session;
|
||||
#endif
|
||||
#ifdef USE_GSKIT
|
||||
internals = conn->ssl[sockindex].handle;
|
||||
tsi->internals = (void *)conn->ssl[i].handle;
|
||||
#endif
|
||||
if(internals) {
|
||||
tsi->internals = internals;
|
||||
#ifdef USE_NSS
|
||||
tsi->internals = (void *)conn->ssl[i].handle;
|
||||
#endif
|
||||
#ifdef USE_OPENSSL
|
||||
/* Legacy: CURLINFO_TLS_SESSION must return an SSL_CTX pointer. */
|
||||
tsi->internals = ((info == CURLINFO_TLS_SESSION) ?
|
||||
(void *)conn->ssl[i].ctx :
|
||||
(void *)conn->ssl[i].handle);
|
||||
#endif
|
||||
#ifdef USE_POLARSSL
|
||||
tsi->internals = (void *)&conn->ssl[i].ssn;
|
||||
#endif
|
||||
#ifdef USE_SCHANNEL
|
||||
tsi->internals = (void *)&conn->ssl[i].ctxt->ctxt_handle;
|
||||
#endif
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
/* NOTE: For other SSL backends, it is not immediately clear what data
|
||||
to return from 'struct ssl_connect_data'; thus we keep 'internals' to
|
||||
NULL which should be interpreted as "not supported" */
|
||||
}
|
||||
break;
|
||||
default:
|
||||
|
||||
@ -679,6 +679,7 @@ curl_easy_getinfo_ccsid(CURL * curl, CURLINFO info, ...)
|
||||
break;
|
||||
|
||||
case CURLINFO_TLS_SESSION:
|
||||
case CURLINFO_TLS_SSL_PTR:
|
||||
case CURLINFO_SOCKET:
|
||||
break;
|
||||
|
||||
|
||||
@ -1426,6 +1426,8 @@
|
||||
d c X'0040002B'
|
||||
d CURLINFO_ACTIVESOCKET... CURLINFO_SOCKET + 44
|
||||
d c X'0050002C'
|
||||
d CURLINFO_TLS_SSL_PTR... CURLINFO_SLIST + 45
|
||||
d c X'0040002D'
|
||||
*
|
||||
d CURLINFO_HTTP_CODE... Old ...RESPONSE_CODE
|
||||
d c X'00200002'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user