The interp command is used to create and manipulate interpreters. The interpreter being created is called a slave, and the interpreter that creates it is called the master. The master has complete control over the slave. The interp command is summarized in Table 19-1.

Here is a simple example that creates an interpreter, evaluates a couple of commands in it, and then deletes the interpreter:

interp create foo
=> foo
interp eval foo {set a 5}
=> 5
set sum [interp eval foo {expr {$a + $a}}]
=> 10
interp delete foo

In Example 19-1 the interpreter is named foo. Two commands are evaluated in the foo interpreter:

set a 5
expr {$a + $a}

Note that curly braces are used to protect the commands from any interpretation by the main interpreter. The variable a is defined in the foo interpreter and does not conflict with variables in the main interpreter. The set of variables and procedures in each interpreter is completely independent.

interp create foo
=> foo
interp eval foo {interp create bar}
=> bar
interp create {foo bar2}
=> foo bar2
interp slaves
=> foo
interp slaves foo
=> bar bar2
interp delete bar
=> interpreter named "bar" not found
interp delete {foo bar}

interp eval foo {interp create bar}

interp create {foo bar2}
interp delete {foo bar2}

slave operation args ...
interp operation slave args ...

foo eval {set a 5}
interp eval foo {set a 5}

foo issafe
interp issafe foo

interp eval slave [list set var $value]

A child can be created either safe (i.e., untrusted) or fully functional. In the examples so far, the children have been trusted and fully functional; they have all the basic Tcl commands available to them. An interpreter is made safe by eliminating certain commands. Table 19-2 lists the commands removed from safe interpreters. As described later, these commands can be used by the master on behalf of the safe interpreter. To create a safe interpreter, use the -safe flag:

interp create -safe untrusted

A safe interpreter does not have commands to manipulate the file system and other programs (e.g., cd, open, and exec). This ensures that untrusted scripts cannot harm the host computer. The socket command is removed so that untrusted scripts cannot access the network. The exit, source, and load commands are removed so that an untrusted script cannot harm the hosting application. Note that commands like puts and gets are not removed. A safe interpreter can still do I/O, but it cannot create an I/O channel. We will show how to pass an I/O channel to a child interpreter on page 299.

The initial state of a safe interpreter is very safe, but it is too limited. The only thing a safe interpreter can do is compute a string and return that value to the parent. By creating command aliases, a master can give a safe interpreter controlled access to resources. A security policy implements a set of command aliases that add controlled capabilities to a safe interpreter. We will show, for example, how to provide limited network and file system access to untrusted slaves. Tcl provides a framework to manage several security policies, which is described in Chapter 20.

A command alias is a command in one interpreter that is implemented by a command in another interpreter. The master interpreter installs command aliases in its slaves. The command to create an alias has the following general form:

interp alias slave cmd1 target cmd2 ?arg arg ...?

This creates cmd1 in slave that is an alias for cmd2 in target. When cmd1 is invoked in slave, cmd2 is invoked in target. The alias mechanism is transparent to the slave. Whatever cmd2 returns, the slave sees as the return value of cmd1. If cmd2 raises an error, the error is propagated to the slave.

Note

Name the current interpreter with {}.

If target is the current interpreter, name it with {}. The empty list is the way to name yourself as the interpreter. This is the most common case, although target can be a different slave. The slave and target can even be the same interpreter.

The arguments to cmd1 are passed to cmd2, after any additional arguments to cmd2 that were specified when the alias was created. These hidden arguments provide a safe way to pass extra arguments to an alias. For example, it is quite common to pass the name of the slave to the alias. In Example 19-3, exit in the interpreter foo is an alias that is implemented in the current interpreter (i.e., {}). When the slave executes exit, the master executes:

interp delete foo

interp create foo
interp alias foo exit {} interp delete foo
interp eval foo exit
# Child foo is gone.

proc Interp_ListAliases {name out} {
   puts $out "Aliases for $name"
   foreach alias [interp aliases $name] {
      puts $out [format "%-20s => (%s) %s" $alias 
             [interp target $name $alias] 
             [interp alias $name $alias]]
   }
}

proc Interp_DumpAliases {name out} {
   puts $out "# Aliases for $name"
   foreach alias [interp aliases $name] {
      puts $out [format "interp alias %s %s %s %s" 
         $name $alias [list [interp target $name $alias]] 
         [interp alias $name $alias]]
   }
}

The commands listed in Table 19-2 are hidden instead of being completely removed. A hidden command can be invoked in a slave by its master. For example, a master can load Tcl scripts into a slave by using its hidden source command:

interp create -safe slave
interp invokehidden slave source filename

Without hidden commands, the master has to do a bit more work to achieve the same thing. It must open and read the file and eval the contents of the file in the slave. File operations are described in Chapter 9.

interp create -safe slave
set in [open filename]
interp eval slave [read $in]
close $in

Hidden commands were added in Tcl 7.7 in order to better support the Tcl/Tk browser plug-in described in Chapter 20. In some cases, hidden commands are strictly necessary; it is not possible to simulate them any other way. The best examples are in the context of Safe-Tk, where the master creates widgets or does potentially dangerous things on behalf of the slave. These will be discussed in more detail later.

A master can hide and expose commands using the interp hide and interp expose operations, respectively. You can even hide Tcl procedures. However, the commands inside the procedure run with the same privilege as that of the slave. For example, if you are really paranoid, you might not want an untrusted interpreter to read the clock or get timing information. You can hide the clock and time commands:

interp create -safe slave
interp hide slave clock
interp hide slave time

You can remove commands from the slave entirely like this:

interp eval slave [list rename clock {}]
interp eval slave [list rename time {}]

You must be aware of Tcl parsing and substitutions when commands are invoked in other interpreters. There are three cases corresponding to interp eval, interp invokehidden, and command aliases.

With interp eval the command is subject to a complete round of parsing and substitutions in the target interpreter. This occurs after the parsing and substitutions for the interp eval command itself. In addition, if you pass several arguments to interp eval, those are concatenated before evaluation. This is similar to the way the eval command works as described in Chapter 19. The most reliable way to use interp eval is to construct a list to ensure the command is well structured:

interp eval slave [list cmd arg1 arg2]

With hidden commands, the command and arguments are taken directly from the arguments to interp invokehidden, and there are no substitutions done in the target interpreter. This means that the master has complete control over the command structure, and nothing funny can happen in the other interpreter. For this reason you should not create a list. If you do that, the whole list will be interpreted as the command name! Instead, just pass separate arguments to interp invokehidden and they are passed straight through to the target:

interp invokehidden slave command arg1 arg2

Note

Never eval alias arguments.

With aliases, all the parsing and substitutions occur in the slave before the alias is invoked in the master. The alias implementation should never eval or subst any values it gets from the slave to avoid executing arbitrary code.

For example, suppose there is an alias to open files. The alias does some checking and then invokes the hidden open command. An untrusted script might pass [exit] as the name of the file to open in order to create mischief. The untrusted code is hoping that the master will accidentally eval the filename and cause the application to exit. This attack has nothing to do with opening files; it just hopes for a poor alias implementation. Example 19-6 shows an alias that is not subject to this attack:

interp alias slave open {} safeopen slave
proc safeopen {slave filename {mode r}} {
   # do some checks, then...
   interp invokehidden $slave open $filename $mode
}
interp eval slave {open [exit]}

The command in the slave starts out as:

open [exit]

The master has to quote the brackets in its interp eval command or else the slave will try to invoke exit because of command substitution. Presumably exit isn't defined, or it is defined to terminate the slave. Once this quoting is done, the value of filename is [exit] and it is not subject to substitutions. It is safe to use $filename in the interp invokehidden command because it is only substituted once, in the master. The hidden open command also gets [exit] as its filename argument, which is never evaluated as a Tcl command.

A safe child interpreter cannot open files or network sockets directly. An alias can create an I/O channel (i.e., open a file or socket) and give the child access to it. The parent can share the I/O channel with the child, or it can transfer the I/O channel to the child. If the channel is shared, both the parent and the child can use it. If the channel is transferred, the parent no longer has access to the channel. In general, transferring an I/O channel is simpler, but sharing an I/O channel gives the parent more control over an unsafe child. The differences are illustrated in Example 19-7 and Example 19-9.

There are three properties of I/O channels that are important to consider when choosing between sharing and transferring: the name, the seek offset, and the reference count.

The syntax of commands to share or transfer an I/O channel is:

interp share interp1 chanName interp2
interp transfer interp1 chanName interp2

In these commands, chanName exists in interp1 and is being shared or transferred to interp2. As with command aliases, if interp1 is the current interpreter, name it with {}.

The following example creates a temporary file for an unsafe interpreter. The file is opened for reading and writing, and the slave can use it to store data temporarily.

proc TempfileAlias {slave} {
   set i 0
   while {[file exists Temp$slave$i]} {
      incr i
   }
   set out [open Temp$slave$i w+]
   interp transfer {} $out $slave
   return $out
}
proc TempfileExitAlias {slave} {
   foreach file [glob -nocomplain Temp$slave*] {
      file delete -force $file
   }
   interp delete $slave
}
interp create -safe foo
interp alias foo Tempfile {} TempfileAlias foo
interp alias foo exit {} TempfileExitAlias foo

The TempfileAlias procedure is invoked in the parent when the child interpreter invokes Tempfile. TempfileAlias returns the name of the open channel, which becomes the return value from Tempfile. TempfileAlias uses interp transfer to pass the I/O channel to the child so that the child has permission to access the I/O channel. In this example, it would also work to invoke the hidden open command to create the I/O channel directly in the slave.

Example 19-7 is not fully safe because the unsafe interpreter can still overflow the disk or create a million files. Because the parent has transferred the I/O channel to the child, it cannot easily monitor the I/O activity by the child. Example 19-9 addresses these issues.

An safe interpreter created with interp create -safe has no script library environment and no way to source scripts. Tcl provides a safe base that extends a raw safe interpreter with the ability to source scripts and packages which are described in Chapter 12. The safe base also defines an exit alias that terminates the slave like the one in Example 19-7. The safe base is implemented as Tcl scripts that are part of the standard Tcl script library. Create an interpreter that uses the safe base with safe::interpCreate:

safe::interpCreate foo

The safe base has source and load aliases that only access directories on an access path defined by the master interpreter. The master has complete control over what files can be loaded into a slave. In general, it would be all right to source any Tcl program into an untrusted interpreter. However, untrusted scripts might learn things from the error messages they get by sourcing arbitrary files. The safe base also has versions of the package and unknown commands that support the library facility. Table 19-3 lists the Tcl procedures in the safe base:

Table 19-4 lists the aliases defined in a safe interpreter by the safe base.

A security policy defines what a safe interpreter can do. Designing security policies that are secure is difficult. If you design your own, make sure to have your colleagues review the code. Give out prizes to folks who can break your policy. Good policy implementations are proven with lots of review and trial attacks. The good news is that Safe-Tcl security policies can be implemented in relatively small amounts of Tcl code. This makes them easier to analyze and get correct. Here are a number of rules of thumb:

# The index is a host name, and the
# value is a list of port specifications, which can be
# an exact port number
# a lower bound on port number: N-
# a range of port numbers, inclusive: N-M
array set safesock {
   sage.eng      3000-4000
   www.sun.com   80
   webcache.eng  {80 8080}
   bisque.eng    {80 1025-}
}
proc Safesock_PolicyInit {slave} {
   interp alias $slave socket {} SafesockAlias $slave
}
proc SafesockAlias {slave host port} {
   global safesock
   if ![info exists safesock($host)] {
      error "unknown host: $host"
   }

   foreach portspec $safesock($host) {
      set low [set high ""]
      if {[regexp {^([0-9]+)-([0-9]*)$} $portspec x low high]} {
         if {($low <= $port && $high == "") ||
                ($low <= $port && $high >= $port)} {
            set good $port
            break
         }
      } elseif {$port == $portspec} {
         set good $port
      }
   }

   if [info exists good] {
      set sock [interp invokehidden $slave socket $host $good]
      interp invokehidden $slave fconfigure $sock 
         -blocking 0
      return $sock
   }
   error "bad port: $port"
}

set sock [interp invokehidden $slave socket $host $good]
interp invokehidden $slave fconfigure $sock -blocking 0

# Policy parameters:
#  directory is the location for the files
#  maxfile is the number of files allowed in the directory
#  maxsize is the max size for any single file.

array set tempfile {
   maxfile       4
   maxsize       65536
}
# tempfile(directory) is computed dynamically based on
# the source of the script

proc Tempfile_PolicyInit {slave} {
   global tempfile
   interp alias $slave open {} 
      TempfileOpenAlias $slave $tempfile(directory) 
         $tempfile(maxfile)
   interp alias $slave puts {} TempfilePutsAlias $slave 
      $tempfile(maxsize)
   interp alias $slave exit {} TempfileExitAlias $slave
}
proc TempfileOpenAlias {slave dir maxfile name {m r} {p 0777}} {
   global tempfile
   # remove sneaky characters
   regsub -all {|/:} [file tail $name] {} real
   set real [file join $dir $real]
   # Limit the number of files
   set files [glob -nocomplain [file join $dir *]]
   set N [llength $files]
   if {($N >= $maxfile) && (
          [lsearch -exact $files $real] < 0)} {
      error "permission denied"
   }
   if [catch {open $real $m $p} out] {
      return -code error "$name: permission denied"
   }
   lappend tempfile(channels,$slave) $out
   interp share {} $out $slave
   return $out
}
proc TempfileExitAlias {slave} {
   global tempfile
   interp delete $slave
   if [info exists tempfile(channels,$slave)] {
      foreach out $tempfile(channels,$slave) {
         catch {close $out}
      }
      unset tempfile(channels,$slave)
   }
}
# See also the puts alias in Example 24–4 on page 389
proc TempfilePutsAlias {slave max chan args} {
   # max is the file size limit, in bytes
   # chan is the I/O channel
   # args is either a single string argument,
   # or the -nonewline flag plus the string.

   if {[llength $args] > 2} {
      error "invalid arguments"
   }
   if {[llength $args] == 2} {
      if {![string match -n* [lindex $argv 0]]} {
         error "invalid arguments"
      }
      set string [lindex $args 1]
   } else {
      set string [lindex $args 0]

   }
   set size [expr [tell $chan] + [string length $string]]
   if {$size > $max} {
      error "File size exceeded"
   } else {
      puts -nonewline $chan $string
   }
}

proc Tempfile_PolicyInit {slave} {
   global tempfile
   interp alias $slave open {} 
      TempfileOpenAlias $slave $tempfile(directory) 
         $tempfile(maxfile)
   interp hide $slave tell
   interp alias $slave tell {} TempfileTellAlias $slave
   interp hide $slave puts
   interp alias $slave puts {} TempfilePutsAlias $slave 
      $tempfile(maxsize)
   # no special exit alias required
}
proc TempfileOpenAlias {slave dir maxfile name {m r} {p 0777}} {
   # remove sneaky characters
   regsub -all {|/:} [file tail $name] {} real
   set real [file join $dir $real]
   # Limit the number of files
   set files [glob -nocomplain [file join $dir *]]
   set N [llength $files]
   if {($N >= $maxfile) && (
          [lsearch -exact $files $real] < 0)} {
      error "permission denied"
   }
   if [catch {interp invokehidden $slave 
          open $real $m $p} out] {
      return -code error "$name: permission denied"
   }
   return $out
}
proc TempfileTellAlias {slave chan} {
   interp invokehidden $slave tell $chan
}
proc TempfilePutsAlias {slave max chan args} {
   if {[llength $args] > 2} {
      error "invalid arguments"
   }
   if {[llength $args] == 2} {
      if {![string match -n* [lindex $args 0]]} {
         error "invalid arguments"
      }
      set string [lindex $args 1]
   } else {
      set string [lindex $args 0]

   }
   set size [interp invokehidden $slave tell $chan]
   incr size [string length $string]
   if {$size > $max} {
      error "File size exceeded"
   } else {
      interp invokehidden $slave 
         puts -nonewline $chan $string
   }
}

# SafeAfter_PolicyInit creates a child with
# a safe after command

proc SafeAfter_PolicyInit {slave max} {
   # max limits the number of outstanding after events
   global after
   interp alias $slave after {} SafeAfterAlias $slave $max
   interp alias $slave exit {} SafeAfterExitAlias $slave
   # This is used to generate after IDs for the slave.
   set after(id,$slave) 0
}

# SafeAfterAlias is an alias for after. It disallows after
# with only a time argument and no command.

proc SafeAfterAlias {slave max args} {
   global after
   set argc [llength $args]
   if {$argc == 0} {
      error "Usage: after option args"
   }
   switch -- [lindex $args 0] {
      cancel {
         # A naive implementation would just
         # eval after cancel $args
         # but something dangerous could be hiding in args.
         set myid [lindex $args 1]
         if {[info exists after(id,$slave,$myid)]} {
            set id $after(id,$slave,$myid)
            unset after(id,$slave,$myid)
            after cancel $id
         }
         return ""
      }
      default {
         if {$argc == 1} {
            error "Usage: after time command args..."
         }
         if {[llength [array names after id,$slave,*]]
               >= $max} {
            error "Too many after events"
         }
         # Maintain concat semantics
         set command [concat [lrange $args 1 end]]
         # Compute our own id to pass the callback.
         set myid after#[incr after(id,$slave)]
         set id [after [lindex $args 0] 
            [list SafeAfterCallback $slave $myid $command]]
         set after(id,$slave,$myid) $id
         return $myid
      }
   }
}

# SafeAfterCallback is the after callback in the master.
# It evaluates its command in the safe interpreter.

proc SafeAfterCallback {slave myid cmd} {
   global after
   unset after(id,$slave,$myid)
   if [catch {
      interp eval $slave $cmd
   } err] {
      catch {interp eval $slave bgerror $error}
   }
}

# SafeAfterExitAlias is an alias for exit that does cleanup.

proc SafeAfterExitAlias {slave} {
   global after
   foreach id [array names after id,$slave,*] {
      after cancel $after($id)
      unset after($id)
   }
   interp delete $slave
}