CURLINFO_TLS_SSL_PTR.3: Warn about limitations

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

1 files changed, 37 insertions, 5 deletions

diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3
index 2f8b702ab..b82faecc9 100644
--- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3
+++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3
@@ -41,11 +41,9 @@ 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.
+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 {
@@ -92,6 +90,40 @@ SSLContext *
 .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