1Safe Tcl(n)                  Tcl Built-In Commands                 Safe Tcl(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       safe - Creating and manipulating safe interpreters
9

SYNOPSIS

11       ::safe::interpCreate ?child? ?options...?
12
13       ::safe::interpInit child ?options...?
14
15       ::safe::interpConfigure child ?options...?
16
17       ::safe::interpDelete child
18
19       ::safe::interpAddToAccessPath child directory
20
21       ::safe::interpFindInAccessPath child directory
22
23       ::safe::setLogCmd ?cmd arg...?
24
25   OPTIONS
26       ?-accessPath pathList?  ?-statics boolean? ?-noStatics?  ?-nested bool‐
27       ean? ?-nestedLoadOk?  ?-deleteHook script?
28______________________________________________________________________________
29

DESCRIPTION

31       Safe Tcl is a mechanism for executing untrusted Tcl scripts safely  and
32       for  providing mediated access by such scripts to potentially dangerous
33       functionality.
34
35       Safe Tcl ensures that untrusted Tcl scripts cannot harm the hosting ap‐
36       plication.   It  prevents  integrity and privacy attacks. Untrusted Tcl
37       scripts are prevented from corrupting the state of the hosting applica‐
38       tion  or computer. Untrusted scripts are also prevented from disclosing
39       information stored on the hosting computer or in the  hosting  applica‐
40       tion to any party.
41
42       Safe  Tcl allows a parent interpreter to create safe, restricted inter‐
43       preters that contain a set of predefined aliases for the source,  load,
44       file,  encoding, and exit commands and are able to use the auto-loading
45       and package mechanisms.
46
47       No knowledge of the file system structure is leaked to the safe  inter‐
48       preter, because it has access only to a virtualized path containing to‐
49       kens. When the safe interpreter requests to source a file, it uses  the
50       token  in the virtual path as part of the file name to source; the par‐
51       ent interpreter transparently translates the token into a  real  direc‐
52       tory  name  and executes the requested operation (see the section SECU‐
53       RITY below for details).  Different levels of security can be  selected
54       by using the optional flags of the commands described below.
55
56       All  commands  provided in the parent interpreter by Safe Tcl reside in
57       the safe namespace.
58

COMMANDS

60       The following commands are provided in the parent interpreter:
61
62       ::safe::interpCreate ?child? ?options...?
63              Creates a safe interpreter, installs the  aliases  described  in
64              the section ALIASES and initializes the auto-loading and package
65              mechanism as specified by the supplied options.  See the OPTIONS
66              section  below  for a description of the optional arguments.  If
67              the child  argument  is  omitted,  a  name  will  be  generated.
68              ::safe::interpCreate always returns the interpreter name.
69
70              The interpreter name child may include namespace separators, but
71              may not have leading or trailing namespace separators, or excess
72              colon  characters in namespace separators.  The interpreter name
73              is qualified relative to the global namespace ::, not the  name‐
74              space in which the ::safe::interpCreate command is evaluated.
75
76       ::safe::interpInit child ?options...?
77              This  command is similar to interpCreate except it that does not
78              create the safe interpreter. child must  have  been  created  by
79              some  other  means,  like  interp create -safe.  The interpreter
80              name child may include namespace separators, subject to the same
81              restrictions as for interpCreate.
82
83       ::safe::interpConfigure child ?options...?
84              If  no  options  are given, returns the settings for all options
85              for the named safe interpreter as a list of  options  and  their
86              current  values for that child.  If a single additional argument
87              is provided, it will return a list of 2 elements name and  value
88              where name is the full name of that option and value the current
89              value for that option and the child.  If  more  than  two  addi‐
90              tional  arguments are provided, it will reconfigure the safe in‐
91              terpreter and change each and only the  provided  options.   See
92              the  section  on OPTIONS below for options description.  Example
93              of use:
94
95                     # Create new interp with the same configuration as "$i0":
96                     set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]]
97
98                     # Get the current deleteHook
99                     set dh [safe::interpConfigure $i0  -del]
100
101                     # Change (only) the statics loading ok attribute of an
102                     # interp and its deleteHook (leaving the rest unchanged):
103                     safe::interpConfigure $i0  -delete {foo bar} -statics 0
104
105       ::safe::interpDelete child
106              Deletes the safe interpreter and  cleans  up  the  corresponding
107              parent  interpreter data structures.  If a deleteHook script was
108              specified for this interpreter it is evaluated before the inter‐
109              preter  is deleted, with the name of the interpreter as an addi‐
110              tional argument.
111
112       ::safe::interpFindInAccessPath child directory
113              This command finds and returns the token for the real  directory
114              directory in the safe interpreter's current virtual access path.
115              It generates an error if the directory is not found.  Example of
116              use:
117
118                     $child eval [list set tk_library \
119                           [::safe::interpFindInAccessPath $name $tk_library]]
120
121       ::safe::interpAddToAccessPath child directory
122              This  command  adds directory to the virtual path maintained for
123              the safe interpreter in the parent, and returns the  token  that
124              can be used in the safe interpreter to obtain access to files in
125              that directory.  If the directory  is  already  in  the  virtual
126              path,  it only returns the token without adding the directory to
127              the virtual path again.  Example of use:
128
129                     $child eval [list set tk_library \
130                           [::safe::interpAddToAccessPath $name $tk_library]]
131
132       ::safe::setLogCmd ?cmd arg...?
133              This command installs a script that will be called  when  inter‐
134              esting  life  cycle  events  occur for a safe interpreter.  When
135              called with no arguments, it  returns  the  currently  installed
136              script.   When  called  with  one argument, an empty string, the
137              currently installed script is removed and logging is turned off.
138              The  script  will  be  invoked  with  one additional argument, a
139              string describing the event of interest.  The main purpose is to
140              help  in  debugging  safe interpreters.  Using this facility you
141              can get complete error messages while the safe interpreter  gets
142              only  generic  error messages.  This prevents a safe interpreter
143              from seeing messages about failures and other events that  might
144              contain sensitive information such as real directory names.
145
146              Example of use:
147
148                     ::safe::setLogCmd puts stderr
149
150              Below  is  the output of a sample session in which a safe inter‐
151              preter attempted to source a file not found in its  virtual  ac‐
152              cess  path.  Note that the safe interpreter only received an er‐
153              ror message saying that the file was not found:
154
155                     NOTICE for child interp10 : Created
156                     NOTICE for child interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
157                     NOTICE for child interp10 : auto_path in interp10 has been set to {$p(:0:)}
158                     ERROR for child interp10 : /foo/bar/init.tcl: no such file or directory
159
160   OPTIONS
161       The following options are common to  ::safe::interpCreate,  ::safe::in‐
162       terpInit, and ::safe::interpConfigure.  Any option name can be abbrevi‐
163       ated to its minimal non-ambiguous name.  Option names are not case sen‐
164       sitive.
165
166       -accessPath directoryList
167              This option sets the list of directories from which the safe in‐
168              terpreter can source and load files.   If  this  option  is  not
169              specified,  or if it is given as the empty list, the safe inter‐
170              preter will use the same directories as  its  parent  for  auto-
171              loading.   See  the section SECURITY below for more detail about
172              virtual paths, tokens and access control.
173
174       -statics boolean
175              This option specifies if the safe interpreter will be allowed to
176              load  statically linked packages (like load {} Tk).  The default
177              value is true : safe interpreters are allowed to load statically
178              linked packages.
179
180       -noStatics
181              This  option  is  a  convenience shortcut for -statics false and
182              thus specifies that the safe interpreter will not be allowed  to
183              load statically linked packages.
184
185       -nested boolean
186              This option specifies if the safe interpreter will be allowed to
187              load packages into its own sub-interpreters.  The default  value
188              is  false  :  safe interpreters are not allowed to load packages
189              into their own sub-interpreters.
190
191       -nestedLoadOk
192              This option is a convenience shortcut for -nested true and  thus
193              specifies  the safe interpreter will be allowed to load packages
194              into its own sub-interpreters.
195
196       -deleteHook script
197              When this option is given a non-empty script, it will be  evalu‐
198              ated  in  the parent with the name of the safe interpreter as an
199              additional argument just before actually deleting the  safe  in‐
200              terpreter.   Giving  an  empty  value  removes any currently in‐
201              stalled deletion hook script for that safe interpreter.  The de‐
202              fault value ({}) is not to have any deletion call back.
203

ALIASES

205       The following aliases are provided in a safe interpreter:
206
207       source fileName
208              The  requested file, a Tcl source file, is sourced into the safe
209              interpreter if it is found.  The source alias  can  only  source
210              files  from  directories in the virtual path for the safe inter‐
211              preter. The source alias requires the safe  interpreter  to  use
212              one  of the token names in its virtual path to denote the direc‐
213              tory in which the file to be sourced can be found.  See the sec‐
214              tion  on  SECURITY  for more discussion of restrictions on valid
215              filenames.
216
217       load fileName
218              The requested file, a shared object file, is dynamically  loaded
219              into  the  safe  interpreter  if it is found.  The filename must
220              contain a token name mentioned in the virtual path for the  safe
221              interpreter  for it to be found successfully.  Additionally, the
222              shared object file must contain a safe entry point; see the man‐
223              ual page for the load command for more details.
224
225       file ?subCmd args...?
226              The  file  alias provides access to a safe subset of the subcom‐
227              mands of the file command; it allows only dirname, join,  exten‐
228              sion,  root,  tail, pathname and split subcommands. For more de‐
229              tails on what these subcommands do see the manual page  for  the
230              file command.
231
232       encoding ?subCmd args...?
233              The  encoding alias provides access to a safe subset of the sub‐
234              commands of the encoding command;  it disallows setting  of  the
235              system encoding, but allows all other subcommands including sys‐
236              tem to check the current encoding.
237
238       exit   The calling  interpreter  is  deleted  and  its  computation  is
239              stopped, but the Tcl process in which this interpreter exists is
240              not terminated.
241

SECURITY

243       Safe Tcl does not attempt to completely prevent annoyance and denial of
244       service  attacks. These forms of attack prevent the application or user
245       from temporarily using the computer to perform useful work, for example
246       by  consuming  all  available CPU time or all available screen real es‐
247       tate.  These attacks, while aggravating, are deemed to be of lesser im‐
248       portance in general than integrity and privacy attacks that Safe Tcl is
249       to prevent.
250
251       The commands available in a safe interpreter, in addition to  the  safe
252       set  as defined in interp manual page, are mediated aliases for source,
253       load, exit, and safe subsets of file and encoding. The safe interpreter
254       can also auto-load code and it can request that packages be loaded.
255
256       Because some of these commands access the local file system, there is a
257       potential for information leakage about its  directory  structure.   To
258       prevent  this, commands that take file names as arguments in a safe in‐
259       terpreter use tokens instead of the real directory names.  These tokens
260       are  translated  to  the  real directory name while a request to, e.g.,
261       source a file is mediated by the parent interpreter.  This virtual path
262       system  is  maintained  in  the parent interpreter for each safe inter‐
263       preter created by ::safe::interpCreate or initialized by ::safe::inter‐
264       pInit  and the path maps tokens accessible in the safe interpreter into
265       real path names on the local file system thus  preventing  safe  inter‐
266       preters  from  gaining knowledge about the structure of the file system
267       of the host on which the interpreter is executing.  The only valid file
268       names  arguments  for the source and load aliases provided to the child
269       are path in the form of [file join token filename] (i.e. when using the
270       native  file path formats: token/filename on Unix and token\filename on
271       Windows), where token is representing one of the directories of the ac‐
272       cessPath list and filename is one file in that directory (no sub direc‐
273       tories access are allowed).
274
275       When a token is used in a safe interpreter in a request  to  source  or
276       load  a  file,  the token is checked and translated to a real path name
277       and the file to be sourced or loaded is located  on  the  file  system.
278       The  safe interpreter never gains knowledge of the actual path name un‐
279       der which the file is stored on the file system.
280
281       To further prevent potential information leakage from  sensitive  files
282       that  are accidentally included in the set of files that can be sourced
283       by a safe interpreter, the source alias restricts access to files meet‐
284       ing  the  following constraints: the file name must fourteen characters
285       or shorter, must not contain more than one dot (“.”), must end up  with
286       the extension (“.tcl”) or be called (“tclIndex”.)
287
288       Each  element  of the initial access path list will be assigned a token
289       that will be set in the child auto_path and the first element  of  that
290       list will be set as the tcl_library for that child.
291
292       If  the access path argument is not given or is the empty list, the de‐
293       fault behavior is to let the child access the same packages as the par‐
294       ent  has access to (Or to be more precise: only packages written in Tcl
295       (which by definition cannot be dangerous as they run in the  child  in‐
296       terpreter) and C extensions that provides a _SafeInit entry point). For
297       that purpose, the parent's auto_path will  be  used  to  construct  the
298       child  access path.  In order that the child successfully loads the Tcl
299       library files (which includes the auto-loading  mechanism  itself)  the
300       tcl_library  will be added or moved to the first position if necessary,
301       in the child access path, so the child tcl_library will be the same  as
302       the  parent's  (its  real  path  will  still  be invisible to the child
303       though).  In order that auto-loading works the same for the  child  and
304       the  parent in this by default case, the first-level sub directories of
305       each directory in the parent auto_path will also be added (if  not  al‐
306       ready  included)  to  the  child access path.  You can always specify a
307       more restrictive path for which sub directories will never be  searched
308       by  explicitly specifying your directory list with the -accessPath flag
309       instead of relying on this default mechanism.
310
311       When the accessPath is changed after the first creation or  initializa‐
312       tion  (i.e. through interpConfigure -accessPath list), an auto_reset is
313       automatically evaluated in the  safe  interpreter  to  synchronize  its
314       auto_index with the new token list.
315

SEE ALSO

317       interp(n), library(n), load(n), package(n), source(n), unknown(n)
318

KEYWORDS

320       alias,  auto-loading,  auto_mkindex, load, parent interpreter, safe in‐
321       terpreter, child interpreter, source
322
323
324
325Tcl                                   8.0                          Safe Tcl(n)
Impressum