Commit 332414a3 authored by Jay Satiro's avatar Jay Satiro
Browse files

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: default avatar <dkjjr89@users.noreply.github.com>

Bug: https://curl.haxx.se/mail/lib-2015-09/0127.html
Reported-by: Michael König
parent 3438ce7f

docs/libcurl/curl_easy_getinfo.3

+2 −2
Original line number Diff line number Diff line
@@ -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.

docs/libcurl/opts/CURLINFO_TLS_SESSION.3

+13 −34
Original line number Diff line number Diff line
@@ -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), "

docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3

0 → 100644
+106 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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), "

docs/libcurl/opts/Makefile.am

+5 −3
Original line number Diff line number Diff line
@@ -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)

docs/libcurl/symbols-in-versions

+2 −1
Original line number Diff line number Diff line
@@ -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