mime: use percent-escaping for multipart form field and file names

Until now, form field and file names where escaped using the
backslash-escaping algorithm defined for multipart mails. This commit
replaces this with the percent-escaping method for URLs.

As this may introduce incompatibilities with server-side applications, a
new libcurl option CURLOPT_MIME_OPTIONS with bitmask
CURLMIMEOPT_FORMESCAPE is introduced to revert to legacy use of
backslash-escaping. This is controlled by new cli tool option
--form-escape.

New tests and documentation are provided for this feature.

Reported by: Ryan Sleevi
Fixes #7789
Closes #7805

docs/cmdline-opts/Makefile.inc

@@ -75,6 +75,7 @@ DPAGES = \
   fail-with-body.d \
   fail.d \
   false-start.d \
+  form-escape.d \
   form-string.d \
   form.d \
   ftp-account.d \

docs/cmdline-opts/form-escape.d

@@ -0,0 +1,10 @@
+Long: form-escape
+Help: Escape multipart form field/file names using backslash
+Protocols: HTTP
+See-also: form
+Added: 7.81.0
+Category: http post
+Example: --form-escape --form 'field\\name=curl' 'file=@load"this' $URL
+---
+Tells curl to pass on names of multipart form fields and files using
+backslash-escaping instead of percent-encoding.

docs/libcurl/curl_easy_setopt.3

@@ -462,6 +462,8 @@ Upload data. See \fICURLOPT_UPLOAD(3)\fP
 Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP
 .IP CURLOPT_MIMEPOST
 Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP
+.IP CURLOPT_MIME_OPTIONS
+Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(3)\fP
 .IP CURLOPT_MAXFILESIZE
 Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP
 .IP CURLOPT_MAXFILESIZE_LARGE

docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3

@@ -0,0 +1,89 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  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_MIME_OPTIONS 3 "2 Oct 2021" "libcurl 7.81.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_MIME_OPTIONS \- set MIME option flags
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIME_OPTIONS, long options);
+.SH DESCRIPTION
+Pass a long that holds a bitmask of CURLMIMEOPT_* defines. Each bit is a
+Boolean flag used while encoding a MIME tree or multipart form data.
+
+Available bits are:
+.IP CURLMIMEOPT_FORMESCAPE
+Tells libcurl to escape multipart form field and file names using the
+backslash-escaping algorithm rather than percent-encoding (HTTP only).
+
+Backslash-escaping consists in preceding backslashes and double quotes with
+a backslash. Percent encoding maps all occurrences of double quote,
+carriage return and line feed to %22, %0D and %0A respectively.
+
+Before version 7.81.0, percent-encoding was never applied.
+
+HTTP browsers used to do backslash-escaping in the past but have over time
+transitioned to use percent-encoding. This option allows to address
+server-side applications that have not yet have been converted.
+
+As an example, consider field or file name \fIstrange\\name"kind\fP.
+When the containing multipart form is sent, this is normally transmitted as
+\fIstrange\\name%22kind\fP. When this option is set, it is sent as
+\fIstrange\\\\name\\"kind\fP.
+.SH DEFAULT
+0, meaning disabled.
+.SH PROTOCOLS
+HTTP, IMAP, SMTP
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+curl_mime *form = NULL;
+
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  curl_easy_setopt(curl, CURLOPT_MIME_OPTIONS, CURLMIMEOPT_FORMESCAPE);
+
+  form = curl_mime_init(curl);
+  if(form) {
+    curl_mimepart *part = curl_mime_addpart(form);
+
+    if(part) {
+      curl_mime_filedata(part, "strange\\\\file\\\\name");
+      curl_mime_name(part, "strange\\"field\\"name");
+      curl_easy_setopt(curl, CURLOPT_MIMEPOST, form);
+
+      /* Perform the request */
+      curl_easy_perform(curl);
+    }
+  }
+
+  curl_easy_cleanup(curl);
+  curl_mime_free(mime);
+}
+.fi
+.SH AVAILABILITY
+Option added in 7.81.0.
+.SH RETURN VALUE
+Returns CURLE_OK
+.SH "SEE ALSO"
+.BR CURLOPT_MIMEPOST "(3), " CURLOPT_HTTPPOST "(3)"

docs/libcurl/opts/Makefile.inc

@@ -233,6 +233,7 @@ man_MANS =                                      \
   CURLOPT_MAX_RECV_SPEED_LARGE.3                \
   CURLOPT_MAX_SEND_SPEED_LARGE.3                \
   CURLOPT_MIMEPOST.3                            \
+  CURLOPT_MIME_OPTIONS.3                        \
   CURLOPT_NETRC.3                               \
   CURLOPT_NETRC_FILE.3                          \
   CURLOPT_NEW_DIRECTORY_PERMS.3                 \

docs/libcurl/symbols-in-versions

@@ -324,6 +324,7 @@ CURLKHTYPE_ED25519              7.58.0
 CURLKHTYPE_RSA                  7.19.6
 CURLKHTYPE_RSA1                 7.19.6
 CURLKHTYPE_UNKNOWN              7.19.6
+CURLMIMEOPT_FORMESCAPE          7.81.0
 CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 7.30.0
 CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 7.30.0
 CURLMOPT_MAXCONNECTS            7.16.3
@@ -504,6 +505,7 @@ CURLOPT_MAXREDIRS               7.5
 CURLOPT_MAX_RECV_SPEED_LARGE    7.15.5
 CURLOPT_MAX_SEND_SPEED_LARGE    7.15.5
 CURLOPT_MIMEPOST                7.56.0
+CURLOPT_MIME_OPTIONS            7.81.0
 CURLOPT_MUTE                    7.1           7.8         7.15.5
 CURLOPT_NETRC                   7.1
 CURLOPT_NETRC_FILE              7.11.0

docs/options-in-versions

@@ -64,6 +64,7 @@
 --fail-with-body                     7.76.0
 --false-start                        7.42.0
 --form (-F)                          5.0
+--form-escape                        7.81.0
 --form-string                        7.13.2
 --ftp-account                        7.13.0
 --ftp-alternative-to-user            7.15.5