MAN page from Old RedHat 5.X perl-5.004-4.i386.rpm

Safe

Section: Perl Programmers Reference Guide (3)
Updated: perl 5.004, patch 04
Index

NAME

Safe - Compile and execute code in restricted compartments

SYNOPSIS

  use Safe;

  $compartment = new Safe;

  $compartment->permit(qw(time sort :browse));

  $result = $compartment->reval($unsafe_code);

DESCRIPTION

The Safe extension module allows the creation of compartmentsin which perl code can be evaluated. Each compartment has

a new namespace

The ``root'' of the namespace (i.e. ``main::") is changed to adifferent package and code evaluated in the compartment cannotrefer to variables outside this namespace, even with run-timeglob lookups and other tricks.

Code which is compiled outside the compartment can choose to placevariables into (or share variables with) the compartment's namespaceand only that data will be visible to code evaluated in thecompartment.

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

an operator mask

Each compartment has an associated ``operator mask''. Recall thatperl code is compiled into an internal format before execution.Evaluating perl code (e.g. via ``eval'' or ``do `file'") causesthe 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 thecompartment's operator mask. Attempting to evaulate code in acompartment which contains a masked operator will cause thecompilation to fail with an error. The code will not be executed.

The default operator mask for a newly created compartment isthe `:default' optag.

It is important that you read the Opcode(3) module documentationfor more information, especially for detailed definitions of opnames,optags and opsets.

Since it is only at the compilation stage that the operator maskapplies, controlled access to potentially unsafe operations canbe achieved by having a handle to a wrapper subroutine (writtenoutside the compartment) placed into the compartment. For example,

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

WARNING

The authors make no warranty, implied or otherwise, about thesuitability of this software for safety or security purposes.

The authors shall not in any case be liable for special, incidental,consequential, indirect or other similar damages arising from the useof this software.

Your mileage will vary. If in any doubt do not use it.

RECENT CHANGES

The interface to the Safe module has changed quite dramatically sinceversion 1 (as supplied with Perl5.002). Study these pages carefully ifyou have code written to use Safe version 1 because you will need tomakes changes.

Methods in class Safe

To create a new compartment, use

    $cpt = new Safe;

Optional argument is (NAMESPACE), where NAMESPACE is the root namespaceto use for the compartment (defaults to ``Safe::Root0'', incremented foreach new compartment).

Note that version 1.00 of the Safe module supported a second optionalparameter, MASK. That functionality has been withdrawn pending deeperconsideration. Use the permit and deny methods described below.

The following methods can then be used on the compartmentobject returned by the above constructor. The object argumentis implicit in each case.

permit (OP, ...)

Permit the listed operators to be used when compiling code in thecompartment (in addition to any operators already permitted).

permit_only (OP, ...)

Permit only the listed operators to be used when compiling code inthe compartment (no other operators are permitted).

deny (OP, ...)

Deny the listed operators from being used when compiling code in thecompartment (other operators may still be permitted).

deny_only (OP, ...)

Deny only the listed operators from being used when compiling codein the compartment (all other operators will be permitted).

trap (OP, ...)

untrap (OP, ...)

The trap and untrap methods are synonyms for deny and permitrespectfully.

share (NAME, ...)

This shares the variable(s) in the argument list with the compartment.This is almost identical to exporting variables using the the Exporter(3) manpagemodule.

Each NAME must be the name of a variable, typically with the leadingtype identifier included. A bareword is treated as a function name.

Examples of legal names are `$foo' for a scalar, `@foo' for anarray, `%foo' for a hash, `&foo' or `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).

Each NAME is assumed to be in the calling package. See share_fromfor an alternative method (which share uses).

share_from (PACKAGE, ARRAYREF)

This method is similar to share() but allows you to explicitly name thepackage that symbols should be shared from. The symbol names (includingtype characters) are supplied as an array reference.

    $safe->share_from('main', [ '$foo', '%bar', 'func' ]);

varglob (VARNAME)

This returns a glob reference for the symbol table entry of VARNAME inthe package of the compartment. VARNAME must be the name of avariable 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 theroot method). The compartment's root package appears to be themain:: package to the code inside the compartment.

Any attempt by the code in STRING to use an operator which is not permittedby the compartment will cause an error (at run-time of the main programbut 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 willnot be executed. If such a trapped operation occurs or any othercompile-time or return error, then $@ is set to the error message, justas with an eval().

If there is no error, then the method returns the value of the lastexpression evaluated, or a return statement may be used, just as withsubroutines and eval(). The context (list or scalar) is determinedby the caller as usual.

This behaviour differs from the beta distribution of the Safe extensionwhere earlier versions of perl made it hard to mimic the returnbehaviour of the eval() command and the context was always scalar.

Some points to note:

If the entereval op is permitted then the code can use eval ``...'' to'hide' code which might use denied ops. This is not a major problemsince when the code tries to execute the eval it will fail because theopmask is still in effect. However this technique would allow clever,and possibly harmful, code to `probe' the boundaries of what ispossible.

Any string eval which is executed by code executing in a compartment,or by code called from code executing in a compartment, will be eval'din the namespace of the compartment. This is potentially a seriousproblem.

Consider a function foo() in package pkg compiled outside a compartmentbut shared with it. Assume the compartment has a root package called'Root'. If foo() contains an eval statement like eval `$foo = 1' then,normally, $pkg::foo will be set to 1. If foo() is called from thecompartment (by whatever means) then instead of setting $pkg::foo, theeval will actually set $Root::pkg::foo.

This can easily be demonstrated by using a module, such as the Socketmodule, which uses eval ``...'' as part of an AUTOLOAD function. You can'use' the module outside the compartment and share an (autoloaded)function with the compartment. If an autoload is triggered by code inthe compartment, or by any code anywhere that is called by any meansfrom the compartment, then the eval in the Socket module's AUTOLOADfunction happens in the namespace of the compartment. Any variablescreated or used by the eval'd code are now under the control ofthe code in the compartment.

A similar effect applies to all runtime symbol lookups in codecalled from a compartment but not compiled within it.

rdo (FILENAME)

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

root (NAMESPACE)

This method returns the name of the package that is the root of thecompartment's namespace.

Note that this behaviour differs from version 1.00 of the Safe modulewhere the root module could be used to change the namespace. Thatfunctionality has been withdrawn pending deeper consideration.

mask (MASK)

This is a get-or-set method for the compartment's operator mask.

With no MASK argument present, it returns the current operator mask ofthe compartment.

With the MASK argument present, it sets the operator mask for thecompartment (equivalent to calling the deny_only method).

Some Safety Issues

This section is currently just an outline of some of the things code ina compartment might do (intentionally or unintentionally) which canhave an effect outside the compartment.

Memory: Consuming all (or nearly all) available memory.
CPU: Causing infinite loops etc.
Snooping: Copying private information out of your system. Even something assimple as your user name is of value to others. Much useful informationcould be gleaned from your environment variables for example.
Signals: Causing signals (especially SIGFPE and SIGALARM) to affect your process.
Setting up a signal handler will need to be carefully consideredand controlled. What mask is in effect when a signal handlergets called? If a user can get an imported function to get anexception and call the user's signal handler, does that user'srestricted mask get re-instated before the handler is called?Does an imported handler get called with its original mask orthe user's one?
State Changes: Ops such as chdir obviously effect the process as a whole and not justthe code in the compartment. Ops such as rand and srand have a similarbut more subtle effect.

AUTHOR

Originally designed and implemented by Malcolm Beattie,mbeattieAATTsable.ox.ac.uk.

Reworked to use the Opcode module and other changes added by Tim Bunce<Tim.BunceAATTig.co.uk>.

This document was created byman2html,using the manual pages.