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