From d2bcf1e3e247d116dc96bd3ea32056e3f089449c Mon Sep 17 00:00:00 2001 From: "Desmond O. Chang" Date: Thu, 28 Apr 2016 17:33:25 +0800 Subject: url: add option CURLOPT_SUPPRESS_CONNECT_HEADERS - Add new option CURLOPT_SUPPRESS_CONNECT_HEADERS to allow suppressing proxy CONNECT response headers from the user callback functions CURLOPT_HEADERFUNCTION and CURLOPT_WRITEFUNCTION. - Add new tool option --suppress-connect-headers to expose CURLOPT_SUPPRESS_CONNECT_HEADERS and allow suppressing proxy CONNECT response headers from --dump-header and --include. Assisted-by: Jay Satiro Assisted-by: CarloCannas@users.noreply.github.com Closes https://github.com/curl/curl/pull/783 --- docs/cmdline-opts/Makefile.am | 3 +- docs/cmdline-opts/proxytunnel.d | 3 + docs/cmdline-opts/suppress-connect-headers.d | 8 ++ docs/libcurl/curl_easy_setopt.3 | 2 + docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 | 3 + docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 | 3 + .../opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 | 95 ++++++++++++++++++++++ docs/libcurl/opts/Makefile.am | 1 + docs/libcurl/symbols-in-versions | 1 + 9 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 docs/cmdline-opts/suppress-connect-headers.d create mode 100644 docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 (limited to 'docs') diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index f425ddd08..5cfd67605 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -59,7 +59,8 @@ DPAGES = abstract-unix-socket.d anyauth.d append.d basic.d cacert.d capath.d cer service-name.d show-error.d silent.d socks4a.d socks4.d socks5.d \ socks5-gssapi-nec.d socks5-gssapi-service.d socks5-hostname.d \ speed-limit.d speed-time.d ssl-allow-beast.d ssl.d ssl-no-revoke.d \ - ssl-reqd.d sslv2.d sslv3.d stderr.d tcp-fastopen.d tcp-nodelay.d \ + ssl-reqd.d sslv2.d sslv3.d stderr.d suppress-connect-headers.d \ + tcp-fastopen.d tcp-nodelay.d \ telnet-option.d tftp-blksize.d tftp-no-options.d time-cond.d \ tls-max.d \ tlsauthtype.d tlspassword.d tlsuser.d tlsv1.0.d tlsv1.1.d tlsv1.2.d \ diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d index 09855ed34..f2e8b802d 100644 --- a/docs/cmdline-opts/proxytunnel.d +++ b/docs/cmdline-opts/proxytunnel.d @@ -8,3 +8,6 @@ to attempt to tunnel through the proxy instead of merely using it to do HTTP-like operations. The tunnel approach is made with the HTTP proxy CONNECT request and requires that the proxy allows direct connect to the remote port number curl wants to tunnel through to. + +To suppress proxy CONNECT response headers when curl is set to output headers +use --suppress-connect-headers. diff --git a/docs/cmdline-opts/suppress-connect-headers.d b/docs/cmdline-opts/suppress-connect-headers.d new file mode 100644 index 000000000..d208b8917 --- /dev/null +++ b/docs/cmdline-opts/suppress-connect-headers.d @@ -0,0 +1,8 @@ +Long: suppress-connect-headers +Help: Suppress proxy CONNECT response headers +See-also: dump-header include proxytunnel +--- +When --proxytunnel is used and a CONNECT request is made don't output proxy +CONNECT response headers. This option is meant to be used with --dump-header or +--include which are used to show protocol headers in the output. It has no +effect on debug options such as --verbose or --trace, or any statistics. diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 422cb8569..cb6884766 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -137,6 +137,8 @@ Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP .IP CURLOPT_FNMATCH_DATA Data pointer to pass to the wildcard matching callback. See \fICURLOPT_FNMATCH_DATA(3)\fP +.IP CURLOPT_SUPPRESS_CONNECT_HEADERS +Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 index b4b9b578f..b687c80b9 100644 --- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 +++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 @@ -30,6 +30,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HEADER_SIZE, long *sizep); .SH DESCRIPTION Pass a pointer to a long to receive the total size of all the headers received. Measured in number of bytes. + +The total includes the size of any received headers suppressed by +\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 index 6b48a0527..bdd04dfff 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 @@ -40,6 +40,9 @@ it allows CONNECT requests to and often only port 80 and 443 are allowed. When using this, it only makes sense to use \fICURLOPT_PROXYTYPE(3)\fP set to a HTTP proxy. + +To suppress proxy CONNECT response headers from user callbacks use +\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 new file mode 100644 index 000000000..8cfec7a8f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 @@ -0,0 +1,95 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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.haxx.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_SUPPRESS_CONNECT_HEADERS 3 "13 February 2017" "libcurl 7.54.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SUPPRESS_CONNECT_HEADERS \- Suppress proxy CONNECT response headers from user callbacks +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff); +.fi +.SH DESCRIPTION +When \fICURLOPT_HTTPPROXYTUNNEL(3)\fP is used and a CONNECT request is made, +suppress proxy CONNECT response headers from the user callback functions +\fICURLOPT_HEADERFUNCTION(3)\fP and \fICURLOPT_WRITEFUNCTION(3)\fP. + +Proxy CONNECT response headers can complicate header processing since it's +essentially a separate set of headers. You can enable this option to suppress +those headers. + +For example let's assume an HTTPS URL is to be retrieved via CONNECT. On +success there would normally be two sets of headers, and each header line sent +to the header function and/or the write function. The data given to the +callbacks would look like this: + +.nf +HTTP/1.1 200 Connection established +{headers}... + +HTTP/1.1 200 OK +Content-Type: application/json +{headers}... + +{body}... +.fi + +However by enabling this option the CONNECT response headers are suppressed, so +the data given to the callbacks would look like this: + +.nf +HTTP/1.1 200 OK +Content-Type: application/json +{headers}... + +{body}... +.fi + +.SH DEFAULT +0 +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADER, 1L); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128"); + curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); + curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in 7.54.0 +.SH RETURN VALUE +CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. +.SH "SEE ALSO" +.BR CURLOPT_HEADER "(3), " CURLOPT_PROXY "(3), " +.BR CURLOPT_HTTPPROXYTUNNEL "(3), " diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 5829a144f..26bb2eeb9 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -300,6 +300,7 @@ man_MANS = \ CURLOPT_STREAM_DEPENDS.3 \ CURLOPT_STREAM_DEPENDS_E.3 \ CURLOPT_STREAM_WEIGHT.3 \ + CURLOPT_SUPPRESS_CONNECT_HEADERS.3 \ CURLOPT_TCP_FASTOPEN.3 \ CURLOPT_TCP_KEEPALIVE.3 \ CURLOPT_TCP_KEEPIDLE.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index f4cd9805f..6ac8869ca 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -559,6 +559,7 @@ CURLOPT_STDERR 7.1 CURLOPT_STREAM_DEPENDS 7.46.0 CURLOPT_STREAM_DEPENDS_E 7.46.0 CURLOPT_STREAM_WEIGHT 7.46.0 +CURLOPT_SUPPRESS_CONNECT_HEADERS 7.54.0 CURLOPT_TCP_KEEPALIVE 7.25.0 CURLOPT_TCP_KEEPIDLE 7.25.0 CURLOPT_TCP_KEEPINTVL 7.25.0 -- cgit v1.2.3