Foswiki::Sandbox
internal package
Foswiki::Sandbox
This package provides an interface to the outside world. All calls to
system functions, or handling of file names, should be brokered by
the
sysCommand
function in this package.
Since date indicates where functions or parameters have been added since
the baseline of the API (TWiki release 4.2.3). The
date indicates the
earliest date of a Foswiki release that will support that function or
parameter.
Deprecated date indicates where a function or parameters has been
deprecated. Deprecated
functions will still work, though they should
not be called in new plugins and should be replaced in older plugins
as soon as possible. Deprecated parameters are simply ignored in Foswiki
releases after
date.
Until date indicates where a function or parameter has been removed.
The
date indicates the latest date at which Foswiki releases still supported
the function or parameter.
StaticMethod
untaintUnchecked ( $string ) → $untainted
Untaints
$string
without any checks. If $string is
undefined, return undef.
This function doesn't perform
any checks on the data being untainted.
Callers
must ensure that
$string
does not contain any dangerous content,
such as interpolation characters, if it is to be used in potentially
unsafe operations.
StaticMethod
untaint ( $datum, \&method, ... ) → $untainted
Calls &$method($datum, ...) and if it returns a non-undef result, returns
that result after untainting it. Otherwise returns undef.
\&method can indicate a validation problem in a couple of ways. First, it
can throw an exception. Second, it can return undef, which then causes
the untaint function to return undef.
StaticMethod
validateWebName($name) → $web
Check that the name is valid for use as a web name. Method used for
validation with untaint(). Returns the name, or undef if it is invalid.
StaticMethod
validateTopicName($name) → $topic
Check that the name is valid for use as a topic name. Method used for
validation with untaint(). Returns the name, or undef if it is invalid.
StaticMethod
validateAttachmentName($name) → $attachment
Check that the name is valid for use as an attachment name. Method used for
validation with untaint(). Returns the name, or undef if it is invalid.
Note that the name may contain path separators. This is to permit validation
of an attachment that is stored in a subdirectory somewhere under the
standard Web/Topic/attachment level e.g
Web/Topic/attachmentdir/subdir/attachment.gif. While such attachments cannot
be created via the UI, they
can be created manually on the server.
The individual path components are filtered by $Foswiki::cfg{NameFilter}
StaticMethod
normalizeFileName( $string ) → $filename
Throws an exception if
$string
contains filtered characters, as
defined by
$Foswiki::cfg{NameFilter}
The returned string is not tainted, but it may contain shell
metacharacters and even control characters.
DEPRECATED - provided for compatibility only. Do not use!
If you want to validate an attachment, use
untaint($name, \&validateAttachmentName)
StaticMethod
sanitizeAttachmentName($fname) → ($fileName, $origName)
Given a file name received in a query parameter, sanitise it. Returns
the sanitised name together with the basename before sanitisation.
Sanitation includes removal of all leading path components,
filtering illegal characters and mapping client
file names to a subset of legal server file names.
Avoid using this if you can; encoding attachment names this way is badly
broken, much better to use point-of-source validation to ensure only valid
attachment names are ever uploaded.
StaticMethod
sysCommand( $class, $template, %params ) → ( $data, $exit, $stderr )
Invokes the program described by
$template
and
%params
, and returns the output of the program and an exit code.
STDOUT is returned. STDERR is returned
if possible (or is undef if not).
$class is ignored, and is only present for compatibility.
The caller has to ensure that the invoked program does not react in a
harmful way to the passed arguments.
sysCommand
merely
ensures that the shell does not interpret any of the passed arguments.
$template is a template command-line for the program, which contains
typed tokens that are replaced with parameter values passed in the
sysCommand
call. For example,
my ( $output, $exit ) = Foswiki::Sandbox->sysCommand(
$command,
FILENAME => $filename );
where
$command
is a template for the command - for example,
/usr/bin/rcs -i -t-none -kb %FILENAME|F%
$template
is split at whitespace, and '' strings contained in it
are replaced with
$params{VAR}
.
%params
values may consist of scalars and
array references. Array references are dereferenced and the
array elements are inserted. '' can optionally take the form '%VAR|T%',
where FLAG is a single character type flag. Permitted type flags are
-
U
untaint without further checks -- dangerous,
-
F
normalize as file name,
-
N
generalized number,
-
S
simple, short string,
-
D
RCS format date