bug#21702: shell-quote-argument semantics and safety

[Eli Zaretskii <eliz@gnu.org>]

> From: taylanbayirli@gmail.com (Taylan Ulrich
> 	Bayırlı/Kammer)
> Date: Sun, 18 Oct 2015 14:36:03 +0200
> 
> The documentation of shell-quote-argument only says
> 
>     Quote ARGUMENT for passing as argument to an inferior shell.
> 
> It's unclear for which shells this is supposed to work.

I fixed the doc string to clarify that this function works correctly
with the system's standard shell.

> In a recent thread in emacs-devel, it has been demonstrated that if
> the result is passed to csh, it can allow an attacker to execute an
> arbitrary shell command

As I understand it, csh is not the standard shell on Posix systems, so
the fixed doc string now says not to expect it to work with csh.

> The function should clearly document
> 
>     1) for which shells will the quoting work absolutely, i.e. lead to
>     the given string to appear *verbatim* in an element of the ARGV of
>     the called command,
> 
>     2) optionally, for which shells will the quoting at least prevent
>     code injection,
> 
>     3) optionally, for which shells and character sets for ARGUMENT will
>     the quoting work absolutely,
> 
>     4) optionally, for which shells and character sets for ARGUMENT will
>     the quoting at least prevent code injection,
> 
>     5) optionally, for which shells will the quoting work at all even if
>     it provides no clear semantics, such that one can at least use it
>     with data coming from trusted sources (e.g. other parts of Emacs's
>     source code, or the user sitting in front of Emacs), where it's the
>     user's/programmer's responsibility to stick to values for ARGUMENT
>     that are intuitively known to be unproblematic even if the character
>     set isn't well-defined.
> 
> Currently #5 seems to be implied for all shells, for lack of further
> documentation.  Possibly, the function was never meant to be used with
> untrusted data, but there's no warning against doing so either.

I thin 1) is now covered, and the rest are optional.  In particular,
our way to provide better safety is not by documenting APIs that could
be maliciously abused, but by marking the related variables as unsafe
unless they have special predefined values.  So I don't think we
should extend this particular doc string with safety information.

>  (defun shell-quote-argument (argument)
> -  "Quote ARGUMENT for passing as argument to an inferior shell."
> +  "Quote ARGUMENT for passing as argument to an inferior shell.
> +
> +This is safe for shells conforming to POSIX sh.  No guarantees
> +regarding code injection are made for other shells, but csh,
> +MS-DOS and Windows NT are supported for simple cases as well."

Thanks, but I think this is no longer needed, after the change I made.