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

diff --git a/docs/cmdline-opts/doh-url.d b/docs/cmdline-opts/doh-url.d
index 7fce4460d9dcd5978ac8438229d3968f6c8b905d..090799440aa613c4723257281ef4098e0898480e 100644 (file)
--- 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 4f451eed34174d1f7b14f7b0c6d61d8a6f8c2cba..265cf37f87566f94842287d56eb3fc13ec72ddbb 100644 (file)
--- 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 cde6a33c765dc14092f9dc5825b9d4fcd6179150..b7c596605bf92803d9e6556b45f8e47c79776315 100644 (file)
--- 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 15cdc35a46949fc92629e04b6130d82c4836c20a..52388cba3eb7a1049a7f2e1d731e09455b5a5afd 100644 (file)
--- 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;
   }