1 | '\" |
---|
2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: safe.n,v 1.13 2007/12/13 15:22:33 dgp Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands" |
---|
11 | .BS |
---|
12 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
13 | .SH NAME |
---|
14 | Safe\ Base \- A mechanism for creating and manipulating safe interpreters |
---|
15 | .SH SYNOPSIS |
---|
16 | \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? |
---|
17 | .sp |
---|
18 | \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? |
---|
19 | .sp |
---|
20 | \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? |
---|
21 | .sp |
---|
22 | \fB::safe::interpDelete\fR \fIslave\fR |
---|
23 | .sp |
---|
24 | \fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR |
---|
25 | .sp |
---|
26 | \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR |
---|
27 | .sp |
---|
28 | \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? |
---|
29 | .SS OPTIONS |
---|
30 | .PP |
---|
31 | ?\fB\-accessPath\fR \fIpathList\fR? |
---|
32 | ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR? |
---|
33 | ?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR? |
---|
34 | ?\fB\-deleteHook\fR \fIscript\fR? |
---|
35 | .BE |
---|
36 | .SH DESCRIPTION |
---|
37 | Safe Tcl is a mechanism for executing untrusted Tcl scripts |
---|
38 | safely and for providing mediated access by such scripts to |
---|
39 | potentially dangerous functionality. |
---|
40 | .PP |
---|
41 | The Safe Base ensures that untrusted Tcl scripts cannot harm the |
---|
42 | hosting application. |
---|
43 | The Safe Base prevents integrity and privacy attacks. Untrusted Tcl |
---|
44 | scripts are prevented from corrupting the state of the hosting |
---|
45 | application or computer. Untrusted scripts are also prevented from |
---|
46 | disclosing information stored on the hosting computer or in the |
---|
47 | hosting application to any party. |
---|
48 | .PP |
---|
49 | The Safe Base allows a master interpreter to create safe, restricted |
---|
50 | interpreters that contain a set of predefined aliases for the \fBsource\fR, |
---|
51 | \fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and |
---|
52 | are able to use the auto-loading and package mechanisms. |
---|
53 | .PP |
---|
54 | No knowledge of the file system structure is leaked to the |
---|
55 | safe interpreter, because it has access only to a virtualized path |
---|
56 | containing tokens. When the safe interpreter requests to source a file, it |
---|
57 | uses the token in the virtual path as part of the file name to source; the |
---|
58 | master interpreter transparently |
---|
59 | translates the token into a real directory name and executes the |
---|
60 | requested operation (see the section \fBSECURITY\fR below for details). |
---|
61 | Different levels of security can be selected by using the optional flags |
---|
62 | of the commands described below. |
---|
63 | .PP |
---|
64 | All commands provided in the master interpreter by the Safe Base reside in |
---|
65 | the \fBsafe\fR namespace. |
---|
66 | .SH COMMANDS |
---|
67 | The following commands are provided in the master interpreter: |
---|
68 | .TP |
---|
69 | \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? |
---|
70 | Creates a safe interpreter, installs the aliases described in the section |
---|
71 | \fBALIASES\fR and initializes the auto-loading and package mechanism as |
---|
72 | specified by the supplied \fBoptions\fR. |
---|
73 | See the \fBOPTIONS\fR section below for a description of the |
---|
74 | optional arguments. |
---|
75 | If the \fIslave\fR argument is omitted, a name will be generated. |
---|
76 | \fB::safe::interpCreate\fR always returns the interpreter name. |
---|
77 | .TP |
---|
78 | \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? |
---|
79 | This command is similar to \fBinterpCreate\fR except it that does not |
---|
80 | create the safe interpreter. \fIslave\fR must have been created by some |
---|
81 | other means, like \fBinterp create \-safe\fR. |
---|
82 | .TP |
---|
83 | \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? |
---|
84 | If no \fIoptions\fR are given, returns the settings for all options for the |
---|
85 | named safe interpreter as a list of options and their current values |
---|
86 | for that \fIslave\fR. |
---|
87 | If a single additional argument is provided, |
---|
88 | it will return a list of 2 elements \fIname\fR and \fIvalue\fR where |
---|
89 | \fIname\fR is the full name of that option and \fIvalue\fR the current value |
---|
90 | for that option and the \fIslave\fR. |
---|
91 | If more than two additional arguments are provided, it will reconfigure the |
---|
92 | safe interpreter and change each and only the provided options. |
---|
93 | See the section on \fBOPTIONS\fR below for options description. |
---|
94 | Example of use: |
---|
95 | .RS |
---|
96 | .PP |
---|
97 | .CS |
---|
98 | # Create new interp with the same configuration as "$i0": |
---|
99 | set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]] |
---|
100 | |
---|
101 | # Get the current deleteHook |
---|
102 | set dh [safe::interpConfigure $i0 \-del] |
---|
103 | |
---|
104 | # Change (only) the statics loading ok attribute of an |
---|
105 | # interp and its deleteHook (leaving the rest unchanged): |
---|
106 | safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 |
---|
107 | .CE |
---|
108 | .RE |
---|
109 | .TP |
---|
110 | \fB::safe::interpDelete\fR \fIslave\fR |
---|
111 | Deletes the safe interpreter and cleans up the corresponding |
---|
112 | master interpreter data structures. |
---|
113 | If a \fIdeleteHook\fR script was specified for this interpreter it is |
---|
114 | evaluated before the interpreter is deleted, with the name of the |
---|
115 | interpreter as an additional argument. |
---|
116 | .TP |
---|
117 | \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR |
---|
118 | This command finds and returns the token for the real directory |
---|
119 | \fIdirectory\fR in the safe interpreter's current virtual access path. |
---|
120 | It generates an error if the directory is not found. |
---|
121 | Example of use: |
---|
122 | .RS |
---|
123 | .PP |
---|
124 | .CS |
---|
125 | $slave eval [list set tk_library \e |
---|
126 | [::safe::interpFindInAccessPath $name $tk_library]] |
---|
127 | .CE |
---|
128 | .RE |
---|
129 | .TP |
---|
130 | \fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR |
---|
131 | This command adds \fIdirectory\fR to the virtual path maintained for the |
---|
132 | safe interpreter in the master, and returns the token that can be used in |
---|
133 | the safe interpreter to obtain access to files in that directory. |
---|
134 | If the directory is already in the virtual path, it only returns the token |
---|
135 | without adding the directory to the virtual path again. |
---|
136 | Example of use: |
---|
137 | .RS |
---|
138 | .PP |
---|
139 | .CS |
---|
140 | $slave eval [list set tk_library \e |
---|
141 | [::safe::interpAddToAccessPath $name $tk_library]] |
---|
142 | .CE |
---|
143 | .RE |
---|
144 | .TP |
---|
145 | \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? |
---|
146 | This command installs a script that will be called when interesting |
---|
147 | life cycle events occur for a safe interpreter. |
---|
148 | When called with no arguments, it returns the currently installed script. |
---|
149 | When called with one argument, an empty string, the currently installed |
---|
150 | script is removed and logging is turned off. |
---|
151 | The script will be invoked with one additional argument, a string |
---|
152 | describing the event of interest. |
---|
153 | The main purpose is to help in debugging safe interpreters. |
---|
154 | Using this facility you can get complete error messages while the safe |
---|
155 | interpreter gets only generic error messages. |
---|
156 | This prevents a safe interpreter from seeing messages about failures |
---|
157 | and other events that might contain sensitive information such as real |
---|
158 | directory names. |
---|
159 | .RS |
---|
160 | .PP |
---|
161 | Example of use: |
---|
162 | .PP |
---|
163 | .CS |
---|
164 | ::safe::setLogCmd puts stderr |
---|
165 | .CE |
---|
166 | .PP |
---|
167 | Below is the output of a sample session in which a safe interpreter |
---|
168 | attempted to source a file not found in its virtual access path. |
---|
169 | Note that the safe interpreter only received an error message saying that |
---|
170 | the file was not found: |
---|
171 | .PP |
---|
172 | .CS |
---|
173 | NOTICE for slave interp10 : Created |
---|
174 | NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=() |
---|
175 | NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)} |
---|
176 | ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory |
---|
177 | .CE |
---|
178 | .RE |
---|
179 | .SS OPTIONS |
---|
180 | The following options are common to |
---|
181 | \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, |
---|
182 | and \fB::safe::interpConfigure\fR. |
---|
183 | Any option name can be abbreviated to its minimal |
---|
184 | non-ambiguous name. |
---|
185 | Option names are not case sensitive. |
---|
186 | .TP |
---|
187 | \fB\-accessPath\fR \fIdirectoryList\fR |
---|
188 | This option sets the list of directories from which the safe interpreter |
---|
189 | can \fBsource\fR and \fBload\fR files. |
---|
190 | If this option is not specified, or if it is given as the |
---|
191 | empty list, the safe interpreter will use the same directories as its |
---|
192 | master for auto-loading. |
---|
193 | See the section \fBSECURITY\fR below for more detail about virtual paths, |
---|
194 | tokens and access control. |
---|
195 | .TP |
---|
196 | \fB\-statics\fR \fIboolean\fR |
---|
197 | This option specifies if the safe interpreter will be allowed |
---|
198 | to load statically linked packages (like \fBload {} Tk\fR). |
---|
199 | The default value is \fBtrue\fR : |
---|
200 | safe interpreters are allowed to load statically linked packages. |
---|
201 | .TP |
---|
202 | \fB\-noStatics\fR |
---|
203 | This option is a convenience shortcut for \fB\-statics false\fR and |
---|
204 | thus specifies that the safe interpreter will not be allowed |
---|
205 | to load statically linked packages. |
---|
206 | .TP |
---|
207 | \fB\-nested\fR \fIboolean\fR |
---|
208 | This option specifies if the safe interpreter will be allowed |
---|
209 | to load packages into its own sub-interpreters. |
---|
210 | The default value is \fBfalse\fR : |
---|
211 | safe interpreters are not allowed to load packages into |
---|
212 | their own sub-interpreters. |
---|
213 | .TP |
---|
214 | \fB\-nestedLoadOk\fR |
---|
215 | This option is a convenience shortcut for \fB\-nested true\fR and |
---|
216 | thus specifies the safe interpreter will be allowed |
---|
217 | to load packages into its own sub-interpreters. |
---|
218 | .TP |
---|
219 | \fB\-deleteHook\fR \fIscript\fR |
---|
220 | When this option is given a non-empty \fIscript\fR, it will be |
---|
221 | evaluated in the master with the name of |
---|
222 | the safe interpreter as an additional argument |
---|
223 | just before actually deleting the safe interpreter. |
---|
224 | Giving an empty value removes any currently installed deletion hook |
---|
225 | script for that safe interpreter. |
---|
226 | The default value (\fB{}\fR) is not to have any deletion call back. |
---|
227 | .SH ALIASES |
---|
228 | The following aliases are provided in a safe interpreter: |
---|
229 | .TP |
---|
230 | \fBsource\fR \fIfileName\fR |
---|
231 | The requested file, a Tcl source file, is sourced into the safe interpreter |
---|
232 | if it is found. |
---|
233 | The \fBsource\fR alias can only source files from directories in |
---|
234 | the virtual path for the safe interpreter. The \fBsource\fR alias requires |
---|
235 | the safe interpreter to |
---|
236 | use one of the token names in its virtual path to denote the directory in |
---|
237 | which the file to be sourced can be found. |
---|
238 | See the section on \fBSECURITY\fR for more discussion of restrictions on |
---|
239 | valid filenames. |
---|
240 | .TP |
---|
241 | \fBload\fR \fIfileName\fR |
---|
242 | The requested file, a shared object file, is dynamically loaded into the |
---|
243 | safe interpreter if it is found. |
---|
244 | The filename must contain a token name mentioned in the virtual path for |
---|
245 | the safe interpreter for it to be found successfully. |
---|
246 | Additionally, the shared object file must contain a safe entry point; see |
---|
247 | the manual page for the \fBload\fR command for more details. |
---|
248 | .TP |
---|
249 | \fBfile\fR ?\fIsubCmd args...\fR? |
---|
250 | The \fBfile\fR alias provides access to a safe subset of the subcommands of |
---|
251 | the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR, |
---|
252 | \fBextension\fR, \fBroot\fR, \fBtail\fR, \fBpathname\fR and \fBsplit\fR |
---|
253 | subcommands. For more details on what these subcommands do see the manual |
---|
254 | page for the \fBfile\fR command. |
---|
255 | .TP |
---|
256 | \fBencoding\fR ?\fIsubCmd args...\fR? |
---|
257 | The \fBencoding\fR alias provides access to a safe subset of the |
---|
258 | subcommands of the \fBencoding\fR command; it disallows setting of |
---|
259 | the system encoding, but allows all other subcommands including |
---|
260 | \fBsystem\fR to check the current encoding. |
---|
261 | .TP |
---|
262 | \fBexit\fR |
---|
263 | The calling interpreter is deleted and its computation is stopped, but the |
---|
264 | Tcl process in which this interpreter exists is not terminated. |
---|
265 | .SH SECURITY |
---|
266 | The Safe Base does not attempt to completely prevent annoyance and |
---|
267 | denial of service attacks. These forms of attack prevent the |
---|
268 | application or user from temporarily using the computer to perform |
---|
269 | useful work, for example by consuming all available CPU time or |
---|
270 | all available screen real estate. |
---|
271 | These attacks, while aggravating, are deemed to be of lesser importance |
---|
272 | in general than integrity and privacy attacks that the Safe Base |
---|
273 | is to prevent. |
---|
274 | .PP |
---|
275 | The commands available in a safe interpreter, in addition to |
---|
276 | the safe set as defined in \fBinterp\fR manual page, are mediated aliases |
---|
277 | for \fBsource\fR, \fBload\fR, \fBexit\fR, and safe subsets of |
---|
278 | \fBfile\fR and \fBencoding\fR. The safe interpreter can also auto-load |
---|
279 | code and it can request that packages be loaded. |
---|
280 | .PP |
---|
281 | Because some of these commands access the local file system, there is a |
---|
282 | potential for information leakage about its directory structure. |
---|
283 | To prevent this, commands that take file names as arguments in a safe |
---|
284 | interpreter use tokens instead of the real directory names. |
---|
285 | These tokens are translated to the real directory name while a request to, |
---|
286 | e.g., source a file is mediated by the master interpreter. |
---|
287 | This virtual path system is maintained in the master interpreter for each safe |
---|
288 | interpreter created by \fB::safe::interpCreate\fR or initialized by |
---|
289 | \fB::safe::interpInit\fR and |
---|
290 | the path maps tokens accessible in the safe interpreter into real path |
---|
291 | names on the local file system thus preventing safe interpreters |
---|
292 | from gaining knowledge about the |
---|
293 | structure of the file system of the host on which the interpreter is |
---|
294 | executing. |
---|
295 | The only valid file names arguments |
---|
296 | for the \fBsource\fR and \fBload\fR aliases provided to the slave |
---|
297 | are path in the form of |
---|
298 | \fB[file join \fR\fItoken filename\fR\fB]\fR (i.e. when using the |
---|
299 | native file path formats: \fItoken\fR\fB/\fR\fIfilename\fR |
---|
300 | on Unix and \fItoken\fR\fB\e\fIfilename\fR on Windows), |
---|
301 | where \fItoken\fR is representing one of the directories |
---|
302 | of the \fIaccessPath\fR list and \fIfilename\fR is |
---|
303 | one file in that directory (no sub directories access are allowed). |
---|
304 | .PP |
---|
305 | When a token is used in a safe interpreter in a request to source or |
---|
306 | load a file, the token is checked and |
---|
307 | translated to a real path name and the file to be |
---|
308 | sourced or loaded is located on the file system. |
---|
309 | The safe interpreter never gains knowledge of the actual path name under |
---|
310 | which the file is stored on the file system. |
---|
311 | .PP |
---|
312 | To further prevent potential information leakage from sensitive files that |
---|
313 | are accidentally included in the set of files that can be sourced by a safe |
---|
314 | interpreter, the \fBsource\fR alias restricts access to files |
---|
315 | meeting the following constraints: the file name must |
---|
316 | fourteen characters or shorter, must not contain more than one dot |
---|
317 | .PQ \fB.\fR "" , |
---|
318 | must end up with the extension |
---|
319 | .PQ \fB.tcl\fR |
---|
320 | or be called |
---|
321 | .PQ \fBtclIndex\fR . |
---|
322 | .PP |
---|
323 | Each element of the initial access path |
---|
324 | list will be assigned a token that will be set in |
---|
325 | the slave \fBauto_path\fR and the first element of that list will be set as |
---|
326 | the \fBtcl_library\fR for that slave. |
---|
327 | .PP |
---|
328 | If the access path argument is not given or is the empty list, |
---|
329 | the default behavior is to let the slave access the same packages |
---|
330 | as the master has access to (Or to be more precise: |
---|
331 | only packages written in Tcl (which by definition cannot be dangerous |
---|
332 | as they run in the slave interpreter) and C extensions that |
---|
333 | provides a _SafeInit entry point). For that purpose, the master's |
---|
334 | \fBauto_path\fR will be used to construct the slave access path. |
---|
335 | In order that the slave successfully loads the Tcl library files |
---|
336 | (which includes the auto-loading mechanism itself) the \fBtcl_library\fR will be |
---|
337 | added or moved to the first position if necessary, in the |
---|
338 | slave access path, so the slave |
---|
339 | \fBtcl_library\fR will be the same as the master's (its real |
---|
340 | path will still be invisible to the slave though). |
---|
341 | In order that auto-loading works the same for the slave and |
---|
342 | the master in this by default case, the first-level |
---|
343 | sub directories of each directory in the master \fBauto_path\fR will |
---|
344 | also be added (if not already included) to the slave access path. |
---|
345 | You can always specify a more |
---|
346 | restrictive path for which sub directories will never be searched by |
---|
347 | explicitly specifying your directory list with the \fB\-accessPath\fR flag |
---|
348 | instead of relying on this default mechanism. |
---|
349 | .PP |
---|
350 | When the \fIaccessPath\fR is changed after the first creation or |
---|
351 | initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR), |
---|
352 | an \fBauto_reset\fR is automatically evaluated in the safe interpreter |
---|
353 | to synchronize its \fBauto_index\fR with the new token list. |
---|
354 | .SH "SEE ALSO" |
---|
355 | interp(n), library(n), load(n), package(n), source(n), unknown(n) |
---|
356 | .SH KEYWORDS |
---|
357 | alias, auto\-loading, auto_mkindex, load, master interpreter, safe |
---|
358 | interpreter, slave interpreter, source |
---|