1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_DOH_URL 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_DNS_CACHE_TIMEOUT (3) 9 - CURLOPT_RESOLVE (3) 10 - CURLOPT_VERBOSE (3) 11Protocol: 12 - All 13--- 14 15# NAME 16 17CURLOPT_DOH_URL - provide the DNS-over-HTTPS URL 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL); 25~~~ 26 27# DESCRIPTION 28 29Pass in a pointer to a *URL* for the DoH server to use for name resolving. The 30parameter should be a char pointer to a null-terminated string which must be a 31valid and correct HTTPS URL. 32 33libcurl does not validate the syntax or use this variable until the transfer 34is issued. Even if you set a crazy value here, curl_easy_setopt(3) still 35returns *CURLE_OK*. 36 37curl sends POST requests to the given DNS-over-HTTPS URL. 38 39To find the DoH server itself, which might be specified using a name, libcurl 40uses the default name lookup function. You can bootstrap that by providing the 41address for the DoH server with CURLOPT_RESOLVE(3). 42 43Disable DoH use again by setting this option to NULL. 44 45# INHERIT OPTIONS 46 47DoH lookups use SSL and some SSL settings from your transfer are inherited, 48like CURLOPT_SSL_CTX_FUNCTION(3). 49 50The hostname and peer certificate verification settings are not inherited but 51can be controlled separately via CURLOPT_DOH_SSL_VERIFYHOST(3) and 52CURLOPT_DOH_SSL_VERIFYPEER(3). 53 54A set CURLOPT_OPENSOCKETFUNCTION(3) callback is not inherited. 55 56# KNOWN BUGS 57 58Even when DoH is set to be used with this option, there are still some name 59resolves that are performed without it, using the default name resolver 60mechanism. This includes name resolves done for CURLOPT_INTERFACE(3), 61CURLOPT_FTPPORT(3), a proxy type set to **CURLPROXY_SOCKS4** or 62**CURLPROXY_SOCKS5** and probably some more. 63 64# DEFAULT 65 66NULL - there is no default DoH URL. If this option is not set, libcurl uses 67the default name resolver. 68 69# EXAMPLE 70 71~~~c 72int main(void) 73{ 74 CURL *curl = curl_easy_init(); 75 if(curl) { 76 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 77 curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com"); 78 curl_easy_perform(curl); 79 } 80} 81~~~ 82 83# AVAILABILITY 84 85Added in 7.62.0 86 87# RETURN VALUE 88 89Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient 90heap space. 91 92Note that curl_easy_setopt(3) does immediately parse the given string so 93when given a bad DoH URL, libcurl might not detect the problem until it later 94tries to resolve a name with it. 95
