NAME
       Safe Base - A mechanism for creating and manipulating safe
       interpreters.

SYNOPSIS
       ::safe::interpCreate ?slave? ?options...?

       ::safe::interpInit slave ?options...?

       ::safe::interpConfigure slave ?options...?

       ::safe::interpDelete slave

       ::safe::interpAddToAccessPath slave directory

       ::safe::interpFindInAccessPath slave directory

       ::safe::setLogCmd ?cmd arg...?

OPTIONS
       ?-accessPath pathList?   ?-statics  boolean?  ?-noStatics?
       ?-nested boolean? ?-nestedLoadOk?  ?-deleteHook script?


DESCRIPTION
       Safe  Tcl  is  a  mechanism  for  executing  untrusted Tcl
       scripts safely and for providing mediated access  by  such
       scripts to potentially dangerous functionality.

       The  Safe  Base  ensures that untrusted Tcl scripts cannot
       harm the hosting  application.   The  Safe  Base  prevents
       integrity  and  privacy attacks. Untrusted Tcl scripts are
       prevented from corrupting the state of the hosting  appli-
       cation  or  computer. Untrusted scripts are also prevented
       from disclosing information stored on the hosting computer
       or in the hosting application to any party.

       The  Safe Base allows a master interpreter to create safe,
       restricted interpreters that contain a set  of  predefined
       aliases  for  the  source,  load, file, encoding, and exit
       commands and are able to use the auto-loading and  package
       mechanisms.

       No knowledge of the file system structure is leaked to the
       safe interpreter, because it has access only to a virtual-
       ized  path  containing  tokens.  When the safe interpreter
       requests to source a file, it uses the token in  the  vir-
       tual  path  as part of the file name to source; the master
       interpreter transparently translates the token into a real
       directory  name  and executes the requested operation (see
       the section SECURITY below for details).  Different levels
       of security can be selected by using the optional flags of
       the commands described below.
       All commands provided in the  master  interpreter  by  the
       Safe Base reside in the safe namespace:


COMMANDS
       The  following  commands are provided in the master inter-
       preter:

       ::safe::interpCreate ?slave? ?options...?
              Creates a safe interpreter,  installs  the  aliases
              described  in  the  section ALIASES and initializes
              the auto-loading and package mechanism as specified
              by  the  supplied options.  See the OPTIONS section
              below for a description of the optional  arguments.
              If  the  slave  argument is omitted, a name will be
              generated.  ::safe::interpCreate always returns the
              interpreter name.

       ::safe::interpInit slave ?options...?
              This  command  is similar to interpCreate except it
              that does not create the  safe  interpreter.  slave
              must  have  been  created by some other means, like
              interp create -safe.

       ::safe::interpConfigure slave ?options...?
              If no options are given, returns the  settings  for
              all  options  for  the  named safe interpreter as a
              list of options and their current values  for  that
              slave.   If  a  single  additional argument is pro-
              vided, it will return a list of 2 elements name and
              value  where  name  is the full name of that option
              and value the current value for that option and the
              slave.   If  more than two additional arguments are
              provided, it will reconfigure the safe  interpreter
              and change each and only the provided options.  See
              the section on OPTIONS below for  options  descrip-
              tion.  Example of use:
                     # Create a new interp with the same configuration as "$i0" :
                     set i1 [eval safe::interpCreate [safe::interpConfigure $i0]]
                     # Get the current deleteHook
                     set dh [safe::interpConfigure $i0  -del]
                     # Change (only) the statics loading ok attribute of an interp
                     # and its deleteHook (leaving the rest unchanged) :
                     safe::interpConfigure $i0  -delete {foo bar} -statics 0 ;

       ::safe::interpDelete slave
              Deletes the safe interpreter and cleans up the cor-
              responding master interpreter data structures.   If
              a  deleteHook  script was specified for this inter-
              preter it is evaluated before  the  interpreter  is
              deleted,  with  the  name  of the interpreter as an
              additional argument.
       ::safe::interpFindInAccessPath slave directory
              This command finds and returns the  token  for  the
              real  directory directory in the safe interpreter's
              current virtual access path.  It generates an error
              if the directory is not found.  Example of use:
                     $slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]

       ::safe::interpAddToAccessPath slave directory
              This  command  adds  directory  to the virtual path
              maintained for the safe interpreter in the  master,
              and  returns the token that can be used in the safe
              interpreter to  obtain  access  to  files  in  that
              directory.  If the directory is already in the vir-
              tual path, it only returns the token without adding
              the  directory  to the virtual path again.  Example
              of use:
                     $slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]

       ::safe::setLogCmd ?cmd arg...?
              This command installs a script that will be  called
              when interesting life cycle events occur for a safe
              interpreter.  When called  with  no  arguments,  it
              returns   the  currently  installed  script.   When
              called with one argument, an empty string, the cur-
              rently  installed  script is removed and logging is
              turned off.  The script will be  invoked  with  one
              additional  argument, a string describing the event
              of interest.  The main purpose is to help in debug-
              ging  safe  interpreters.   Using this facility you
              can get complete  error  messages  while  the  safe
              interpreter gets only generic error messages.  This
              prevents a safe interpreter  from  seeing  messages
              about  failures and other events that might contain
              sensitive information such as real directory names.
              Example of use:
                     ::safe::setLogCmd puts stderr
              Below  is the output of a sample session in which a
              safe interpreter attempted to  source  a  file  not
              found  in  its  virtual access path.  Note that the
              safe interpreter only  received  an  error  message
              saying that the file was not found:
                     NOTICE for slave interp10 : Created
                     NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
                     NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
                     ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory


OPTIONS
       The  following options are common to ::safe::interpCreate,
       ::safe::interpInit,  and   ::safe::interpConfigure.    Any
       option  name can be abbreviated to its minimal non-ambigu-
       ous name.  Option names are not case sensitive.
       -accessPath directoryList
              This option sets the list of directories from which
              the safe interpreter can source and load files.  If
              this option is not specified, or if it is given  as
              the  empty  list, the safe interpreter will use the
              same directories as its  master  for  auto-loading.
              See  the  section  SECURITY  below  for more detail
              about virtual paths, tokens and access control.

       -statics boolean
              This option specifies if the safe interpreter  will
              be allowed to load statically linked packages (like
              load {} Tk).  The default  value  is  true  :  safe
              interpreters  are allowed to load statically linked
              packages.

       -noStatics
              This option is a convenience shortcut for  -statics
              false  and thus specifies that the safe interpreter
              will not be allowed to load statically linked pack-
              ages.

       -nested boolean
              This  option specifies if the safe interpreter will
              be allowed to load packages into its own sub-inter-
              preters.   The default value is false : safe inter-
              preters are not allowed to load packages into their
              own sub-interpreters.

       -nestedLoadOk
              This  option  is a convenience shortcut for -nested
              true and thus specifies the safe  interpreter  will
              be allowed to load packages into its own sub-inter-
              preters.

       -deleteHook script
              When this option is given an non empty  script,  it
              will  be  evaluated  in the master with the name of
              the safe interpreter as an additional argument just
              before  actually  deleting  the  safe  interpreter.
              Giving  an  empty  value  removes   any   currently
              installed deletion hook script for that safe inter-
              preter.  The default value ({}) is not to have  any
              deletion call back.

ALIASES
       The following aliases are provided in a safe interpreter:

       source fileName
              The  requested  file, a Tcl source file, is sourced
              into the safe interpreter  if  it  is  found.   The
              source alias can only source files from directories
              in the virtual path for the safe  interpreter.  The
              source  alias  requires the safe interpreter to use
              one of the token  names  in  its  virtual  path  to
              denote  the  directory  in  which  the  file  to be
              sourced can be found.  See the section on  SECURITY
              for  more discussion of restrictions on valid file-
              names.

       load fileName
              The requested file, a shared object file, is dynam-
              ically  loaded  into  the safe interpreter if it is
              found.  The filename must contain a token name men-
              tioned in the virtual path for the safe interpreter
              for it to be found successfully.  Additionally, the
              shared object file must contain a safe entry point;
              see the manual page for the load command  for  more
              details.

       file ?subCmd args...?
              The  file alias provides access to a safe subset of
              the subcommands of the file command; it allows only
              dirname,  join, extension, root, tail, pathname and
              split subcommands. For more details on  what  these
              subcommands  do  see  the  manual page for the file
              command.

       encoding ?subCmd args...?
              The enconding alias provides access to a safe  sub-
              set of the subcommands of the encoding command;  it
              disallows  setting  of  the  system  encoding,  but
              allows  all  other  subcommands including system to
              check the current encoding.

       exit   The calling interpreter is deleted and its computa-
              tion  is stopped, but the Tcl process in which this
              interpreter exists is not terminated.


SECURITY
       The Safe Base  does  not  attempt  to  completely  prevent
       annoyance  and  denial  of service attacks. These forms of
       attack prevent the application or  user  from  temporarily
       using  the computer to perform useful work, for example by
       consuming all available CPU time or all  available  screen
       real estate.  These attacks, while aggravating, are deemed
       to be of lesser importance in general than  integrity  and
       privacy attacks that the Safe Base is to prevent.

       The  commands available in a safe interpreter, in addition
       to the safe set as defined  in  interp  manual  page,  are
       mediated  aliases for source, load, exit, and safe subsets
       of file and encoding. The safe interpreter can also  auto-
       load code and it can request that packages be loaded.

       Because  some of these commands access the local file sys-
       tem, there is a potential for  information  leakage  about
       its  directory  structure.  To prevent this, commands that
       take file names as arguments in  a  safe  interpreter  use
       tokens  instead of the real directory names.  These tokens
       are translated to the real directory name while a  request
       to,  e.g.,  source a file is mediated by the master inter-
       preter.  This virtual path system  is  maintained  in  the
       master  interpreter  for  each safe interpreter created by
       ::safe::interpCreate or initialized by  ::safe::interpInit
       and  the  path  maps  tokens accessible in the safe inter-
       preter into real path names on the local file system  thus
       preventing  safe interpreters from gaining knowledge about
       the structure of the file system of the host on which  the
       interpreter is executing.  The only valid file names argu-
       ments for the source and  load  aliases  provided  to  the
       slave  are  path in the form of [file join token filename]
       (ie, when using the native file path formats:  token/file-
       name  on  Unix, token\filename on Windows, and token:file-
       name on the Mac), where token is representing one  of  the
       directories  of  the  accessPath  list and filename is one
       file in that directory  (no  sub  directories  access  are
       allowed).

       When a token is used in a safe interpreter in a request to
       source or load a file, the token is checked and translated
       to  a  real path name and the file to be sourced or loaded
       is located on the file system.  The safe interpreter never
       gains  knowledge  of  the actual path name under which the
       file is stored on the file system.

       To further prevent potential information leakage from sen-
       sitive  files that are accidentally included in the set of
       files that can be  sourced  by  a  safe  interpreter,  the
       source alias restricts access to files meeting the follow-
       ing constraints: the file name must fourteen characters or
       shorter,  must  not  contain more than one dot ("."), must
       end up with the extension .tcl or be called tclIndex.

       Each element of the  initial  access  path  list  will  be
       assigned  a  token that will be set in the slave auto_path
       and the first element of that list  will  be  set  as  the
       tcl_library for that slave.

       If  the  access path argument is not given or is the empty
       list, the default behavior is to let the slave access  the
       same  packages  as the master has access to (Or to be more
       precise: only packages written in Tcl (which by definition
       can't  be  dangerous as they run in the slave interpreter)
       and C extensions that provides a Safe_Init  entry  point).
       For  that  purpose, the master's auto_path will be used to
       construct the slave access path.  In order that the  slave
       successfully  loads  the Tcl library files (which includes
       the auto-loading mechanism itself) the tcl_library will be
       added  or moved to the first position if necessary, in the
       slave access path, so the slave tcl_library  will  be  the
       same  as the master's (its real path will still be invisi-
       ble to the slave  though).   In  order  that  auto-loading
       works  the  same  for  the slave and the master in this by
       default case, the  first-level  sub  directories  of  each
       directory  in  the master auto_path will also be added (if
       not already included) to the slave access path.   You  can
       always  specify  a  more  restrictive  path  for which sub
       directories will never be searched by explicitly  specify-
       ing  your directory list with the -accessPath flag instead
       of relying on this default mechanism.

       When the accessPath is changed after the first creation or
       initialization  (ie  through  interpConfigure  -accessPath
       list), an auto_reset is  automatically  evaluated  in  the
       safe  interpreter  to  synchronize its auto_index with the
       new token list.


SEE ALSO
       interp(n),  library(n),  load(n),  package(n),  source(n),
       unknown(n)


KEYWORDS
       alias,  auto-loading,  auto_mkindex,  load,  master inter-
       preter, safe interpreter, slave interpreter, source
