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