From 8a4ef73c8fc035becb4c1d99ca8b1892d100532a Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Thu, 4 Mar 2021 00:55:53 -0500 Subject: docs: Explain DOH transfers inherit some SSL settings - Document in DOH that some SSL settings are inherited but DOH hostname and peer verification are not and are controlled separately. - Document that CURLOPT_SSL_CTX_FUNCTION is inherited by DOH handles but we're considering changing behavior to no longer inherit it. Request feedback. Closes https://github.com/curl/curl/pull/6688 --- docs/cmdline-opts/doh-url.d | 5 +++++ docs/libcurl/opts/CURLOPT_DOH_URL.3 | 6 ++++++ docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 | 8 ++++++++ lib/doh.c | 6 +++++- 4 files changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/cmdline-opts/doh-url.d b/docs/cmdline-opts/doh-url.d index 7fce4460d..090799440 100644 --- a/docs/cmdline-opts/doh-url.d +++ b/docs/cmdline-opts/doh-url.d @@ -8,4 +8,9 @@ Category: dns Specifies which DNS-over-HTTPS (DOH) server to use to resolve hostnames, instead of using the default name resolver mechanism. The URL must be HTTPS. +Some SSL options that you set for your transfer will apply to DOH since the +name lookups take place over SSL. However, the certificate verification +settings are not inherited and can be controlled separately via +--doh-insecure and --doh-cert-status. + If this option is used several times, the last one will be used. diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.3 b/docs/libcurl/opts/CURLOPT_DOH_URL.3 index 4f451eed3..265cf37f8 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.3 +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.3 @@ -44,6 +44,12 @@ will use the default name lookup function. You can bootstrap that by providing the address for the DOH server with \fICURLOPT_RESOLVE(3)\fP. Disable DOH use again by setting this option to NULL. + +\fBAdvanced:\fP The DOH lookups use SSL so some SSL settings from your transfer +are inherited. The hostname and peer certificate verification settings are not +inherited and can be controlled separately via +\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP and \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP. +Note \fICURLOPT_SSL_CTX_FUNCTION(3)\fP is inherited. .SH DEFAULT NULL - there is no default DOH URL. If this option isn't set, libcurl will use the default name resolver. diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 index cde6a33c7..b7c596605 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 @@ -62,6 +62,14 @@ to reach in and modify SSL details in the connection without libcurl itself knowing anything about it, which then subsequently can lead to libcurl unknowingly reusing SSL connections with different properties. To remedy this you may set \fICURLOPT_FORBID_REUSE(3)\fP from the callback function. + +WARNING: If you are using DNS-over-HTTPS (DOH) via \fICURLOPT_DOH_URL(3)\fP +then the CTX callback will also be called for those transfers and the curl +handle is set to an internal handle. \fBThis behavior is subject to change.\fP +We recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on +your curl handle so you can identify it in the CTX callback. If you have a +reason to modify DOH SSL context please let us know on the curl-library mailing +list because we are considering removing this capability. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/lib/doh.c b/lib/doh.c index 15cdc35a4..52388cba3 100644 --- a/lib/doh.c +++ b/lib/doh.c @@ -359,7 +359,11 @@ static CURLcode dohprobe(struct Curl_easy *data, doh->set.dohfor = data; /* identify for which transfer this is done */ p->easy = doh; - /* add this transfer to the multi handle */ + /* DOH private_data must be null because the user must have a way to + distinguish their transfer's handle from DOH handles in user + callbacks (ie SSL CTX callback). */ + DEBUGASSERT(!data->set.private_data); + if(curl_multi_add_handle(multi, doh)) goto error; } -- cgit v1.2.1