diff options
Diffstat (limited to 'docs/libcurl/opts')
| -rw-r--r-- | docs/libcurl/opts/CURLINFO_TLS_SESSION.3 | 47 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 | 106 | ||||
| -rw-r--r-- | docs/libcurl/opts/Makefile.am | 8 |
3 files changed, 124 insertions, 37 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), " diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 new file mode 100644 index 000000000..6d984e34d --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 @@ -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), " diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 04f8b4bbe..61e564043 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -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) |