setopt: add CURLOPT_PROTOCOLS_STR and CURLOPT_REDIR_PROTOCOLS_STR

... as replacements for deprecated CURLOPT_PROTOCOLS and
CURLOPT_REDIR_PROTOCOLS as these new ones do not risk running into the
32 bit limit the old ones are facing.

CURLINFO_PROTCOOL is now deprecated.

The curl tool is updated to use the new options.

Added test 1597 to verify the libcurl protocol parser.

Closes #8992

docs/libcurl/curl_easy_setopt.3

@@ -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

docs/libcurl/opts/CURLINFO_PROTOCOL.3

@@ -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:
 

docs/libcurl/opts/CURLOPT_PROTOCOLS.3

@@ -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
@@ -71,7 +75,7 @@ CURLPROTO_TELNET
 CURLPROTO_TFTP
 .fi
 .SH DEFAULT
-All protocols built-in
+All protocols built-in.
 .SH PROTOCOLS
 All
 .SH EXAMPLE

docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3

@@ -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), "

docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3

@@ -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

docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3

@@ -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), "

docs/libcurl/opts/Makefile.inc

@@ -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                         \
@@ -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                             \

docs/libcurl/symbols-in-versions

@@ -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
@@ -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

include/curl/curl.h

@@ -1010,7 +1010,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)
@@ -2144,6 +2145,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;
 

include/curl/typecheck-gcc.h

@@ -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 ||                                          \
@@ -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 ||                                     \

lib/easyoptions.c

@@ -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},
@@ -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},
@@ -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},
@@ -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