CURLINFO_TLS_SSL_PTR.3: Warn about limitations

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.

This option may be useful for example to extract certificate information in a

format convenient for further processing, such as manual validation. Refer to

the \fBLIMITATIONS\fP section.

.nf

struct curl_tlssessioninfo {

.IP "WolfSSL (formerly CyaSSL)"

SSL *

.RE

If the \fIinternals\fP pointer is NULL then either the SSL backend is not

supported or an SSL session has not yet been established.

.SH LIMITATIONS

\fBThis option has some limitations that could make it unsafe when it comes to

the manual verification of certificates.\fP

This option only retrieves the first in-use SSL session pointer for your easy

handle, however your easy handle may have more than one in-use SSL session if

using FTP over SSL. That is because the FTP protocol has a control channel and

a data channel and one or both may be over SSL. \fBCurrently there is no way to

retrieve a second in-use SSL session associated with an easy handle.\fP

This option has not been thoroughly tested with plaintext protocols that can be

upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with

\fICURLOPT_USE_SSL(3)\fP. Though you will be able to retrieve the SSL pointer,

it's possible that before you can do that \fBdata (including auth) may have

already been sent over a connection after it was upgraded.\fP

Renegotiation. If unsafe renegotiation or renegotiation in a way that the

certificate is allowed to change is allowed by your SSL library this may occur

and the certificate may change, and \fBdata may continue to be sent or received

after renegotiation but before you are able to get the (possibly) changed SSL

pointer,\fP with the (possibly) changed certificate information.

If you are using OpenSSL or wolfSSL then \fICURLOPT_SSL_CTX_FUNCTION(3)\fP can

be used to set a certificate verification callback in the CTX. That is safer

than using this option to poll for certificate changes and doesn't suffer from

any of the problems above. There is currently no way in libcurl to set a

verification callback for the other SSL backends.

How are you using this option? Are you affected by any of these limitations?

Please let us know by making a comment at

https://github.com/curl/curl/issues/685

.SH PROTOCOLS

All TLS-based

.SH EXAMPLE