1Safe(3pm) Perl Programmers Reference Guide Safe(3pm)
2
6 Safe - Compile and execute code in restricted compartments
7
9 use Safe;
10 $compartment = new Safe;
12 $compartment->permit(qw(time sort :browse));
14 $result = $compartment->reval($unsafe_code);
16
18 The Safe extension module allows the creation of compartments in which
19 perl code can be evaluated. Each compartment has
20 a new namespace
22 The "root" of the namespace (i.e. "main::") is changed to a
23 different package and code evaluated in the compartment cannot
24 refer to variables outside this namespace, even with run-time
25 glob lookups and other tricks.
26 Code which is compiled outside the compartment can choose to
28 place variables into (or share variables with) the compart‐
29 ment's namespace and only that data will be visible to code
30 evaluated in the compartment.
31 By default, the only variables shared with compartments are the
33 "underscore" variables $_ and @_ (and, technically, the less
34 frequently used %_, the _ filehandle and so on). This is
35 because otherwise perl operators which default to $_ will not
36 work and neither will the assignment of arguments to @_ on sub‐
37 routine entry.
38 an operator mask
40 Each compartment has an associated "operator mask". Recall that
41 perl code is compiled into an internal format before execution.
42 Evaluating perl code (e.g. via "eval" or "do 'file'") causes
43 the code to be compiled into an internal format and then, pro‐
44 vided there was no error in the compilation, executed. Code
45 evaluated in a compartment compiles subject to the compart‐
46 ment's operator mask. Attempting to evaluate code in a compart‐
47 ment which contains a masked operator will cause the compila‐
48 tion to fail with an error. The code will not be executed.
49 The default operator mask for a newly created compartment is
51 the ':default' optag.
52 It is important that you read the Opcode(3) module documenta‐
54 tion for more information, especially for detailed definitions
55 of opnames, optags and opsets.
56 Since it is only at the compilation stage that the operator
58 mask applies, controlled access to potentially unsafe opera‐
59 tions can be achieved by having a handle to a wrapper subrou‐
60 tine (written outside the compartment) placed into the compart‐
61 ment. For example,
62 $cpt = new Safe;
64 sub wrapper {
65 # vet arguments and perform potentially unsafe operations
66 }
67 $cpt->share('&wrapper');
68
70 The authors make no warranty, implied or otherwise, about the suitabil‐
71 ity of this software for safety or security purposes.
72 The authors shall not in any case be liable for special, incidental,
74 consequential, indirect or other similar damages arising from the use
75 of this software.
76 Your mileage will vary. If in any doubt do not use it.
78 RECENT CHANGES
80 The interface to the Safe module has changed quite dramatically since
82 version 1 (as supplied with Perl5.002). Study these pages carefully if
83 you have code written to use Safe version 1 because you will need to
84 makes changes.
85 Methods in class Safe
87 To create a new compartment, use
89 $cpt = new Safe;
91 Optional argument is (NAMESPACE), where NAMESPACE is the root namespace
93 to use for the compartment (defaults to "Safe::Root0", incremented for
94 each new compartment).
95 Note that version 1.00 of the Safe module supported a second optional
97 parameter, MASK. That functionality has been withdrawn pending deeper
98 consideration. Use the permit and deny methods described below.
99 The following methods can then be used on the compartment object
101 returned by the above constructor. The object argument is implicit in
102 each case.
103 permit (OP, ...)
105 Permit the listed operators to be used when compiling code in
106 the compartment (in addition to any operators already permit‐
107 ted).
108 You can list opcodes by names, or use a tag name; see "Prede‐
110 fined Opcode Tags" in Opcode.
111 permit_only (OP, ...)
113 Permit only the listed operators to be used when compiling code
114 in the compartment (no other operators are permitted).
115 deny (OP, ...)
117 Deny the listed operators from being used when compiling code
118 in the compartment (other operators may still be permitted).
119 deny_only (OP, ...)
121 Deny only the listed operators from being used when compiling
122 code in the compartment (all other operators will be permit‐
123 ted).
124 trap (OP, ...)
126 untrap (OP, ...)
127 The trap and untrap methods are synonyms for deny and permit
128 respectfully.
129 share (NAME, ...)
131 This shares the variable(s) in the argument list with the com‐
132 partment. This is almost identical to exporting variables
133 using the Exporter module.
134 Each NAME must be the name of a non-lexical variable, typically
136 with the leading type identifier included. A bareword is
137 treated as a function name.
138 Examples of legal names are '$foo' for a scalar, '@foo' for an
140 array, '%foo' for a hash, '&foo' or 'foo' for a subroutine and
141 '*foo' for a glob (i.e. all symbol table entries associated
142 with "foo", including scalar, array, hash, sub and filehandle).
143 Each NAME is assumed to be in the calling package. See
145 share_from for an alternative method (which share uses).
146 share_from (PACKAGE, ARRAYREF)
148 This method is similar to share() but allows you to explicitly
149 name the package that symbols should be shared from. The symbol
150 names (including type characters) are supplied as an array ref‐
151 erence.
152 $safe->share_from('main', [ '$foo', '%bar', 'func' ]);
154 varglob (VARNAME)
156 This returns a glob reference for the symbol table entry of
157 VARNAME in the package of the compartment. VARNAME must be the
158 name of a variable without any leading type marker. For exam‐
159 ple,
160 $cpt = new Safe 'Root';
162 $Root::foo = "Hello world";
163 # Equivalent version which doesn't need to know $cpt's package name:
164 ${$cpt->varglob('foo')} = "Hello world";
165 reval (STRING)
167 This evaluates STRING as perl code inside the compartment.
168 The code can only see the compartment's namespace (as returned
170 by the root method). The compartment's root package appears to
171 be the "main::" package to the code inside the compartment.
172 Any attempt by the code in STRING to use an operator which is
174 not permitted by the compartment will cause an error (at run-
175 time of the main program but at compile-time for the code in
176 STRING). The error is of the form "'%s' trapped by operation
177 mask...".
178 If an operation is trapped in this way, then the code in STRING
180 will not be executed. If such a trapped operation occurs or any
181 other compile-time or return error, then $@ is set to the error
182 message, just as with an eval().
183 If there is no error, then the method returns the value of the
185 last expression evaluated, or a return statement may be used,
186 just as with subroutines and eval(). The context (list or
187 scalar) is determined by the caller as usual.
188 This behaviour differs from the beta distribution of the Safe
190 extension where earlier versions of perl made it hard to mimic
191 the return behaviour of the eval() command and the context was
192 always scalar.
193 Some points to note:
195 If the entereval op is permitted then the code can use eval
197 "..." to 'hide' code which might use denied ops. This is not a
198 major problem since when the code tries to execute the eval it
199 will fail because the opmask is still in effect. However this
200 technique would allow clever, and possibly harmful, code to
201 'probe' the boundaries of what is possible.
202 Any string eval which is executed by code executing in a com‐
204 partment, or by code called from code executing in a compart‐
205 ment, will be eval'd in the namespace of the compartment. This
206 is potentially a serious problem.
207 Consider a function foo() in package pkg compiled outside a
209 compartment but shared with it. Assume the compartment has a
210 root package called 'Root'. If foo() contains an eval statement
211 like eval '$foo = 1' then, normally, $pkg::foo will be set to
212 1. If foo() is called from the compartment (by whatever means)
213 then instead of setting $pkg::foo, the eval will actually set
214 $Root::pkg::foo.
215 This can easily be demonstrated by using a module, such as the
217 Socket module, which uses eval "..." as part of an AUTOLOAD
218 function. You can 'use' the module outside the compartment and
219 share an (autoloaded) function with the compartment. If an
220 autoload is triggered by code in the compartment, or by any
221 code anywhere that is called by any means from the compartment,
222 then the eval in the Socket module's AUTOLOAD function happens
223 in the namespace of the compartment. Any variables created or
224 used by the eval'd code are now under the control of the code
225 in the compartment.
226 A similar effect applies to all runtime symbol lookups in code
228 called from a compartment but not compiled within it.
229 rdo (FILENAME)
231 This evaluates the contents of file FILENAME inside the com‐
232 partment. See above documentation on the reval method for fur‐
233 ther details.
234 root (NAMESPACE)
236 This method returns the name of the package that is the root of
237 the compartment's namespace.
238 Note that this behaviour differs from version 1.00 of the Safe
240 module where the root module could be used to change the names‐
241 pace. That functionality has been withdrawn pending deeper con‐
242 sideration.
243 mask (MASK)
245 This is a get-or-set method for the compartment's operator
246 mask.
247 With no MASK argument present, it returns the current operator
249 mask of the compartment.
250 With the MASK argument present, it sets the operator mask for
252 the compartment (equivalent to calling the deny_only method).
253 Some Safety Issues
255 This section is currently just an outline of some of the things code in
257 a compartment might do (intentionally or unintentionally) which can
258 have an effect outside the compartment.
259 Memory Consuming all (or nearly all) available memory.
261 CPU Causing infinite loops etc.
263 Snooping
265 Copying private information out of your system. Even something
266 as simple as your user name is of value to others. Much useful
267 information could be gleaned from your environment variables
268 for example.
269 Signals Causing signals (especially SIGFPE and SIGALARM) to affect your
271 process.
272 Setting up a signal handler will need to be carefully consid‐
274 ered and controlled. What mask is in effect when a signal han‐
275 dler gets called? If a user can get an imported function to
276 get an exception and call the user's signal handler, does that
277 user's restricted mask get re-instated before the handler is
278 called? Does an imported handler get called with its original
279 mask or the user's one?
280 State Changes
282 Ops such as chdir obviously effect the process as a whole and
283 not just the code in the compartment. Ops such as rand and
284 srand have a similar but more subtle effect.
285 AUTHOR
287 Originally designed and implemented by Malcolm Beattie, mbeat‐
289 tie@sable.ox.ac.uk.
290 Reworked to use the Opcode module and other changes added by Tim Bunce
292 <Tim.Bunce@ig.co.uk>.
293perl v5.8.8 2001-09-21 Safe(3pm)