CURLOPT_DOH_URL(3)

1CURLOPT_DOH_URL(3)         curl_easy_setopt options         CURLOPT_DOH_URL(3)
2
3
4

NAME

6       CURLOPT_DOH_URL - provide the DNS-over-HTTPS URL
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL);
12

DESCRIPTION

14       Pass  in  a pointer to a URL for the DoH server to use for name resolv‐
15       ing. The parameter should be a char * to a null-terminated string which
16       must  be URL-encoded in the following format: "https://host:port/path".
17       It MUST specify an HTTPS URL.
18
19       libcurl does not validate the syntax or use  this  variable  until  the
20       transfer  is  issued. Even if you set a crazy value here, curl_easy_se‐
21       topt(3) will still return CURLE_OK.
22
23       curl sends POST requests to the given DNS-over-HTTPS URL.
24
25       To find the DoH server itself, which might be specified using  a  name,
26       libcurl  will  use  the default name lookup function. You can bootstrap
27       that by providing the address  for  the  DoH  server  with  CURLOPT_RE‐
28       SOLVE(3).
29
30       Disable DoH use again by setting this option to NULL.
31

INHERIT OPTIONS

33       DoH lookups use SSL and some SSL settings from your transfer are inher‐
34       ited, like CURLOPT_SSL_CTX_FUNCTION(3).
35
36       The hostname and peer certificate verification settings are not  inher‐
37       ited but can be controlled separately via CURLOPT_DOH_SSL_VERIFYHOST(3)
38       and CURLOPT_DOH_SSL_VERIFYPEER(3).
39
40       A set CURLOPT_OPENSOCKETFUNCTION(3) callback is not inherited.
41

KNOWN BUGS

43       Even when DoH is set to be used with this option, there are still  some
44       name resolves that are performed without it, using the default name re‐
45       solver mechanism. This includes name resolves done  for  CURLOPT_INTER‐
46       FACE(3),  CURLOPT_FTPPORT(3),  a  proxy type set to CURLPROXY_SOCKS4 or
47       CURLPROXY_SOCKS5 and probably some more.
48

DEFAULT

50       NULL - there is no default DoH URL. If this option is not set,  libcurl
51       will use the default name resolver.
52

PROTOCOLS

54       All
55

EXAMPLE

57       CURL *curl = curl_easy_init();
58       if(curl) {
59         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
60         curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com");
61         curl_easy_perform(curl);
62       }
63

AVAILABILITY

65       Added in 7.62.0
66

RETURN VALUE

68       Returns  CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insuf‐
69       ficient heap space.
70
71       Note that curl_easy_setopt(3) will  not  immediately  parse  the  given
72       string  so when given a bad DoH URL, libcurl might not detect the prob‐
73       lem until it later tries to resolve a name with it.
74