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.
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
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), "
--- /dev/null
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * 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), "
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 \
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 \
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)
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
/* 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;
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
*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;
+ tsi->internals = (void *)conn->ssl[i].session;
+#endif
+#ifdef USE_GSKIT
+ tsi->internals = (void *)conn->ssl[i].handle;
#endif
#ifdef USE_NSS
- internals = conn->ssl[sockindex].handle;
+ tsi->internals = (void *)conn->ssl[i].handle;
#endif
-#ifdef USE_GSKIT
- internals = conn->ssl[sockindex].handle;
+#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
- if(internals) {
- tsi->internals = internals;
+ 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:
break;
case CURLINFO_TLS_SESSION:
+ case CURLINFO_TLS_SSL_PTR:
case CURLINFO_SOCKET:
break;
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'
projects / curl / commitdiff