NAME

DESCRIPTION

a new namespace

The ``root'' of the namespace (i.e. ``main::'') is changed to a different package and code evaluated in the compartment cannot refer to variables outside this namespace, even with run-time glob lookups and other tricks. Code which is compiled outside the compartment can choose to place variables into (or share variables with) the compartment's namespace and only that data will be visible to code evaluated in the compartment.

By default, the only variables shared with compartments are the ``underscore'' variables $_ and @_ (and, technically, the much less frequently used %_, the _ filehandle and so on). This is because otherwise perl operators which default to $_ will not work and neither will the assignment of arguments to @_ on subroutine entry.

an operator mask

Each compartment has an associated ``operator mask''. Recall that perl code is compiled into an internal format before execution. Evaluating perl code (e.g. via ``eval'' or ``do 'file''') causes the code to be compiled into an internal format and then, provided there was no error in the compilation, executed. Code evaulated in a compartment compiles subject to the compartment's operator mask. Attempting to evaulate code in a compartment which contains a masked operator will cause the compilation to fail with an error. The code will not be executed.

By default, the operator mask for a newly created compartment masks out all operations which give ``access to the system'' in some sense. This includes masking off operators such as system, open, chown, and shmget but does not mask off operators such as print, sysread and <HANDL>. Those file operators are allowed since for the code in the compartment to have access to a filehandle, the code outside the compartment must have explicitly placed the filehandle variable inside the compartment.

Since it is only at the compilation stage that the operator mask applies, controlled access to potentially unsafe operations can be achieved by having a handle to a wrapper subroutine (written outside the compartment) placed into the compartment. For example,

$cpt = new Safe; sub wrapper { # vet arguments and perform potentially unsafe operations } $cpt->share('&wrapper');

Operator masks

Methods in class Safe

Optional arguments are (NAMESPACE, MASK), where

NAMESPACE

is the root namespace to use for the compartment (defaults to ``Safe::Root000000000'', auto-incremented for each new compartment); and

MASK

is the operator mask to use (defaults to a fairly restrictive set).

root (NAMESPACE)

This is a get-or-set method for the compartment's namespace. With the NAMESPACE argument present, it sets the root namespace for the compartment. With no NAMESPACE argument present, it returns the current root namespace of the compartment.

mask (MASK)

This is a get-or-set method for the compartment's operator mask. With the MASK argument present, it sets the operator mask for the compartment. With no MASK argument present, it returns the current operator mask of the compartment.

trap (OP, ...)

This sets bits in the compartment's operator mask corresponding to each operator named in the list of arguments. Each OP can be either the name of an operation or its number. See opcode.h or opcode.pl in the main perl distribution for a canonical list of operator names.

untrap (OP, ...)

This resets bits in the compartment's operator mask corresponding to each operator named in the list of arguments. Each OP can be either the name of an operation or its number. See opcode.h or opcode.pl in the main perl distribution for a canonical list of operator names.

share (VARNAME, ...)

This shares the variable(s) in the argument list with the compartment. Each VARNAME must be the name of a variable with a leading type identifier included. Examples of legal variable names are '$foo' for a scalar, '@foo' for an array, '%foo' for a hash, '&foo' for a subroutine and '*foo' for a glob (i.e. all symbol table entries associated with ``foo'', including scalar, array, hash, sub and filehandle).

varglob (VARNAME)

This returns a glob for the symbol table entry of VARNAME in the package of the compartment. VARNAME must be the name of a variable without any leading type marker. For example,

$cpt = new Safe 'Root'; $Root::foo = "Hello world"; # Equivalent version which doesn't need to know $cpt's package name: ${$cpt->varglob('foo')} = "Hello world";

reval (STRING)

This evaluates STRING as perl code inside the compartment. The code can only see the compartment's namespace (as returned by the root method). Any attempt by code in STRING to use an operator which is in the compartment's mask will cause an error (at run-time of the main program but at compile-time for the code in STRING). The error is of the form ``%s trapped by operation mask operation...''. If an operation is trapped in this way, then the code in STRING will not be executed. If such a trapped operation occurs or any other compile-time or return error, then $@ is set to the error message, just as with an eval(). If there is no error, then the method returns the value of the last expression evaluated, or a return statement may be used, just as with subroutines and eval(). Note that this behaviour differs from the beta distribution of the Safe extension where earlier versions of perl made it hard to mimic the return behaviour of the eval() command.

rdo (FILENAME)

This evaluates the contents of file FILENAME inside the compartment. See above documentation on the reval method for further details.

Subroutines in package Safe

ops_to_mask (OP, ...)

This takes a list of operator names and returns an operator mask with precisely those operators masked.

mask_to_ops (MASK)

This takes an operator mask and returns a list of operator names corresponding to those operators which are masked in MASK.

opcode (OP, ...)

This takes a list of operator names and returns the corresponding list of opcodes (which can then be used as byte offsets into a mask).

opname (OP, ...)

This takes a list of opcodes and returns the corresponding list of operator names.

fullmask

This just returns a mask which has all operators masked. It returns the string ``\1'' x MAXO() .

emptymask

This just returns a mask which has all operators unmasked. It returns the string ``\0'' x MAXO() . This is useful if you want a compartment to make use of the namespace protection features but do not want the default restrictive mask.

MAXO

This returns the number of operators (and hence the length of an operator mask). Note that, unlike the beta distributions of the Safe extension, this is derived from a genuine integer variable in the perl executable and not from a preprocessor constant. This means that the Safe extension is more robust in the presence of mismatched versions of the perl executable and the Safe extension.

op_mask

This returns the operator mask which is actually in effect at the time the invocation to the subroutine is compiled. In general, this is probably not terribly useful.

AUTHOR