diff options
| -rw-r--r-- | docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 | 42 |
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 |