.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Safe::Hole 3pm" .TH Safe::Hole 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Safe::Hole \- make a hole to the original main compartment in the Safe compartment .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 10 \& use Safe; \& use Safe::Hole; \& $cpt = new Safe; \& $hole = new Safe::Hole {}; \& sub test { Test\->test; } \& $Testobj = new Test; \& # $cpt\->share(\*(Aq&test\*(Aq); # alternate as next line \& $hole\->wrap(\e&test, $cpt, \*(Aq&test\*(Aq); \& # ${$cpt\->varglob(\*(AqTestobj\*(Aq)} = $Testobj; # alternate as next line \& $hole\->wrap($Testobj, $cpt, \*(Aq$Testobj\*(Aq); \& $cpt\->reval(\*(Aqtest; $Testobj\->test;\*(Aq); \& print $@ if $@; \& package Test; \& sub new { bless {},shift(); } \& sub test { my $self = shift; $self\->test2; } \& sub test2 { print "Test\->test2 called\en"; } .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" .Vb 7 \& We can call outside defined subroutines from the Safe compartment \&using share(), or can call methods through the object that is copied \&into the Safe compartment using varglob(). But that subroutines or \&methods are executed in the Safe compartment too, so they cannot call \&another subroutines that are dinamically qualified with the package \&name such as class methods nor can they compile code that uses opcodes \&that are forbidden within the compartment. \& \& Through Safe::Hole, we can execute outside defined subroutines in the \&original main compartment from the Safe compartment. \& \& Note that if a subroutine called through Safe::Hole::call does a \&Carp::croak() it will report the error as having occured within \&Safe::Hole. This can be avoided by including Safe::Hole::User in the \&@ISA for the package containing the subroutine. .Ve .SS Methods .IX Subsection "Methods" .IP "new [NAMESPACE]" 4 .IX Item "new [NAMESPACE]" Class method. Backward compatible constructor. NAMESPACE is the alternate root namespace that makes the compartment in which \fBcall()\fR method execute the subroutine. Default of NAMESPACE means the current 'main'. This emulates the behaviour of Safe\-Hole\-0.08 and earlier. .IP "new \e%arguments" 4 .IX Item "new %arguments" Class method. Constructor. The constructor is called with a hash reference providing the constructor arguments. The argument ROOT specifies the alternate root namespace for the object. If the ROOT argument is not specified then Safe::Hole object will attempt restore as much as it can of the environment in which it was constrtucted. This includes the opcode mask, \f(CW%INC\fR and \f(CW@INC\fR. If a root namespace is specified then it would not make sense to restore the \f(CW%INC\fR and \f(CW@INC\fR from main:: so this is not done. Also if a root namespace is given the opcode mask is not restored either. .ie n .IP "call $coderef [,@args]" 4 .el .IP "call \f(CW$coderef\fR [,@args]" 4 .IX Item "call $coderef [,@args]" Object method. Call the subroutine refered by \f(CW$coderef\fR in the compartment that is specified with constructor new. \f(CW@args\fR are passed as the arguments to the called \f(CW$coderef\fR. Note that the arguments are not currently passed by reference although this may change in a future version. .ie n .IP "wrap $ref [,$cpt ,$name]" 4 .el .IP "wrap \f(CW$ref\fR [,$cpt ,$name]" 4 .IX Item "wrap $ref [,$cpt ,$name]" Object method. If \f(CW$ref\fR is a code reference, this method returns the anonymous subroutine reference that calls \f(CW$ref\fR using \fBcall()\fR method of Safe::Hole (see above). If \f(CW$ref\fR is a class object, this method makes a wrapper class of that object and returns a new object of the wrapper class. Through the wrapper class, all original class methods called using \fBcall()\fR method of Safe::Hole. If \f(CW$cpt\fR as Safe object and \f(CW$name\fR as subroutine or scalar name specified, this method works like \fBshare()\fR method of Safe. When \f(CW$ref\fR is a code reference \&\f(CW$name\fR must like '&subroutine'. When \f(CW$ref\fR is a object \f(CW$name\fR must like '$var'. Name \f(CW$name\fR may not be same as referent of \f(CW$ref\fR. For example: \f(CW$hole\fR\->wrap(\e&foo, \f(CW$cpt\fR, '&bar'); \f(CW$hole\fR\->wrap(sub{...}, \f(CW$cpt\fR, '&foo'); \f(CW$hole\fR\->wrap($objfoo, \f(CW$cpt\fR, '$objbar'); .IP root 4 .IX Item "root" Object method. Return the namespace that is specified with constructor \fBnew()\fR. If no namespace was then \fBroot()\fR returns 'main'. .SS Warning .IX Subsection "Warning" You MUST NOT share the Safe::Hole object with the Safe compartment. If you do it the Safe compartment is NOT safe. .PP This module provides a means to go from a state where an opcode is denied back to a state where it is not. Reasonable care has been taken to ensure that programs cannot simply manipulate the internals to the Safe::Hole object to reduce the opmask in effect. However there may still be a way that the authors have not considered. In particular it relies on the fact that a Perl program cannot change stuff inside the magic on a Perl variable. If you install a module that allows a Perl program to fiddle inside the magic then this assuption breaks down. One would hope that any system that was running un-trusted code would not have such a module installed. .SH AUTHORS .IX Header "AUTHORS" Sey Nakajima (Initial version) .PP Brian McCauley (Maintenance) .PP Todd Rinaldo (Maintenance) .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBSafe\fR\|(3).