safe(3tcl)


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  application  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  virtualized  path
   containing tokens. When the safe interpreter requests to source a file,
   it  uses  the  token  in  the  virtual 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 interpreter:

   ::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  provided, 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  description.   Example
          of use:

                 # Create new interp with the same configuration as "$i0":
                 set i1 [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 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 virtual
          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 currently 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 debugging 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-ambiguous 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 packages.

   -nested boolean
          This option specifies if the safe interpreter will be allowed to
          load packages into its own sub-interpreters.  The default  value
          is  false  :  safe interpreters 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-interpreters.

   -deleteHook script
          When this option  is  given  a  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  interpreter.   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
          filenames.

   load fileName
          The requested file, a shared object file, is dynamically  loaded
          into  the  safe  interpreter  if it is found.  The filename must
          contain a token name mentioned 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  encoding  alias  provides  access  to  a safe subset 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  computation  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 system, 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  interpreter.   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
   interpreter 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 arguments for the source and load aliases
   provided to the slave  are  path  in  the  form  of  [file  join  token
   filename] (i.e. when using the native file path formats: token/filename
   on Unix and token\filename on Windows), 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  sensitive  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  following  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 cannot be dangerous as they run in  the  slave
   interpreter)  and  C extensions that provides a _SafeInit 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 invisible 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 specifying 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  (i.e.  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(3tcl),  library(3tcl),  load(3tcl), package(3tcl), source(3tcl),
   unknown(3tcl)

KEYWORDS

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





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.