Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/librexec.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents ae75d4a1f5dd
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4259
dbb76095adee Added bastion and (dummy) rexec docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard Module \sectcode{rexec}}
dbb76095adee Added bastion and (dummy) rexec docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{rexec}
dbb76095adee Added bastion and (dummy) rexec docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \renewcommand{\indexsubitem}{(in module rexec)}
dbb76095adee Added bastion and (dummy) rexec docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
4
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
5 This module contains the \code{RExec} class, which supports
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
6 \code{r_exec()}, \code{r_eval()}, \code{r_execfile()}, and
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
7 \code{r_import()} methods, which are restricted versions of the standard
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
8 Python functions \code{exec()}, \code{eval()}, \code{execfile()}, and
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
9 the \code{import} statement.
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
10 Code executed in this restricted environment will
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
11 only have access to modules and functions that are deemed safe; you
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
12 can subclass \code{RExec} to add or remove capabilities as desired.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
13
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
14 \emph{Note:} The \code{RExec} class can prevent code from performing
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
15 unsafe operations like reading or writing disk files, or using TCP/IP
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
16 sockets. However, it does not protect against code using extremely
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
17 large amounts of memory or CPU time.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
18
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
19 \begin{funcdesc}{RExec}{\optional{hooks\optional{\, verbose}}}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
20 Returns an instance of the \code{RExec} class.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
21
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
22 \var{hooks} is an instance of the \code{RHooks} class or a subclass of it.
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
23 If it is omitted or \code{None}, the default \code{RHooks} class is
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
24 instantiated.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
25 Whenever the RExec module searches for a module (even a built-in one)
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
26 or reads a module's code, it doesn't actually go out to the file
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
27 system itself. Rather, it calls methods of an RHooks instance that
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
28 was passed to or created by its constructor. (Actually, the RExec
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
29 object doesn't make these calls---they are made by a module loader
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
30 object that's part of the RExec object. This allows another level of
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
31 flexibility, e.g. using packages.)
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
32
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
33 By providing an alternate RHooks object, we can control the
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
34 file system accesses made to import a module, without changing the
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
35 actual algorithm that controls the order in which those accesses are
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
36 made. For instance, we could substitute an RHooks object that passes
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
37 all filesystem requests to a file server elsewhere, via some RPC
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
38 mechanism such as ILU. Grail's applet loader uses this to support
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
39 importing applets from a URL for a directory.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
40
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
41 If \var{verbose} is true, additional debugging output may be sent to
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
42 standard output.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
43 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
44
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
45 The RExec class has the following class attributes, which are used by the
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
46 \code{__init__} method. Changing them on an existing instance won't
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
47 have any effect; instead, create a subclass of \code{RExec} and assign
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
48 them new values in the class definition. Instances of the new class
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
49 will then use those new values. All these attributes are tuples of
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
50 strings.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
51
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
52 \renewcommand{\indexsubitem}{(RExec object attribute)}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
53 \begin{datadesc}{nok_builtin_names}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
54 Contains the names of built-in functions which will \emph{not} be
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
55 available to programs running in the restricted environment. The
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
56 value for \code{RExec} is \code{('open',} \code{'reload',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
57 \code{'__import__')}. (This gives the exceptions, because by far the
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
58 majority of built-in functions are harmless. A subclass that wants to
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
59 override this variable should probably start with the value from the
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
60 base class and concatenate additional forbidden functions --- when new
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
61 dangerous built-in functions are added to Python, they will also be
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
62 added to this module.)
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
63 \end{datadesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
64
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
65 \begin{datadesc}{ok_builtin_modules}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
66 Contains the names of built-in modules which can be safely imported.
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
67 The value for \code{RExec} is \code{('audioop',} \code{'array',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
68 \code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
69 \code{'marshal',} \code{'math',} \code{'md5',} \code{'operator',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
70 \code{'parser',} \code{'regex',} \code{'rotor',} \code{'select',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
71 \code{'strop',} \code{'struct',} \code{'time')}. A similar remark
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
72 about overriding this variable applies --- use the value from the base
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
73 class as a starting point.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
74 \end{datadesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
75
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
76 \begin{datadesc}{ok_path}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
77 Contains the directories which will be searched when an \code{import}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
78 is performed in the restricted environment.
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
79 The value for \code{RExec} is the same as \code{sys.path} (at the time
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
80 the module is loaded) for unrestricted code.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
81 \end{datadesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
82
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
83 \begin{datadesc}{ok_posix_names}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
84 % Should this be called ok_os_names?
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
85 Contains the names of the functions in the \code{os} module which will be
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
86 available to programs running in the restricted environment. The
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
87 value for \code{RExec} is \code{('error',} \code{'fstat',}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
88 \code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
89 \code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
90 \code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
91 \code{'getegid')}.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
92 \end{datadesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
93
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
94 \begin{datadesc}{ok_sys_names}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
95 Contains the names of the functions and variables in the \code{sys}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
96 module which will be available to programs running in the restricted
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
97 environment. The value for \code{RExec} is \code{('ps1',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
98 \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
99 \code{'exit',} \code{'maxint')}.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
100 \end{datadesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
101
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
102 RExec instances support the following methods:
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
103 \renewcommand{\indexsubitem}{(RExec object method)}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
104
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
105 \begin{funcdesc}{r_eval}{code}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
106 \var{code} must either be a string containing a Python expression, or
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
107 a compiled code object, which will be evaluated in the restricted
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
108 environment's \code{__main__} module. The value of the expression or
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
109 code object will be returned.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
110 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
111
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
112 \begin{funcdesc}{r_exec}{code}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
113 \var{code} must either be a string containing one or more lines of
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
114 Python code, or a compiled code object, which will be executed in the
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
115 restricted environment's \code{__main__} module.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
116 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
117
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
118 \begin{funcdesc}{r_execfile}{filename}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
119 Execute the Python code contained in the file \var{filename} in the
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
120 restricted environment's \code{__main__} module.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
121 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
122
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
123 Methods whose names begin with \code{s_} are similar to the functions
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
124 beginning with \code{r_}, but the code will be granted access to
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
125 restricted versions of the standard I/O streans \code{sys.stdin},
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
126 \code{sys.stderr}, and \code{sys.stdout}.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
127
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
128 \begin{funcdesc}{s_eval}{code}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
129 \var{code} must be a string containing a Python expression, which will
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
130 be evaluated in the restricted environment.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
131 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
132
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
133 \begin{funcdesc}{s_exec}{code}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
134 \var{code} must be a string containing one or more lines of Python code,
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
135 which will be executed in the restricted environment.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
136 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
137
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
138 \begin{funcdesc}{s_execfile}{code}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
139 Execute the Python code contained in the file \var{filename} in the
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
140 restricted environment.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
141 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
142
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
143 \code{RExec} objects must also support various methods which will be
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
144 implicitly called by code executing in the restricted environment.
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
145 Overriding these methods in a subclass is used to change the policies
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
146 enforced by a restricted environment.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
147
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
148 \begin{funcdesc}{r_import}{modulename\optional{\, globals\, locals\, fromlist}}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
149 Import the module \var{modulename}, raising an \code{ImportError}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
150 exception if the module is considered unsafe.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
151 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
152
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
153 \begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
154 Method called when \code{open()} is called in the restricted
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
155 environment. The arguments are identical to those of \code{open()},
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
156 and a file object (or a class instance compatible with file objects)
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
157 should be returned. \code{RExec}'s default behaviour is allow opening
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
158 any file for reading, but forbidding any attempt to write a file. See
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
159 the example below for an implementation of a less restrictive
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
160 \code{r_open()}.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
161 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
162
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
163 \begin{funcdesc}{r_reload}{module}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
164 Reload the module object \var{module}, re-parsing and re-initializing it.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
165 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
166
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
167 \begin{funcdesc}{r_unload}{module}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
168 Unload the module object \var{module} (i.e., remove it from the
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
169 restricted environment's \code{sys.modules} dictionary).
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
170 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
171
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
172 And their equivalents with access to restricted standard I/O streams:
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
173
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
174 \begin{funcdesc}{s_import}{modulename\optional{\, globals, locals, fromlist}}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
175 Import the module \var{modulename}, raising an \code{ImportError}
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
176 exception if the module is considered unsafe.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
177 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
178
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
179 \begin{funcdesc}{s_reload}{module}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
180 Reload the module object \var{module}, re-parsing and re-initializing it.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
181 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
182
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
183 \begin{funcdesc}{s_unload}{module}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
184 Unload the module object \var{module}.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
185 % XXX what are the semantics of this?
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
186 \end{funcdesc}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
187
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
188 \subsection{An example}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
189
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
190 Let us say that we want a slightly more relaxed policy than the
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
191 standard RExec class. For example, if we're willing to allow files in
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
192 \file{/tmp} to be written, we can subclass the \code{RExec} class:
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
193
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
194 \bcode\begin{verbatim}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
195 class TmpWriterRExec(rexec.RExec):
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
196 def r_open(self, file, mode='r', buf=-1):
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
197 if mode in ('r', 'rb'):
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
198 pass
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
199 elif mode in ('w', 'wb', 'a', 'ab'):
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
200 # check filename : must begin with /tmp/
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
201 if file[:5]!='/tmp/':
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
202 raise IOError, "can't write outside /tmp"
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
203 elif (string.find(file, '/../') >= 0 or
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
204 file[:3] == '../' or file[-3:] == '/..'):
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
205 raise IOError, "'..' in filename forbidden"
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
206 else: raise IOError, "Illegal open() mode"
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
207 return open(file, mode, buf)
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
208 \end{verbatim}\ecode
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
209
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
210 Notice that the above code will occasionally forbid a perfectly valid
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
211 filename; for example, code in the restricted environment won't be
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
212 able to open a file called \file{/tmp/foo/../bar}. To fix this, the
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
213 \code{r_open} method would have to simplify the filename to
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
214 \file{/tmp/bar}, which would require splitting apart the filename and
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
215 performing various operations on it. In cases where security is at
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
216 stake, it may be preferable to write simple code which is sometimes
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
217 overly restrictive, instead of more general code that is also more
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
218 complex and may harbor a subtle security hole.