Expose DNS-over-HTTP options (#434)

* Expose DNS-over-HTTP options

Expose options related to DNS-over-HTTP name resolution support. Includes a brief working example. Support for DoH is enabled in curl by default and is available as of 7.62.0.

* Fix verify option datatypes

* Make rustfmt happy

Author: sagebind

curl-sys/lib.rs

@@ -597,6 +597,7 @@ pub const CURLOPT_PROXY_CAPATH: CURLoption = CURLOPTTYPE_OBJECTPOINT + 247;
 pub const CURLOPT_PROXY_SSLCERT: CURLoption = CURLOPTTYPE_OBJECTPOINT + 254;
 pub const CURLOPT_PROXY_SSLKEY: CURLoption = CURLOPTTYPE_OBJECTPOINT + 256;
 
+pub const CURLOPT_DOH_URL: CURLoption = CURLOPTTYPE_OBJECTPOINT + 279;
 pub const CURLOPT_UPLOAD_BUFFERSIZE: CURLoption = CURLOPTTYPE_LONG + 280;
 
 pub const CURLOPT_MAXAGE_CONN: CURLoption = CURLOPTTYPE_LONG + 288;
@@ -609,6 +610,9 @@ pub const CURLOPT_ISSUERCERT_BLOB: CURLoption = CURLOPTTYPE_BLOB + 295;
 
 pub const CURLOPT_AWS_SIGV4: CURLoption = CURLOPTTYPE_OBJECTPOINT + 305;
 
+pub const CURLOPT_DOH_SSL_VERIFYPEER: CURLoption = CURLOPTTYPE_LONG + 306;
+pub const CURLOPT_DOH_SSL_VERIFYHOST: CURLoption = CURLOPTTYPE_LONG + 307;
+pub const CURLOPT_DOH_SSL_VERIFYSTATUS: CURLoption = CURLOPTTYPE_LONG + 308;
 pub const CURLOPT_CAINFO_BLOB: CURLoption = CURLOPTTYPE_BLOB + 309;
 
 pub const CURL_IPRESOLVE_WHATEVER: c_int = 0;

examples/doh.rs

@@ -0,0 +1,17 @@
+use curl::easy::Easy;
+use std::io::{stdout, Write};
+
+fn main() -> Result<(), curl::Error> {
+    let mut curl = Easy::new();
+
+    curl.url("https://example.com")?;
+    curl.doh_url(Some("https://cloudflare-dns.com/dns-query"))?;
+    curl.write_function(|data| {
+        stdout().write_all(data).unwrap();
+        Ok(data.len())
+    })?;
+
+    curl.perform()?;
+
+    Ok(())
+}

src/easy/handle.rs

@@ -648,6 +648,26 @@ impl Easy {
         self.inner.dns_cache_timeout(dur)
     }
 
+    /// Same as [`Easy2::doh_url`](struct.Easy2.html#method.doh_url)
+    pub fn doh_url(&mut self, url: Option<&str>) -> Result<(), Error> {
+        self.inner.doh_url(url)
+    }
+
+    /// Same as [`Easy2::doh_ssl_verify_peer`](struct.Easy2.html#method.doh_ssl_verify_peer)
+    pub fn doh_ssl_verify_peer(&mut self, verify: bool) -> Result<(), Error> {
+        self.inner.doh_ssl_verify_peer(verify)
+    }
+
+    /// Same as [`Easy2::doh_ssl_verify_host`](struct.Easy2.html#method.doh_ssl_verify_host)
+    pub fn doh_ssl_verify_host(&mut self, verify: bool) -> Result<(), Error> {
+        self.inner.doh_ssl_verify_host(verify)
+    }
+
+    /// Same as [`Easy2::doh_ssl_verify_status`](struct.Easy2.html#method.doh_ssl_verify_status)
+    pub fn doh_ssl_verify_status(&mut self, verify: bool) -> Result<(), Error> {
+        self.inner.doh_ssl_verify_status(verify)
+    }
+
     /// Same as [`Easy2::buffer_size`](struct.Easy2.html#method.buffer_size)
     pub fn buffer_size(&mut self, size: usize) -> Result<(), Error> {
         self.inner.buffer_size(size)

src/easy/handler.rs

@@ -1049,6 +1049,123 @@ impl<H> Easy2<H> {
         self.setopt_long(curl_sys::CURLOPT_DNS_CACHE_TIMEOUT, dur.as_secs() as c_long)
     }
 
+    /// Provide the DNS-over-HTTPS URL.
+    ///
+    /// The parameter must be URL-encoded in the following format:
+    /// `https://host:port/path`. It **must** specify a HTTPS URL.
+    ///
+    /// libcurl does not validate the syntax or use this variable until the
+    /// transfer is issued. Even if you set a crazy value here, this method will
+    /// still return [`Ok`].
+    ///
+    /// curl sends `POST` requests to the given DNS-over-HTTPS URL.
+    ///
+    /// To find the DoH server itself, which might be specified using a name,
+    /// libcurl will use the default name lookup function. You can bootstrap
+    /// that by providing the address for the DoH server with
+    /// [`Easy2::resolve`].
+    ///
+    /// Disable DoH use again by setting this option to [`None`].
+    ///
+    /// By default this option is not set and corresponds to `CURLOPT_DOH_URL`.
+    pub fn doh_url(&mut self, url: Option<&str>) -> Result<(), Error> {
+        if let Some(url) = url {
+            let url = CString::new(url)?;
+            self.setopt_str(curl_sys::CURLOPT_DOH_URL, &url)
+        } else {
+            self.setopt_ptr(curl_sys::CURLOPT_DOH_URL, ptr::null())
+        }
+    }
+
+    /// This option tells curl to verify the authenticity of the DoH
+    /// (DNS-over-HTTPS) server's certificate. A value of `true` means curl
+    /// verifies; `false` means it does not.
+    ///
+    /// This option is the DoH equivalent of [`Easy2::ssl_verify_peer`] and only
+    /// affects requests to the DoH server.
+    ///
+    /// When negotiating a TLS or SSL connection, the server sends a certificate
+    /// indicating its identity. Curl verifies whether the certificate is
+    /// authentic, i.e. that you can trust that the server is who the
+    /// certificate says it is. This trust is based on a chain of digital
+    /// signatures, rooted in certification authority (CA) certificates you
+    /// supply. curl uses a default bundle of CA certificates (the path for that
+    /// is determined at build time) and you can specify alternate certificates
+    /// with the [`Easy2::cainfo`] option or the [`Easy2::capath`] option.
+    ///
+    /// When `doh_ssl_verify_peer` is enabled, and the verification fails to
+    /// prove that the certificate is authentic, the connection fails. When the
+    /// option is zero, the peer certificate verification succeeds regardless.
+    ///
+    /// Authenticating the certificate is not enough to be sure about the
+    /// server. You typically also want to ensure that the server is the server
+    /// you mean to be talking to. Use [`Easy2::doh_ssl_verify_host`] for that.
+    /// The check that the host name in the certificate is valid for the host
+    /// name you are connecting to is done independently of the
+    /// `doh_ssl_verify_peer` option.
+    ///
+    /// **WARNING:** disabling verification of the certificate allows bad guys
+    /// to man-in-the-middle the communication without you knowing it. Disabling
+    /// verification makes the communication insecure. Just having encryption on
+    /// a transfer is not enough as you cannot be sure that you are
+    /// communicating with the correct end-point.
+    ///
+    /// By default this option is set to `true` and corresponds to
+    /// `CURLOPT_DOH_SSL_VERIFYPEER`.
+    pub fn doh_ssl_verify_peer(&mut self, verify: bool) -> Result<(), Error> {
+        self.setopt_long(curl_sys::CURLOPT_DOH_SSL_VERIFYPEER, verify.into())
+    }
+
+    /// Tells curl to verify the DoH (DNS-over-HTTPS) server's certificate name
+    /// fields against the host name.
+    ///
+    /// This option is the DoH equivalent of [`Easy2::ssl_verify_host`] and only
+    /// affects requests to the DoH server.
+    ///
+    /// When `doh_ssl_verify_host` is `true`, the SSL certificate provided by
+    /// the DoH server must indicate that the server name is the same as the
+    /// server name to which you meant to connect to, or the connection fails.
+    ///
+    /// Curl considers the DoH server the intended one when the Common Name
+    /// field or a Subject Alternate Name field in the certificate matches the
+    /// host name in the DoH URL to which you told Curl to connect.
+    ///
+    /// When the verify value is set to `false`, the connection succeeds
+    /// regardless of the names used in the certificate. Use that ability with
+    /// caution!
+    ///
+    /// See also [`Easy2::doh_ssl_verify_peer`] to verify the digital signature
+    /// of the DoH server certificate. If libcurl is built against NSS and
+    /// [`Easy2::doh_ssl_verify_peer`] is `false`, `doh_ssl_verify_host` is also
+    /// set to `false` and cannot be overridden.
+    ///
+    /// By default this option is set to `true` and corresponds to
+    /// `CURLOPT_DOH_SSL_VERIFYHOST`.
+    pub fn doh_ssl_verify_host(&mut self, verify: bool) -> Result<(), Error> {
+        self.setopt_long(
+            curl_sys::CURLOPT_DOH_SSL_VERIFYHOST,
+            if verify { 2 } else { 0 },
+        )
+    }
+
+    /// Pass a long as parameter set to 1 to enable or 0 to disable.
+    ///
+    /// This option determines whether libcurl verifies the status of the DoH
+    /// (DNS-over-HTTPS) server cert using the "Certificate Status Request" TLS
+    /// extension (aka. OCSP stapling).
+    ///
+    /// This option is the DoH equivalent of CURLOPT_SSL_VERIFYSTATUS and only
+    /// affects requests to the DoH server.
+    ///
+    /// Note that if this option is enabled but the server does not support the
+    /// TLS extension, the verification will fail.
+    ///
+    /// By default this option is set to `false` and corresponds to
+    /// `CURLOPT_DOH_SSL_VERIFYSTATUS`.
+    pub fn doh_ssl_verify_status(&mut self, verify: bool) -> Result<(), Error> {
+        self.setopt_long(curl_sys::CURLOPT_DOH_SSL_VERIFYSTATUS, verify.into())
+    }
+
     /// Specify the preferred receive buffer size, in bytes.
     ///
     /// This is treated as a request, not an order, and the main point of this

systest/build.rs

@@ -76,6 +76,14 @@ fn main() {
                 _ => {}
             }
         }
+        if version < 76 {
+            match s {
+                "CURLOPT_DOH_SSL_VERIFYHOST" => return true,
+                "CURLOPT_DOH_SSL_VERIFYPEER" => return true,
+                "CURLOPT_DOH_SSL_VERIFYSTATUS" => return true,
+                _ => {}
+            }
+        }
         if version < 75 {
             match s {
                 "CURLAUTH_AWS_SIGV4" => return true,
@@ -138,6 +146,7 @@ fn main() {
         }
         if version < 62 {
             match s {
+                "CURLOPT_DOH_URL" => return true,
                 "CURLOPT_UPLOAD_BUFFERSIZE" => return true,
                 _ => {}
             }