data/TWiki/TWikiSandboxDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
---+ Package =TWiki::Sandbox=
colas@0
     2
colas@0
     3
This object provides an interface to the outside world. All calls to
colas@0
     4
system functions, or handling of file names, should be brokered by
colas@0
     5
this object.
colas@0
     6
colas@0
     7
NOTE: TWiki creates a singleton sandbox that is *shared* by all TWiki
colas@0
     8
runs under a single mod_perl instance. If any TWiki run modifies the
colas@0
     9
sandbox, that modification will carry over in to subsequent runs.
colas@0
    10
Be very, very careful!
colas@0
    11
colas@0
    12
colas@0
    13
%TOC%
colas@0
    14
colas@0
    15
---++ ClassMethod *new* <tt>($os,$realOS)</tt>
colas@0
    16
colas@0
    17
Construct a new sandbox suitable for $os, setting
colas@0
    18
flags for platform features that help.  $realOS distinguishes
colas@0
    19
Perl variants on platforms such as Windows.
colas@0
    20
colas@0
    21
colas@0
    22
colas@0
    23
---++ ObjectMethod *finish* <tt>()</tt>
colas@0
    24
Break circular references.
colas@0
    25
colas@0
    26
colas@0
    27
colas@0
    28
---++ StaticMethod *untaintUnchecked* <tt>($string) -> $untainted</tt>
colas@0
    29
colas@0
    30
Untaints $string without any checks (dangerous).  If $string is
colas@0
    31
undefined, return undef.
colas@0
    32
colas@0
    33
The intent is to use this routine to be able to find all untainting
colas@0
    34
places using grep.
colas@0
    35
colas@0
    36
colas@0
    37
colas@0
    38
---++ StaticMethod *normalizeFileName* <tt>($string) -> $filename</tt>
colas@0
    39
colas@0
    40
Errors out if $string contains filtered characters.
colas@0
    41
colas@0
    42
The returned string is not tainted, but it may contain shell
colas@0
    43
metacharacters and even control characters.
colas@0
    44
colas@0
    45
colas@0
    46
colas@0
    47
---++ StaticMethod *sanitizeAttachmentName* <tt>($fname) -> ($fileName,$origName)</tt>
colas@0
    48
colas@0
    49
Given a file name received in a query parameter, sanitise it. Returns
colas@0
    50
the sanitised name together with the basename before sanitisation.
colas@0
    51
colas@0
    52
Sanitisation includes filtering illegal characters and mapping client
colas@0
    53
file names to legal server names.
colas@0
    54
colas@0
    55
colas@0
    56
colas@0
    57
---++ ObjectMethod *sysCommand* <tt>($template,@params) -> ($data,$exit)</tt>
colas@0
    58
colas@0
    59
Invokes the program described by $template
colas@0
    60
and @params, and returns the output of the program and an exit code.
colas@0
    61
STDOUT is returned. STDERR is THROWN AWAY.
colas@0
    62
colas@0
    63
The caller has to ensure that the invoked program does not react in a
colas@0
    64
harmful way to the passed arguments.  sysCommand merely
colas@0
    65
ensures that the shell does not interpret any of the passed arguments.
colas@0
    66
colas@0
    67