From 423a93ce32215c9854b0b077aeb5ea723a1f0f63 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Mon, 6 Feb 2017 03:13:42 -0500 Subject: docs: Add more HTTPS proxy documentation - Document HTTPS proxy type. - Document --write-out %{proxy_ssl_verify_result}. - Document SOCKS proxy + HTTP/HTTPS proxy combination. HTTPS proxy support was added in 7.52.0 for OpenSSL, GnuTLS and NSS. Ref: https://github.com/curl/curl/commit/cb4e2be --- docs/cmdline-opts/proxy.d | 15 ++++++++++----- docs/cmdline-opts/socks4.d | 8 +++++--- docs/cmdline-opts/socks4a.d | 8 +++++--- docs/cmdline-opts/socks5-hostname.d | 8 +++++--- docs/cmdline-opts/socks5.d | 8 +++++--- docs/cmdline-opts/write-out.d | 4 ++++ docs/libcurl/opts/CURLOPT_PROXY.3 | 20 ++++++++++++++++---- docs/libcurl/opts/CURLOPT_PROXYTYPE.3 | 27 +++++++++++++++++++-------- 8 files changed, 69 insertions(+), 29 deletions(-) diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d index 377a51aab..6506692be 100644 --- a/docs/cmdline-opts/proxy.d +++ b/docs/cmdline-opts/proxy.d @@ -5,11 +5,16 @@ Help: Use this proxy --- Use the specified proxy. -The proxy string can be specified with a protocol:// prefix to specify -alternative proxy protocols. Use socks4://, socks4a://, socks5:// or -socks5h:// to request the specific SOCKS version to be used. No protocol -specified, http:// and all others will be treated as HTTP proxies. (The -protocol support was added in curl 7.21.7) +The proxy string can be specified with a protocol:// prefix. No protocol +specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://, +socks5:// or socks5h:// to request a specific SOCKS version to be used. +(The protocol support was added in curl 7.21.7) + +HTTPS proxy support via https:// protocol prefix was added in 7.52.0 for +OpenSSL, GnuTLS and NSS. + +Unrecognized and unsupported proxy protocols cause an error since 7.52.0. +Prior versions may ignore the protocol and use http:// instead. If the port number is not specified in the proxy string, it is assumed to be 1080. diff --git a/docs/cmdline-opts/socks4.d b/docs/cmdline-opts/socks4.d index ab4536af3..46354408e 100644 --- a/docs/cmdline-opts/socks4.d +++ b/docs/cmdline-opts/socks4.d @@ -6,10 +6,12 @@ Added: 7.15.2 Use the specified SOCKS4 proxy. If the port number is not specified, it is assumed at port 1080. -This option overrides any previous use of --proxy, as they are mutually -exclusive. - Since 7.21.7, this option is superfluous since you can specify a socks4 proxy with --proxy using a socks4:// protocol prefix. +This option typically overrides any previous use of --proxy; however since +7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will +attempt to use it with the SOCKS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/socks4a.d b/docs/cmdline-opts/socks4a.d index a1db1f56a..c7663eebd 100644 --- a/docs/cmdline-opts/socks4a.d +++ b/docs/cmdline-opts/socks4a.d @@ -6,10 +6,12 @@ Added: 7.18.0 Use the specified SOCKS4a proxy. If the port number is not specified, it is assumed at port 1080. -This option overrides any previous use of --proxy, as they are mutually -exclusive. - Since 7.21.7, this option is superfluous since you can specify a socks4a proxy with --proxy using a socks4a:// protocol prefix. +This option typically overrides any previous use of --proxy; however since +7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will +attempt to use it with the SOCKS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/socks5-hostname.d b/docs/cmdline-opts/socks5-hostname.d index d971766af..87bc44a8e 100644 --- a/docs/cmdline-opts/socks5-hostname.d +++ b/docs/cmdline-opts/socks5-hostname.d @@ -6,10 +6,12 @@ Added: 7.18.0 Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If the port number is not specified, it is assumed at port 1080. -This option overrides any previous use of --proxy, as they are mutually -exclusive. - Since 7.21.7, this option is superfluous since you can specify a socks5 hostname proxy with --proxy using a socks5h:// protocol prefix. +This option typically overrides any previous use of --proxy; however since +7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will +attempt to use it with the SOCKS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/socks5.d b/docs/cmdline-opts/socks5.d index 34f0311ed..aa07afeb1 100644 --- a/docs/cmdline-opts/socks5.d +++ b/docs/cmdline-opts/socks5.d @@ -6,12 +6,14 @@ Added: 7.18.0 Use the specified SOCKS5 proxy - but resolve the host name locally. If the port number is not specified, it is assumed at port 1080. -This option overrides any previous use of --proxy, as they are mutually -exclusive. - Since 7.21.7, this option is superfluous since you can specify a socks5 proxy with --proxy using a socks5:// protocol prefix. +This option typically overrides any previous use of --proxy; however since +7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will +attempt to use it with the SOCKS proxy. In such a case curl first connects to +the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy. + If this option is used several times, the last one will be used. This option (as well as --socks4) does not work with IPV6, FTPS or LDAP. diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index 9580ac9d7..03506c9de 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -60,6 +60,10 @@ Number of new connects made in the recent transfer. (Added in 7.12.3) .B num_redirects Number of redirects that were followed in the request. (Added in 7.12.3) .TP +.B proxy_ssl_verify_result +The result of the HTTPS proxy's SSL peer certificate verification that was +requested. 0 means the verification was successful. (Added in 7.52.0) +.TP .B redirect_url When an HTTP request was made without -L to follow redirects, this variable will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2) diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3 index 9a8656114..65f84f528 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY.3 @@ -38,10 +38,22 @@ option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to using port 1080 for proxies. The proxy string may be prefixed with [scheme]:// to specify which kind of -proxy is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last -one to enable socks5 and asking the proxy to do the resolving, also known as -\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to -be used. No scheme specified or http://, will be treated as HTTP proxies. +proxy is used. + +.RS +.IP http:// +HTTP Proxy. Default when no scheme or proxy type is specified. +.IP https:// +HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS) +.IP socks4:// +SOCKS4 Proxy. +.IP socks4a:// +SOCKS4a Proxy. Proxy resolves URL hostname. +.IP socks5:// +SOCKS5 Proxy. +.IP socks5h:// +SOCKS5 Proxy. Proxy resolves URL hostname. +.RE Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify which kind of proxy the string identifies. diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 index d2d924257..19856195e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 @@ -28,15 +28,26 @@ CURLOPT_PROXYTYPE \- proxy protocol type CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYTYPE, long type); .SH DESCRIPTION -Pass a long with this option to set type of the proxy. Available options for -this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP -\fICURLPROXY_SOCKS4\fP, \fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP and -\fICURLPROXY_SOCKS5_HOSTNAME\fP. The HTTP type is default. +Pass one of the values below to set the type of the proxy. -If you set \fICURLOPT_PROXYTYPE(3)\fP to \fICURLPROXY_HTTP_1_0\fP, it will -only affect how libcurl speaks to a proxy when CONNECT is used. The HTTP -version used for "regular" HTTP requests is instead controlled with -\fICURLOPT_HTTP_VERSION(3)\fP. +.RS +.IP CURLPROXY_HTTP +HTTP Proxy. Default. +.IP CURLPROXY_HTTPS +HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS) +.IP CURLPROXY_HTTP_1_0 +HTTP 1.0 Proxy. This is very similar to CURLPROXY_HTTP except it uses HTTP/1.0 +for any CONNECT tunnelling. It does not change the HTTP version of the actual +HTTP requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURLPROXY_SOCKS4 +SOCKS4 Proxy. +.IP CURLPROXY_SOCKS4A +SOCKS4a Proxy. Proxy resolves URL hostname. +.IP CURLPROXY_SOCKS5 +SOCKS5 Proxy. +.IP CURLPROXY_SOCKS5_HOSTNAME +SOCKS5 Proxy. Proxy resolves URL hostname. +.RE Often it is more convenient to specify the proxy type with the scheme part of the \fICURLOPT_PROXY(3)\fP string. -- cgit v1.2.3