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

4 files changed, 24 insertions, 1 deletions

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;
   }