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