Return to Safe.pm CVS log

Up to [LON-CAPA] / loncom / xml

- silly typo

    1: package Safe;
    2: 
    3: use 5.003_11;
    4: use strict;
    5: 
    6: $Safe::VERSION = "2.09";
    7: 
    8: use Carp;
    9: 
   10: use Opcode 1.01, qw(
   11:     opset opset_to_ops opmask_add
   12:     empty_opset full_opset invert_opset verify_opset
   13:     opdesc opcodes opmask define_optag opset_to_hex
   14: );
   15: 
   16: *ops_to_opset = \&opset;   # Temporary alias for old Penguins
   17: 
   18: 
   19: my $default_root  = 0;
   20: my $default_share = ['*_']; #, '*main::'];
   21: 
   22: sub new {
   23:     my($class, $root, $mask) = @_;
   24:     my $obj = {};
   25:     bless $obj, $class;
   26: 
   27:     if (defined($root)) {
   28: 	croak "Can't use \"$root\" as root name"
   29: 	    if $root =~ /^main\b/ or $root !~ /^\w[:\w]*$/;
   30: 	$obj->{Root}  = $root;
   31: 	$obj->{Erase} = 0;
   32:     }
   33:     else {
   34: 	$obj->{Root}  = "Safe::Root".$default_root++;
   35: 	$obj->{Erase} = 1;
   36:     }
   37: 
   38:     # use permit/deny methods instead till interface issues resolved
   39:     # XXX perhaps new Safe 'Root', mask => $mask, foo => bar, ...;
   40:     croak "Mask parameter to new no longer supported" if defined $mask;
   41:     $obj->permit_only(':default');
   42: 
   43:     # We must share $_ and @_ with the compartment or else ops such
   44:     # as split, length and so on won't default to $_ properly, nor
   45:     # will passing argument to subroutines work (via @_). In fact,
   46:     # for reasons I don't completely understand, we need to share
   47:     # the whole glob *_ rather than $_ and @_ separately, otherwise
   48:     # @_ in non default packages within the compartment don't work.
   49:     $obj->share_from('main', $default_share);
   50:     Opcode::_safe_pkg_prep($obj->{Root}) if($Opcode::VERSION > 1.04);
   51:     return $obj;
   52: }
   53: 
   54: sub DESTROY {
   55:     my $obj = shift;
   56:     $obj->erase('DESTROY') if $obj->{Erase};
   57: }
   58: 
   59: sub erase {
   60:     my ($obj, $action) = @_;
   61:     my $pkg = $obj->root();
   62:     my ($stem, $leaf);
   63: 
   64:     no strict 'refs';
   65:     $pkg = "main::$pkg\::";	# expand to full symbol table name
   66:     ($stem, $leaf) = $pkg =~ m/(.*::)(\w+::)$/;
   67: 
   68:     # The 'my $foo' is needed! Without it you get an
   69:     # 'Attempt to free unreferenced scalar' warning!
   70:     my $stem_symtab = *{$stem}{HASH};
   71: 
   72:     #warn "erase($pkg) stem=$stem, leaf=$leaf";
   73:     #warn " stem_symtab hash ".scalar(%$stem_symtab)."\n";
   74: 	# ", join(', ', %$stem_symtab),"\n";
   75: 
   76: #    delete $stem_symtab->{$leaf};
   77: 
   78:     my $leaf_glob   = $stem_symtab->{$leaf};
   79:     my $leaf_symtab = *{$leaf_glob}{HASH};
   80: #    warn " leaf_symtab ", join(', ', %$leaf_symtab),"\n";
   81:     %$leaf_symtab = ();
   82:     #delete $leaf_symtab->{'__ANON__'};
   83:     #delete $leaf_symtab->{'foo'};
   84:     #delete $leaf_symtab->{'main::'};
   85: #    my $foo = undef ${"$stem\::"}{"$leaf\::"};
   86: 
   87:     if ($action and $action eq 'DESTROY') {
   88:         delete $stem_symtab->{$leaf};
   89:     } else {
   90:         $obj->share_from('main', $default_share);
   91:     }
   92:     1;
   93: }
   94: 
   95: 
   96: sub reinit {
   97:     my $obj= shift;
   98:     $obj->erase;
   99:     $obj->share_redo;
  100: }
  101: 
  102: sub root {
  103:     my $obj = shift;
  104:     croak("Safe root method now read-only") if @_;
  105:     return $obj->{Root};
  106: }
  107: 
  108: 
  109: sub mask {
  110:     my $obj = shift;
  111:     return $obj->{Mask} unless @_;
  112:     $obj->deny_only(@_);
  113: }
  114: 
  115: # v1 compatibility methods
  116: sub trap   { shift->deny(@_)   }
  117: sub untrap { shift->permit(@_) }
  118: 
  119: sub deny {
  120:     my $obj = shift;
  121:     $obj->{Mask} |= opset(@_);
  122: }
  123: sub deny_only {
  124:     my $obj = shift;
  125:     $obj->{Mask} = opset(@_);
  126: }
  127: 
  128: sub permit {
  129:     my $obj = shift;
  130:     # XXX needs testing
  131:     $obj->{Mask} &= invert_opset opset(@_);
  132: }
  133: sub permit_only {
  134:     my $obj = shift;
  135:     $obj->{Mask} = invert_opset opset(@_);
  136: }
  137: 
  138: 
  139: sub dump_mask {
  140:     my $obj = shift;
  141:     print opset_to_hex($obj->{Mask}),"\n";
  142: }
  143: 
  144: 
  145: 
  146: sub share {
  147:     my($obj, @vars) = @_;
  148:     $obj->share_from(scalar(caller), \@vars);
  149: }
  150: 
  151: sub share_from {
  152:     my $obj = shift;
  153:     my $pkg = shift;
  154:     my $vars = shift;
  155:     my $no_record = shift || 0;
  156:     my $root = $obj->root();
  157:     croak("vars not an array ref") unless ref $vars eq 'ARRAY';
  158:     no strict 'refs';
  159:     # Check that 'from' package actually exists
  160:     croak("Package \"$pkg\" does not exist")
  161: 	unless keys %{"$pkg\::"};
  162:     my $arg;
  163:     foreach $arg (@$vars) {
  164: 	# catch some $safe->share($var) errors:
  165: 	croak("'$arg' not a valid symbol table name")
  166: 	    unless $arg =~ /^[\$\@%*&]?\w[\w:]*$/
  167: 	    	or $arg =~ /^\$\W$/;
  168: 	my ($var, $type);
  169: 	$type = $1 if ($var = $arg) =~ s/^(\W)//;
  170: 	# warn "share_from $pkg $type $var";
  171: 	*{$root."::$var"} = (!$type)       ? \&{$pkg."::$var"}
  172: 			  : ($type eq '&') ? \&{$pkg."::$var"}
  173: 			  : ($type eq '$') ? \${$pkg."::$var"}
  174: 			  : ($type eq '@') ? \@{$pkg."::$var"}
  175: 			  : ($type eq '%') ? \%{$pkg."::$var"}
  176: 			  : ($type eq '*') ?  *{$pkg."::$var"}
  177: 			  : croak(qq(Can't share "$type$var" of unknown type));
  178:     }
  179:     $obj->share_record($pkg, $vars) unless $no_record or !$vars;
  180: }
  181: 
  182: sub share_record {
  183:     my $obj = shift;
  184:     my $pkg = shift;
  185:     my $vars = shift;
  186:     my $shares = \%{$obj->{Shares} ||= {}};
  187:     # Record shares using keys of $obj->{Shares}. See reinit.
  188:     @{$shares}{@$vars} = ($pkg) x @$vars if @$vars;
  189: }
  190: sub share_redo {
  191:     my $obj = shift;
  192:     my $shares = \%{$obj->{Shares} ||= {}};
  193:     my($var, $pkg);
  194:     while(($var, $pkg) = each %$shares) {
  195: 	# warn "share_redo $pkg\:: $var";
  196: 	$obj->share_from($pkg,  [ $var ], 1);
  197:     }
  198: }
  199: sub share_forget {
  200:     delete shift->{Shares};
  201: }
  202: 
  203: sub varglob {
  204:     my ($obj, $var) = @_;
  205:     no strict 'refs';
  206:     return *{$obj->root()."::$var"};
  207: }
  208: 
  209: 
  210: sub reval {
  211:     undef($Safe::evalsub);
  212:     {
  213: 	my ($obj, $expr, $strict) = @_;
  214: 	my $root = $obj->{Root};
  215: 
  216: 	# Create anon sub ref in root of compartment.
  217: 	# Uses a closure (on $expr) to pass in the code to be executed.
  218: 	# (eval on one line to keep line numbers as expected by caller)
  219: 	my $evalcode = sprintf('package %s; sub { @_ = (\'\'); eval $expr; }', $obj->{Root});
  220: 	
  221: 	if ($strict) { use strict; $Safe::evalsub = eval $evalcode; }
  222: 	else         {  no strict; $Safe::evalsub = eval $evalcode; }
  223:     }
  224:     return Opcode::_safe_call_sv($_[0]->{Root}, $_[0]->{Mask}, $Safe::evalsub);
  225: }
  226: 
  227: sub rdo {
  228:     my ($obj, $file) = @_;
  229:     my $root = $obj->{Root};
  230: 
  231:     my $evalsub = eval
  232: 	    sprintf('package %s; sub { @_ = (\'\'); do $file }', $root);
  233:     return Opcode::_safe_call_sv($root, $obj->{Mask}, $evalsub);
  234: }
  235: 
  236: 
  237: 1;
  238: 
  239: __END__
  240: 
  241: =head1 NAME
  242: 
  243: Safe - Compile and execute code in restricted compartments
  244: 
  245: =head1 SYNOPSIS
  246: 
  247:   use Safe;
  248: 
  249:   $compartment = new Safe;
  250: 
  251:   $compartment->permit(qw(time sort :browse));
  252: 
  253:   $result = $compartment->reval($unsafe_code);
  254: 
  255: =head1 DESCRIPTION
  256: 
  257: The Safe extension module allows the creation of compartments
  258: in which perl code can be evaluated. Each compartment has
  259: 
  260: =over 8
  261: 
  262: =item a new namespace
  263: 
  264: The "root" of the namespace (i.e. "main::") is changed to a
  265: different package and code evaluated in the compartment cannot
  266: refer to variables outside this namespace, even with run-time
  267: glob lookups and other tricks.
  268: 
  269: Code which is compiled outside the compartment can choose to place
  270: variables into (or I<share> variables with) the compartment's namespace
  271: and only that data will be visible to code evaluated in the
  272: compartment.
  273: 
  274: By default, the only variables shared with compartments are the
  275: "underscore" variables $_ and @_ (and, technically, the less frequently
  276: used %_, the _ filehandle and so on). This is because otherwise perl
  277: operators which default to $_ will not work and neither will the
  278: assignment of arguments to @_ on subroutine entry.
  279: 
  280: =item an operator mask
  281: 
  282: Each compartment has an associated "operator mask". Recall that
  283: perl code is compiled into an internal format before execution.
  284: Evaluating perl code (e.g. via "eval" or "do 'file'") causes
  285: the code to be compiled into an internal format and then,
  286: provided there was no error in the compilation, executed.
  287: Code evaluated in a compartment compiles subject to the
  288: compartment's operator mask. Attempting to evaluate code in a
  289: compartment which contains a masked operator will cause the
  290: compilation to fail with an error. The code will not be executed.
  291: 
  292: The default operator mask for a newly created compartment is
  293: the ':default' optag.
  294: 
  295: It is important that you read the Opcode(3) module documentation
  296: for more information, especially for detailed definitions of opnames,
  297: optags and opsets.
  298: 
  299: Since it is only at the compilation stage that the operator mask
  300: applies, controlled access to potentially unsafe operations can
  301: be achieved by having a handle to a wrapper subroutine (written
  302: outside the compartment) placed into the compartment. For example,
  303: 
  304:     $cpt = new Safe;
  305:     sub wrapper {
  306:         # vet arguments and perform potentially unsafe operations
  307:     }
  308:     $cpt->share('&wrapper');
  309: 
  310: =back
  311: 
  312: 
  313: =head1 WARNING
  314: 
  315: The authors make B<no warranty>, implied or otherwise, about the
  316: suitability of this software for safety or security purposes.
  317: 
  318: The authors shall not in any case be liable for special, incidental,
  319: consequential, indirect or other similar damages arising from the use
  320: of this software.
  321: 
  322: Your mileage will vary. If in any doubt B<do not use it>.
  323: 
  324: 
  325: =head2 RECENT CHANGES
  326: 
  327: The interface to the Safe module has changed quite dramatically since
  328: version 1 (as supplied with Perl5.002). Study these pages carefully if
  329: you have code written to use Safe version 1 because you will need to
  330: makes changes.
  331: 
  332: 
  333: =head2 Methods in class Safe
  334: 
  335: To create a new compartment, use
  336: 
  337:     $cpt = new Safe;
  338: 
  339: Optional argument is (NAMESPACE), where NAMESPACE is the root namespace
  340: to use for the compartment (defaults to "Safe::Root0", incremented for
  341: each new compartment).
  342: 
  343: Note that version 1.00 of the Safe module supported a second optional
  344: parameter, MASK.  That functionality has been withdrawn pending deeper
  345: consideration. Use the permit and deny methods described below.
  346: 
  347: The following methods can then be used on the compartment
  348: object returned by the above constructor. The object argument
  349: is implicit in each case.
  350: 
  351: 
  352: =over 8
  353: 
  354: =item permit (OP, ...)
  355: 
  356: Permit the listed operators to be used when compiling code in the
  357: compartment (in I<addition> to any operators already permitted).
  358: 
  359: =item permit_only (OP, ...)
  360: 
  361: Permit I<only> the listed operators to be used when compiling code in
  362: the compartment (I<no> other operators are permitted).
  363: 
  364: =item deny (OP, ...)
  365: 
  366: Deny the listed operators from being used when compiling code in the
  367: compartment (other operators may still be permitted).
  368: 
  369: =item deny_only (OP, ...)
  370: 
  371: Deny I<only> the listed operators from being used when compiling code
  372: in the compartment (I<all> other operators will be permitted).
  373: 
  374: =item trap (OP, ...)
  375: 
  376: =item untrap (OP, ...)
  377: 
  378: The trap and untrap methods are synonyms for deny and permit
  379: respectfully.
  380: 
  381: =item share (NAME, ...)
  382: 
  383: This shares the variable(s) in the argument list with the compartment.
  384: This is almost identical to exporting variables using the L<Exporter>
  385: module.
  386: 
  387: Each NAME must be the B<name> of a non-lexical variable, typically
  388: with the leading type identifier included. A bareword is treated as a
  389: function name.
  390: 
  391: Examples of legal names are '$foo' for a scalar, '@foo' for an
  392: array, '%foo' for a hash, '&foo' or 'foo' for a subroutine and '*foo'
  393: for a glob (i.e.  all symbol table entries associated with "foo",
  394: including scalar, array, hash, sub and filehandle).
  395: 
  396: Each NAME is assumed to be in the calling package. See share_from
  397: for an alternative method (which share uses).
  398: 
  399: =item share_from (PACKAGE, ARRAYREF)
  400: 
  401: This method is similar to share() but allows you to explicitly name the
  402: package that symbols should be shared from. The symbol names (including
  403: type characters) are supplied as an array reference.
  404: 
  405:     $safe->share_from('main', [ '$foo', '%bar', 'func' ]);
  406: 
  407: 
  408: =item varglob (VARNAME)
  409: 
  410: This returns a glob reference for the symbol table entry of VARNAME in
  411: the package of the compartment. VARNAME must be the B<name> of a
  412: variable without any leading type marker. For example,
  413: 
  414:     $cpt = new Safe 'Root';
  415:     $Root::foo = "Hello world";
  416:     # Equivalent version which doesn't need to know $cpt's package name:
  417:     ${$cpt->varglob('foo')} = "Hello world";
  418: 
  419: 
  420: =item reval (STRING)
  421: 
  422: This evaluates STRING as perl code inside the compartment.
  423: 
  424: The code can only see the compartment's namespace (as returned by the
  425: B<root> method). The compartment's root package appears to be the
  426: C<main::> package to the code inside the compartment.
  427: 
  428: Any attempt by the code in STRING to use an operator which is not permitted
  429: by the compartment will cause an error (at run-time of the main program
  430: but at compile-time for the code in STRING).  The error is of the form
  431: "'%s' trapped by operation mask...".
  432: 
  433: If an operation is trapped in this way, then the code in STRING will
  434: not be executed. If such a trapped operation occurs or any other
  435: compile-time or return error, then $@ is set to the error message, just
  436: as with an eval().
  437: 
  438: If there is no error, then the method returns the value of the last
  439: expression evaluated, or a return statement may be used, just as with
  440: subroutines and B<eval()>. The context (list or scalar) is determined
  441: by the caller as usual.
  442: 
  443: This behaviour differs from the beta distribution of the Safe extension
  444: where earlier versions of perl made it hard to mimic the return
  445: behaviour of the eval() command and the context was always scalar.
  446: 
  447: Some points to note:
  448: 
  449: If the entereval op is permitted then the code can use eval "..." to
  450: 'hide' code which might use denied ops. This is not a major problem
  451: since when the code tries to execute the eval it will fail because the
  452: opmask is still in effect. However this technique would allow clever,
  453: and possibly harmful, code to 'probe' the boundaries of what is
  454: possible.
  455: 
  456: Any string eval which is executed by code executing in a compartment,
  457: or by code called from code executing in a compartment, will be eval'd
  458: in the namespace of the compartment. This is potentially a serious
  459: problem.
  460: 
  461: Consider a function foo() in package pkg compiled outside a compartment
  462: but shared with it. Assume the compartment has a root package called
  463: 'Root'. If foo() contains an eval statement like eval '$foo = 1' then,
  464: normally, $pkg::foo will be set to 1.  If foo() is called from the
  465: compartment (by whatever means) then instead of setting $pkg::foo, the
  466: eval will actually set $Root::pkg::foo.
  467: 
  468: This can easily be demonstrated by using a module, such as the Socket
  469: module, which uses eval "..." as part of an AUTOLOAD function. You can
  470: 'use' the module outside the compartment and share an (autoloaded)
  471: function with the compartment. If an autoload is triggered by code in
  472: the compartment, or by any code anywhere that is called by any means
  473: from the compartment, then the eval in the Socket module's AUTOLOAD
  474: function happens in the namespace of the compartment. Any variables
  475: created or used by the eval'd code are now under the control of
  476: the code in the compartment.
  477: 
  478: A similar effect applies to I<all> runtime symbol lookups in code
  479: called from a compartment but not compiled within it.
  480: 
  481: 
  482: 
  483: =item rdo (FILENAME)
  484: 
  485: This evaluates the contents of file FILENAME inside the compartment.
  486: See above documentation on the B<reval> method for further details.
  487: 
  488: =item root (NAMESPACE)
  489: 
  490: This method returns the name of the package that is the root of the
  491: compartment's namespace.
  492: 
  493: Note that this behaviour differs from version 1.00 of the Safe module
  494: where the root module could be used to change the namespace. That
  495: functionality has been withdrawn pending deeper consideration.
  496: 
  497: =item mask (MASK)
  498: 
  499: This is a get-or-set method for the compartment's operator mask.
  500: 
  501: With no MASK argument present, it returns the current operator mask of
  502: the compartment.
  503: 
  504: With the MASK argument present, it sets the operator mask for the
  505: compartment (equivalent to calling the deny_only method).
  506: 
  507: =back
  508: 
  509: 
  510: =head2 Some Safety Issues
  511: 
  512: This section is currently just an outline of some of the things code in
  513: a compartment might do (intentionally or unintentionally) which can
  514: have an effect outside the compartment.
  515: 
  516: =over 8
  517: 
  518: =item Memory
  519: 
  520: Consuming all (or nearly all) available memory.
  521: 
  522: =item CPU
  523: 
  524: Causing infinite loops etc.
  525: 
  526: =item Snooping
  527: 
  528: Copying private information out of your system. Even something as
  529: simple as your user name is of value to others. Much useful information
  530: could be gleaned from your environment variables for example.
  531: 
  532: =item Signals
  533: 
  534: Causing signals (especially SIGFPE and SIGALARM) to affect your process.
  535: 
  536: Setting up a signal handler will need to be carefully considered
  537: and controlled.  What mask is in effect when a signal handler
  538: gets called?  If a user can get an imported function to get an
  539: exception and call the user's signal handler, does that user's
  540: restricted mask get re-instated before the handler is called?
  541: Does an imported handler get called with its original mask or
  542: the user's one?
  543: 
  544: =item State Changes
  545: 
  546: Ops such as chdir obviously effect the process as a whole and not just
  547: the code in the compartment. Ops such as rand and srand have a similar
  548: but more subtle effect.
  549: 
  550: =back
  551: 
  552: =head2 AUTHOR
  553: 
  554: Originally designed and implemented by Malcolm Beattie,
  555: mbeattie@sable.ox.ac.uk.
  556: 
  557: Reworked to use the Opcode module and other changes added by Tim Bunce
  558: E<lt>F<Tim.Bunce@ig.co.uk>E<gt>.
  559: 
  560: =cut
  561: