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

1 files changed, 13 insertions, 34 deletions

diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3
index 4c6e1e838..b1bef0e6e 100644
--- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3
+++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3
@@ -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), "