Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

setopt: add CURLOPT_PROTOCOLS_STR and CURLOPT_REDIR_PROTOCOLS_STR #8992

Closed
wants to merge 1 commit into from
Closed

setopt: add CURLOPT_PROTOCOLS_STR and CURLOPT_REDIR_PROTOCOLS_STR #8992

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/libcurl/curl_easy_setopt.3
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,9 +167,14 @@ URL to work on. See \fICURLOPT_URL(3)\fP
.IP CURLOPT_PATH_AS_IS
Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP
.IP CURLOPT_PROTOCOLS
Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP
\fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP
.IP CURLOPT_PROTOCOLS_STR
Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP
.IP CURLOPT_REDIR_PROTOCOLS
Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS(3)\fP
\fBDeprecated option\fP Protocols to allow redirects to. See
\fICURLOPT_REDIR_PROTOCOLS(3)\fP
.IP CURLOPT_REDIR_PROTOCOLS_STR
Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP
.IP CURLOPT_DEFAULT_PROTOCOL
Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP
.IP CURLOPT_PROXY
Expand Down
4 changes: 4 additions & 0 deletions docs/libcurl/opts/CURLINFO_PROTOCOL.3
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ CURLINFO_PROTOCOL \- get the protocol used in the connection
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROTOCOL, long *p);
.fi
.SH DESCRIPTION
This option is deprecated. We strongly recommend using
\fICURLINFO_SCHEME(3)\fP instead, because this option cannot return all
possible protocols!

Pass a pointer to a long to receive the version used in the last http
connection. The returned value will be exactly one of the CURLPROTO_* values:

Expand Down
6 changes: 5 additions & 1 deletion docs/libcurl/opts/CURLOPT_PROTOCOLS.3
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ CURLOPT_PROTOCOLS \- allowed protocols
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask);
.fi
.SH DESCRIPTION
This option is deprecated. We strongly recommend using
\fICURLOPT_PROTOCOLS_STR(3)\fP instead because this option cannot control all
available protocols!

Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in the transfer. This allows you to have
a libcurl built to support a wide range of protocols but still limit specific
Expand Down Expand Up @@ -71,7 +75,7 @@ CURLPROTO_TELNET
CURLPROTO_TFTP
.fi
.SH DEFAULT
All protocols built-in
All protocols built-in.
.SH PROTOCOLS
All
.SH EXAMPLE
Expand Down
82 changes: 82 additions & 0 deletions docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROTOCOLS_STR 3 "11 Jun 2022" "libcurl 7.85.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROTOCOLS_STR \- allowed protocols
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS_STR, char *spec);
.fi
.SH DESCRIPTION
Pass a pointer to a string that holds a comma-separated list of case
insensitive protocol names (URL schemes) to allow in the transfer. This
option allows applications to use libcurl built to support a wide range of
protocols but still limit specific transfers to only be allowed to use a
subset of them. By default, libcurl accepts all protocols it was built with
support for. See also \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP.

If trying to set a non-existing protocol or if no matching protocol at all is
set, it returns error.

These are the available protocols:

DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS,
POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, SMB,
SMBS, SMTP, SMTPS, TELNET, TFTP

You can set "ALL" as a short-cut to enable all protocols. Note that by setting
all, you may enable protocols that were not supported the day you write this
but are introduced in a future libcurl version.

\fIcurl_version_info(3)\fP can be used to get a list of all supported
protocols in the current libcurl. \fICURLINFO_SCHEME(3)\fP is the recommended
way to figure out the protocol used in a previous transfer.
.SH DEFAULT
All protocols built-in
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* pass in the URL from an external source */
curl_easy_setopt(curl, CURLOPT_URL, argv[1]);

/* only allow HTTP, TFTP and SFTP */
curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,tftp,sftp");

/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.85.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_REDIR_PROTOCOLS_STR "(3), " CURLOPT_URL "(3), "
.BR curl_version_info "(3), " CURLINFO_SCHEME "(3), "
4 changes: 4 additions & 0 deletions docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ CURLOPT_REDIR_PROTOCOLS \- protocols allowed to redirect to
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS, long bitmask);
.fi
.SH DESCRIPTION
This option is deprecated. We strongly recommend using
\fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP instead because this option cannot
control all available protocols!

Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in a transfer that it follows to in a
redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to
Expand Down
89 changes: 89 additions & 0 deletions docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_REDIR_PROTOCOLS_STR 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_REDIR_PROTOCOLS_STR \- protocols allowed to redirect to
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS_STR,
char *spec);
.fi
.SH DESCRIPTION
Pass a pointer to a string that holds a comma-separated list of case
insensitive protocol names (URL schemes). That list limits what protocols
libcurl may use in a transfer that it follows to in a redirect when
\fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This option allows applications to
limit specific transfers to only be allowed to use a subset of protocols in
redirections.

Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this
option.

By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirects (since
7.65.2). Older versions of libcurl allowed all protocols on redirect except
several disabled for security reasons: Since 7.19.4 FILE and SCP are disabled,
and since 7.40.0 SMB and SMBS are also disabled.

These are the available protocols:

DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS,
POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, SMB,
SMBS, SMTP, SMTPS, TELNET, TFTP

You can set "ALL" as a short-cut to enable all protocols. Note that by setting
all, you may enable protocols that were not supported the day you write this
but are introduced in a future libcurl version.

If trying to set a non-existing protocol or if no matching protocol at all is
set, it returns error.
.SH DEFAULT
HTTP, HTTPS, FTP and FTPS (Added in 7.65.2).

Older versions defaulted to all protocols except FILE, SCP and since 7.40.0
SMB and SMBS.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* pass in the URL from an external source */
curl_easy_setopt(curl, CURLOPT_URL, argv[1]);

/* only allow redirects to HTTP and HTTPS URLs */
curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS_STR, "http,https");

/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.85.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PROTOCOLS_STR "(3), "
2 changes: 2 additions & 0 deletions docs/libcurl/opts/Makefile.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,7 @@ man_MANS = \
CURLOPT_PROGRESSDATA.3 \
CURLOPT_PROGRESSFUNCTION.3 \
CURLOPT_PROTOCOLS.3 \
CURLOPT_PROTOCOLS_STR.3 \
CURLOPT_PROXY.3 \
CURLOPT_PROXYAUTH.3 \
CURLOPT_PROXYHEADER.3 \
Expand Down Expand Up @@ -307,6 +308,7 @@ man_MANS = \
CURLOPT_READDATA.3 \
CURLOPT_READFUNCTION.3 \
CURLOPT_REDIR_PROTOCOLS.3 \
CURLOPT_REDIR_PROTOCOLS_STR.3 \
CURLOPT_REFERER.3 \
CURLOPT_REQUEST_TARGET.3 \
CURLOPT_RESOLVE.3 \
Expand Down
2 changes: 2 additions & 0 deletions docs/libcurl/symbols-in-versions
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -722,6 +722,7 @@ CURLOPT_PRIVATE 7.10.3
CURLOPT_PROGRESSDATA 7.1
CURLOPT_PROGRESSFUNCTION 7.1 7.32.0
CURLOPT_PROTOCOLS 7.19.4
CURLOPT_PROTOCOLS_STR 7.85.0
CURLOPT_PROXY 7.1
CURLOPT_PROXY_CAINFO 7.52.0
CURLOPT_PROXY_CAINFO_BLOB 7.77.0
Expand Down Expand Up @@ -762,6 +763,7 @@ CURLOPT_RANGE 7.1
CURLOPT_READDATA 7.9.7
CURLOPT_READFUNCTION 7.1
CURLOPT_REDIR_PROTOCOLS 7.19.4
CURLOPT_REDIR_PROTOCOLS_STR 7.85.0
CURLOPT_REFERER 7.1
CURLOPT_REQUEST_TARGET 7.55.0
CURLOPT_RESOLVE 7.21.3
Expand Down
12 changes: 11 additions & 1 deletion include/curl/curl.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1009,7 +1009,8 @@ typedef CURLSTScode (*curl_hstswrite_callback)(CURL *easy,
#define CURLHSTS_ENABLE (long)(1<<0)
#define CURLHSTS_READONLYFILE (long)(1<<1)

/* CURLPROTO_ defines are for the CURLOPT_*PROTOCOLS options */
/* The CURLPROTO_ defines below are for the **deprecated** CURLOPT_*PROTOCOLS
options. Do not use. */
#define CURLPROTO_HTTP (1<<0)
#define CURLPROTO_HTTPS (1<<1)
#define CURLPROTO_FTP (1<<2)
Expand Down Expand Up @@ -2143,6 +2144,15 @@ typedef enum {
/* set the SSH host key callback custom pointer */
CURLOPT(CURLOPT_SSH_HOSTKEYDATA, CURLOPTTYPE_CBPOINT, 317),

/* specify which protocols that are allowed to be used for the transfer,
which thus helps the app which takes URLs from users or other external
inputs and want to restrict what protocol(s) to deal with. Defaults to
all built-in protocols. */
CURLOPT(CURLOPT_PROTOCOLS_STR, CURLOPTTYPE_STRINGPOINT, 318),

/* specify which protocols that libcurl is allowed to follow directs to */
CURLOPT(CURLOPT_REDIR_PROTOCOLS_STR, CURLOPTTYPE_STRINGPOINT, 319),

CURLOPT_LASTENTRY /* the last unused */
} CURLoption;

Expand Down
12 changes: 7 additions & 5 deletions include/curl/typecheck-gcc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,9 +272,9 @@ CURLWARNING(_curl_easy_getinfo_err_curl_off_t,
(option) == CURLOPT_DNS_SERVERS || \
(option) == CURLOPT_DOH_URL || \
(option) == CURLOPT_EGDSOCKET || \
(option) == CURLOPT_FTPPORT || \
(option) == CURLOPT_FTP_ACCOUNT || \
(option) == CURLOPT_FTP_ALTERNATIVE_TO_USER || \
(option) == CURLOPT_FTPPORT || \
(option) == CURLOPT_HSTS || \
(option) == CURLOPT_INTERFACE || \
(option) == CURLOPT_ISSUERCERT || \
Expand All @@ -288,28 +288,30 @@ CURLWARNING(_curl_easy_getinfo_err_curl_off_t,
(option) == CURLOPT_PASSWORD || \
(option) == CURLOPT_PINNEDPUBLICKEY || \
(option) == CURLOPT_PRE_PROXY || \
(option) == CURLOPT_PROTOCOLS_STR || \
(option) == CURLOPT_PROXY || \
(option) == CURLOPT_PROXYPASSWORD || \
(option) == CURLOPT_PROXYUSERNAME || \
(option) == CURLOPT_PROXYUSERPWD || \
(option) == CURLOPT_PROXY_CAINFO || \
(option) == CURLOPT_PROXY_CAPATH || \
(option) == CURLOPT_PROXY_CRLFILE || \
(option) == CURLOPT_PROXY_ISSUERCERT || \
(option) == CURLOPT_PROXY_KEYPASSWD || \
(option) == CURLOPT_PROXY_PINNEDPUBLICKEY || \
(option) == CURLOPT_PROXY_SERVICE_NAME || \
(option) == CURLOPT_PROXY_SSL_CIPHER_LIST || \
(option) == CURLOPT_PROXY_SSLCERT || \
(option) == CURLOPT_PROXY_SSLCERTTYPE || \
(option) == CURLOPT_PROXY_SSLKEY || \
(option) == CURLOPT_PROXY_SSLKEYTYPE || \
(option) == CURLOPT_PROXY_SSL_CIPHER_LIST || \
(option) == CURLOPT_PROXY_TLS13_CIPHERS || \
(option) == CURLOPT_PROXY_TLSAUTH_PASSWORD || \
(option) == CURLOPT_PROXY_TLSAUTH_TYPE || \
(option) == CURLOPT_PROXY_TLSAUTH_USERNAME || \
(option) == CURLOPT_PROXYPASSWORD || \
(option) == CURLOPT_PROXYUSERNAME || \
(option) == CURLOPT_PROXYUSERPWD || \
(option) == CURLOPT_RANDOM_FILE || \
(option) == CURLOPT_RANGE || \
(option) == CURLOPT_REDIR_PROTOCOLS_STR || \
(option) == CURLOPT_REFERER || \
(option) == CURLOPT_REQUEST_TARGET || \
(option) == CURLOPT_RTSP_SESSION_ID || \
Expand Down
8 changes: 5 additions & 3 deletions lib/easyoptions.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,7 @@ struct curl_easyoption Curl_easyopts[] = {
{"PROGRESSDATA", CURLOPT_XFERINFODATA, CURLOT_CBPTR, CURLOT_FLAG_ALIAS},
{"PROGRESSFUNCTION", CURLOPT_PROGRESSFUNCTION, CURLOT_FUNCTION, 0},
{"PROTOCOLS", CURLOPT_PROTOCOLS, CURLOT_LONG, 0},
{"PROTOCOLS_STR", CURLOPT_PROTOCOLS_STR, CURLOT_STRING, 0},
{"PROXY", CURLOPT_PROXY, CURLOT_STRING, 0},
{"PROXYAUTH", CURLOPT_PROXYAUTH, CURLOT_VALUES, 0},
{"PROXYHEADER", CURLOPT_PROXYHEADER, CURLOT_SLIST, 0},
Expand Down Expand Up @@ -245,6 +246,7 @@ struct curl_easyoption Curl_easyopts[] = {
{"READDATA", CURLOPT_READDATA, CURLOT_CBPTR, 0},
{"READFUNCTION", CURLOPT_READFUNCTION, CURLOT_FUNCTION, 0},
{"REDIR_PROTOCOLS", CURLOPT_REDIR_PROTOCOLS, CURLOT_LONG, 0},
{"REDIR_PROTOCOLS_STR", CURLOPT_REDIR_PROTOCOLS_STR, CURLOT_STRING, 0},
{"REFERER", CURLOPT_REFERER, CURLOT_STRING, 0},
{"REQUEST_TARGET", CURLOPT_REQUEST_TARGET, CURLOT_STRING, 0},
{"RESOLVE", CURLOPT_RESOLVE, CURLOT_SLIST, 0},
Expand Down Expand Up @@ -275,14 +277,14 @@ struct curl_easyoption Curl_easyopts[] = {
{"SOCKS5_GSSAPI_SERVICE", CURLOPT_SOCKS5_GSSAPI_SERVICE, CURLOT_STRING, 0},
{"SSH_AUTH_TYPES", CURLOPT_SSH_AUTH_TYPES, CURLOT_VALUES, 0},
{"SSH_COMPRESSION", CURLOPT_SSH_COMPRESSION, CURLOT_LONG, 0},
{"SSH_HOSTKEYDATA", CURLOPT_SSH_HOSTKEYDATA, CURLOT_CBPTR, 0},
{"SSH_HOSTKEYFUNCTION", CURLOPT_SSH_HOSTKEYFUNCTION, CURLOT_FUNCTION, 0},
{"SSH_HOST_PUBLIC_KEY_MD5", CURLOPT_SSH_HOST_PUBLIC_KEY_MD5,
CURLOT_STRING, 0},
{"SSH_HOST_PUBLIC_KEY_SHA256", CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256,
CURLOT_STRING, 0},
{"SSH_KEYDATA", CURLOPT_SSH_KEYDATA, CURLOT_CBPTR, 0},
{"SSH_KEYFUNCTION", CURLOPT_SSH_KEYFUNCTION, CURLOT_FUNCTION, 0},
{"SSH_HOSTKEYDATA", CURLOPT_SSH_HOSTKEYDATA, CURLOT_CBPTR, 0},
{"SSH_HOSTKEYFUNCTION", CURLOPT_SSH_HOSTKEYFUNCTION, CURLOT_FUNCTION, 0},
{"SSH_KNOWNHOSTS", CURLOPT_SSH_KNOWNHOSTS, CURLOT_STRING, 0},
{"SSH_PRIVATE_KEYFILE", CURLOPT_SSH_PRIVATE_KEYFILE, CURLOT_STRING, 0},
{"SSH_PUBLIC_KEYFILE", CURLOPT_SSH_PUBLIC_KEYFILE, CURLOT_STRING, 0},
Expand Down Expand Up @@ -364,6 +366,6 @@ struct curl_easyoption Curl_easyopts[] = {
*/
int Curl_easyopts_check(void)
{
return ((CURLOPT_LASTENTRY%10000) != (317 + 1));
return ((CURLOPT_LASTENTRY%10000) != (319 + 1));
}
#endif
Loading