summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorJay Satiro <raysatiro@yahoo.com>2021-02-11 17:09:59 -0500
committerJay Satiro <raysatiro@yahoo.com>2021-02-14 18:20:48 -0500
commit53022e1893de74b73554396b697f5a06cc7bc3f2 (patch)
treec771a0d256d150a43481f1b48b13656a6d9f4b93 /docs
parentb68026f7f4f4f99926fabf7f7b8ec948d5fcdc72 (diff)
downloadcurl-53022e1893de74b73554396b697f5a06cc7bc3f2.tar.gz
doh: add options to disable ssl verification
- New libcurl options CURLOPT_DOH_SSL_VERIFYHOST, CURLOPT_DOH_SSL_VERIFYPEER and CURLOPT_DOH_SSL_VERIFYSTATUS do the same as their respective counterparts. - New curl tool options --doh-insecure and --doh-cert-status do the same as their respective counterparts. Prior to this change DOH SSL certificate verification settings for verifyhost and verifypeer were supposed to be inherited respectively from CURLOPT_SSL_VERIFYHOST and CURLOPT_SSL_VERIFYPEER, but due to a bug were not. As a result DOH verification remained at the default, ie enabled, and it was not possible to disable. This commit changes behavior so that the DOH verification settings are independent and not inherited. Ref: https://github.com/curl/curl/pull/4579#issuecomment-554723676 Fixes https://github.com/curl/curl/issues/4578 Closes https://github.com/curl/curl/pull/6597
Diffstat (limited to 'docs')
-rw-r--r--docs/cmdline-opts/Makefile.inc2
-rw-r--r--docs/cmdline-opts/cert-status.d2
-rw-r--r--docs/cmdline-opts/doh-cert-status.d7
-rw-r--r--docs/cmdline-opts/doh-insecure.d7
-rw-r--r--docs/libcurl/curl_easy_setopt.311
-rw-r--r--docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.385
-rw-r--r--docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.396
-rw-r--r--docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.369
-rw-r--r--docs/libcurl/opts/Makefile.inc3
-rw-r--r--docs/libcurl/symbols-in-versions3
-rw-r--r--docs/options-in-versions2
11 files changed, 285 insertions, 2 deletions
diff --git a/docs/cmdline-opts/Makefile.inc b/docs/cmdline-opts/Makefile.inc
index e56bc84c7..7ca0f3268 100644
--- a/docs/cmdline-opts/Makefile.inc
+++ b/docs/cmdline-opts/Makefile.inc
@@ -62,6 +62,8 @@ DPAGES = \
dns-ipv4-addr.d \
dns-ipv6-addr.d \
dns-servers.d \
+ doh-cert-status.d \
+ doh-insecure.d \
doh-url.d \
dump-header.d \
egd-file.d \
diff --git a/docs/cmdline-opts/cert-status.d b/docs/cmdline-opts/cert-status.d
index 1342b092b..63e352051 100644
--- a/docs/cmdline-opts/cert-status.d
+++ b/docs/cmdline-opts/cert-status.d
@@ -1,7 +1,7 @@
Long: cert-status
Protocols: TLS
Added: 7.41.0
-Help: Verify the status of the server certificate
+Help: Verify the status of the server cert via OCSP-staple
Category: tls
---
Tells curl to verify the status of the server certificate by using the
diff --git a/docs/cmdline-opts/doh-cert-status.d b/docs/cmdline-opts/doh-cert-status.d
new file mode 100644
index 000000000..c99c9c132
--- /dev/null
+++ b/docs/cmdline-opts/doh-cert-status.d
@@ -0,0 +1,7 @@
+Long: doh-cert-status
+Help: Verify the status of the DOH server cert via OCSP-staple
+Protocols: all
+Added: 7.76.0
+Category: dns tls
+---
+Same as --cert-status but used for DOH (DNS-over-HTTPS).
diff --git a/docs/cmdline-opts/doh-insecure.d b/docs/cmdline-opts/doh-insecure.d
new file mode 100644
index 000000000..af254db70
--- /dev/null
+++ b/docs/cmdline-opts/doh-insecure.d
@@ -0,0 +1,7 @@
+Long: doh-insecure
+Help: Allow insecure DOH server connections
+Protocols: all
+Added: 7.76.0
+Category: dns tls
+---
+Same as --insecure but used for DOH (DNS-over-HTTPS).
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index ee5bd32da..3fc9a1d03 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -565,14 +565,23 @@ SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP
Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP
.IP CURLOPT_SSL_VERIFYHOST
Verify the host name in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP
+.IP CURLOPT_DOH_SSL_VERIFYHOST
+Verify the host name in the DOH (DNS-over-HTTPS) SSL certificate. See
+\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_PROXY_SSL_VERIFYHOST
Verify the host name in the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_SSL_VERIFYPEER
Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP
+.IP CURLOPT_DOH_SSL_VERIFYPEER
+Verify the DOH (DNS-over-HTTPS) SSL certificate. See
+\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_PROXY_SSL_VERIFYPEER
Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_SSL_VERIFYSTATUS
Verify the SSL certificate's status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP
+.IP CURLOPT_DOH_SSL_VERIFYSTATUS
+Verify the DOH (DNS-over-HTTPS) SSL certificate's status. See
+\fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP
.IP CURLOPT_CAINFO
CA cert bundle. See \fICURLOPT_CAINFO(3)\fP
.IP CURLOPT_PROXY_CAINFO
@@ -661,7 +670,7 @@ Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
7.65.0).
\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option
-is invalid, like perhaps out of range.a
+is invalid, like perhaps out of range.
If you try to set an option that libcurl doesn't know about, perhaps because
the library is too old to support it or the option was removed in a recent
diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3
new file mode 100644
index 000000000..ce4a369ec
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3
@@ -0,0 +1,85 @@
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_DOH_SSL_VERIFYHOST 3 "11 Feb 2021" "libcurl 7.76.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_DOH_SSL_VERIFYHOST \- verify the host name in the DOH SSL certificate
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYHOST, long verify);
+.SH DESCRIPTION
+Pass a long set to 2L as asking curl to \fIverify\fP the DOH (DNS-over-HTTPS)
+server's certificate name fields against the host name.
+
+This option is the DOH equivalent of \fICURLOPT_SSL_VERIFYHOST(3)\fP and
+only affects requests to the DOH server.
+
+When \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is 2, 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 \fIverify\fP value is set to 1L it is treated the same as 2L. However
+for consistency with the other VERIFYHOST options we suggest use 2 and not 1.
+
+When the \fIverify\fP value is set to 0L, the connection succeeds regardless of
+the names used in the certificate. Use that ability with caution!
+
+See also \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP to verify the digital signature
+of the DOH server certificate. If libcurl is built against NSS and
+\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is zero,
+\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is also set to zero and cannot be
+overridden.
+.SH DEFAULT
+2
+.SH PROTOCOLS
+DOH
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+ curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query");
+
+ /* Disable host name verification of the DOH server */
+ curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYHOST, 0L);
+
+ curl_easy_perform(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.76.0
+
+If built TLS enabled.
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLOPT_DOH_SSL_VERIFYPEER "(3), "
+.BR CURLOPT_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_SSL_VERIFYPEER "(3), "
+.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), "
+.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3
new file mode 100644
index 000000000..3f52595a7
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3
@@ -0,0 +1,96 @@
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_DOH_SSL_VERIFYPEER 3 "11 Feb 2021" "libcurl 7.76.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_DOH_SSL_VERIFYPEER \- verify the DOH SSL certificate
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYPEER, long verify);
+.SH DESCRIPTION
+Pass a long as parameter set to 1L to enable or 0L to disable.
+
+This option tells curl to verify the authenticity of the DOH (DNS-over-HTTPS)
+server's certificate. A value of 1 means curl verifies; 0 (zero) means it
+doesn't.
+
+This option is the DOH equivalent of \fICURLOPT_SSL_VERIFYPEER(3)\fP 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 \fICURLOPT_CAINFO(3)\fP option
+or the \fICURLOPT_CAPATH(3)\fP option.
+
+When \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP 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 \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP for that. The check
+that the host name in the certificate is valid for the host name you're
+connecting to is done independently of the
+\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP 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.
+.SH DEFAULT
+1
+.SH PROTOCOLS
+DOH
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+ curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query");
+
+ /* Disable certificate verification of the DOH server */
+ curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYPEER, 0L);
+
+ curl_easy_perform(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.76.0
+
+If built TLS enabled.
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLOPT_DOH_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_SSL_VERIFYPEER "(3), "
+.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), "
+.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_CAINFO "(3), "
+.BR CURLOPT_CAPATH "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3
new file mode 100644
index 000000000..a22ad6764
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3
@@ -0,0 +1,69 @@
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_DOH_SSL_VERIFYSTATUS 3 "11 Feb 2021" "libcurl 7.76.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_DOH_SSL_VERIFYSTATUS \- verify the DOH SSL certificate's status
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYSTATUS, long verify);
+.SH DESCRIPTION
+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 \fICURLOPT_SSL_VERIFYSTATUS(3)\fP 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.
+.SH DEFAULT
+0
+.SH PROTOCOLS
+DOH
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+ curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query");
+
+ /* Ask for OCSP stapling when verifying the DOH server */
+ curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYSTATUS, 1L);
+
+ curl_easy_perform(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.76.0. This option is currently only supported by the OpenSSL, GnuTLS
+and NSS TLS backends.
+.SH RETURN VALUE
+Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise
+returns CURLE_NOT_BUILT_IN.
+.SH "SEE ALSO"
+.BR CURLOPT_DOH_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_DOH_SSL_VERIFYPEER "(3), "
+.BR CURLOPT_SSL_VERIFYSTATUS "(3), "
diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc
index 3b5d27edd..5cec7cb4e 100644
--- a/docs/libcurl/opts/Makefile.inc
+++ b/docs/libcurl/opts/Makefile.inc
@@ -150,6 +150,9 @@ man_MANS = \
CURLOPT_DNS_SERVERS.3 \
CURLOPT_DNS_SHUFFLE_ADDRESSES.3 \
CURLOPT_DNS_USE_GLOBAL_CACHE.3 \
+ CURLOPT_DOH_SSL_VERIFYHOST.3 \
+ CURLOPT_DOH_SSL_VERIFYPEER.3 \
+ CURLOPT_DOH_SSL_VERIFYSTATUS.3 \
CURLOPT_DOH_URL.3 \
CURLOPT_EGDSOCKET.3 \
CURLOPT_ERRORBUFFER.3 \
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index a22fc0fa5..7da5c4cfa 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -410,6 +410,9 @@ CURLOPT_DNS_LOCAL_IP6 7.33.0
CURLOPT_DNS_SERVERS 7.24.0
CURLOPT_DNS_SHUFFLE_ADDRESSES 7.60.0
CURLOPT_DNS_USE_GLOBAL_CACHE 7.9.3 7.11.1
+CURLOPT_DOH_SSL_VERIFYHOST 7.76.0
+CURLOPT_DOH_SSL_VERIFYPEER 7.76.0
+CURLOPT_DOH_SSL_VERIFYSTATUS 7.76.0
CURLOPT_DOH_URL 7.62.0
CURLOPT_EGDSOCKET 7.7
CURLOPT_ENCODING 7.10
diff --git a/docs/options-in-versions b/docs/options-in-versions
index 66a178565..27497b7c1 100644
--- a/docs/options-in-versions
+++ b/docs/options-in-versions
@@ -50,6 +50,8 @@
--dns-ipv4-addr 7.33.0
--dns-ipv6-addr 7.33.0
--dns-servers 7.33.0
+--doh-cert-status 7.76.0
+--doh-insecure 7.76.0
--doh-url 7.62.0
--dump-header (-D) 5.7
--egd-file 7.7