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?   ?-noStatics?    ?-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 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  translates  the  token  into a real directory
       name and executes the requested operation.  Different lev-
       els  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.
       ::safe::interpCreate creates a new safe  interpreter  with
       options,  described  in  the  section OPTIONS.  The return
       value is the name of the  new  safe  interpreter  created.
       ::safe::interpInit   is  similar  to  ::safe::interpCreate
       except that it requires as its first argument the name  of
       a  safe  interpreter  that was previously created directly
       using the interp  command.   ::safe::interpDelete  deletes
       the interpreter named by its argument.  ::safe::interpCon-
       figure can be used to set or get  options  for  the  named
       safe  interpreters;  the options are described in the sec-
       tion OPTIONS.

       A virtual path is maintained in the master interpreter for
       each  safe  interpreter created by ::safe::interpCreate or
       initialized by ::safe::interpInit.  The path  maps  tokens
       accessible in the safe interpreter into real path names on
       the local file system.  This  prevents  safe  interpreters
       from  gaining  knowledge  about  the structure of the file
       system of the host on which the interpeter  is  executing.
       When a token is used in a safe interpreter in a request to
       source or load a file, the token is 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.  Commands are provided  in  the
       master  interpreter  to  manipulate the virtual path for a
       safe interpreter.  ::safe::interpConfigure can be used  to
       set  a new path for a safe interpreter.  ::safe::interpAd-
       dToAccessPath adds a directory to the virtual path for the
       named safe interpreter and returns the token by which that
       directory will be  accessible  in  the  safe  interpreter.
       ::safe::interpFindInAccessPath  finds the requested direc-
       tory in the virtual path for the  named  safe  interpreter
       and  returns  the  token  by  which  that directory can be
       accessed in the safe interpreter.   If  the  path  is  not
       found, an error is raised.

       ::safe::setLogCommand  installs a script to be called when
       interesting life cycle events happen.  This script will be
       called with one argument, a string describing the event.

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
              filenames.

       load fileName
              The requested file, a shared object file, in 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 ?options?
              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.

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


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 common 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.   If
              options  are  supplied,  sets  the  options for the
              named safe interpreter. See the section on  OPTIONS
              below.

       ::safe::interpDelete slave
              Deletes  the  safe  interpreter  and  cleans up the
              corresponding master interpreter  data  structures.
              If  a  deletehook  script  was  specified  for this
              interpreter 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 lifecycle 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, and
              returns a list of tokens that will allow  the  safe
              interpreter  access  to  these  directories.   If a
              value for directoryList is not given, or if  it  is
              given  as the empty list, the safe interpreter will
              use the same directories than its master for  auto-
              loading.   See  the section SECURITY below for more
              detail about virtual paths, tokens and access  con-
              trol.

       -noStatics
              This  option  specifies  that  the safe interpreter
              will not be allowed to load statically linked pack-
              ages  (like  load {} Tk).  The default is that safe
              interpreters are allowed to load statically  linked
              packages.

       -nestedLoadOk
              This  option  specifies  that  the safe interpreter
              will be allowed  to  load  packages  into  its  own
              subinterpreters.   The  default is that safe inter-
              preters are not allowed to load packages into their
              own subinterpreters.

       -deleteHook ?script?
              If  script  is given, it is evaluated in the master
              with the name of the safe interpreter as  an  addi-
              tional  argument  just  before  deleting  the  safe
              interpreter.  If no value is given for  script  any
              currently  installed  deletion hook script for that
              safe interpreter is removed; it will no  longer  be
              called  when  the interpreter is deleted.  There is
              no deletion hook script installed by default.


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 agravating, 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 a safe subset
       of file.  The safe interpreter can also auto-load code and
       it  can  request  to load packages.  Because some of these
       commands access the local file system, there is  a  poten-
       tial  for  information  leakage about its directory struc-
       ture.  To prevent this, commands which 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 interpreter.

       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  is  restricted  so  that it can only source
       files with names that have the extension .tcl,  that  con-
       tain  only one dot and that are forteen characters long or
       shorter.

       The default value of the Tcl variable auto_path in a  safe
       interpreter  is  a virtualized token list for the directo-
       ries in the value of its master's auto_path  variable  and
       their  immediate  subdirectories.  The first token in this
       list is also assigned to the Tcl varibale  tcl_library  in
       the  safe  interpreter.   You  can  always  specify a more
       restrictive path for which sub directories will  never  be
       searched by explicitly specifying your directory list with
       the -accessPath flag instead of relying  on  this  default
       mechanism.


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
