Tcl Built-In Commands


Safe Tcl - A mechanism for managing security policies.


tcl_safeCreateInterp slave

tcl_safeDeleteInterp slave

tcl_safeAutoPath slave ?path?

tcl_safePolicyPath ?path?

policy_policyInit slave

policy_policyFinalize slave


This manual entry describes Safe Tcl, a mechanism and collection of library procedures for managing security policies. Safe Tcl is used in applications that want to provide a flexible, extensible safe hosting environment for untrusted guest scripts, tclets. It provides a mechanism to ensure that tclets cannot harm the hosting application, and a way to extend limited degrees of trust to such tclets, to allow them to have access to unsafe features.

The content of this manual entry is of interest to four different audiences: authors of tclets will primarily be interested in the sections on the SAFE BASE and on USING SAFE TCL IN TCLETS. Application authors will find relevant information in the section on USING SAFE TCL IN APPLICATIONS. To create a new security policy, e.g. to enable tclets to have access to a new feature, read the section on WRITING SECURITY POLICIES. Finally, system administrators and people installing Safe Tcl will find useful information in the section on INSTALLING SECURITY POLICIES.

Security policies are collections of procedures, aliases, hidden commands and variable settings that together implement a controlled way for an application to allow a tclet to have restricted access to unsafe features. For a complete description of aliases, hidden commands and how to use multiple interpreters in an application, see the manual entry for the interp command.

Packaging collections of features into security policies has several advantages: First, it allows these collections to have names. This facilitates the formation of a common, agreed upon, understanding of what features are included in each policy. Second, it enables a reasoned approach to developing extensions that make restricted features available to untrusted tclets. Third, because the feature set is delineated clearly, a security policy can be subjected to analysis to determine what risks it exposes its user to.

The Safe Tcl approach to safe execution of untrusted code is further discussed in The Safe-Tcl Security Model ( This paper provides a detailed discussion of the underlying motivations and philosophy, and compares the Safe Tcl model with other current efforts.


This section describes the environment in which tclets start execution in an application using Safe Tcl. This environment is known as the Safe Base, as it provides the basis on which further security policies are built.

When a tclet starts execution in an environment using Safe Tcl, its interpreter will contain aliases for the following commands:

exit             file             load             source
The exit alias terminates the execution of the invoking slave. File allows access to a subset of the sub-commands of the full file command. load and source make extensions available to the tclet in a controlled manner. The tclPkgUnknown alias allows the application to interpose on package require invocations by the tclet.

The following Tcl commands are hidden in the Safe Base:

cd               exec             exit             fconfigure
file             glob             load             open
pwd              socket           source           vwait

A tclet can also request to load packages using package require. Please read the manual page on the package and load commands for a discussion of package loading and special restrictions on loading into safe interpreters.


Tclets start executing in the environment described in the previous section, on the SAFE BASE. If they need access to unsafe features, tclets can request to use a named security policy by invoking package require with the policy name. If the request is denied by the application's master interpreter, an error is returned. A tclet can catch the error and request to use a different named policy, until a request is granted.

A tclet can only use one security policy during its lifetime. Once an invocation of package require to load a security policy succeeds, Safe Tcl prevents subsequent invocations of package require from succeeding if the requested package is a security policy. There is also no mechanism for a tclet to stop using a security policy, once it is loaded. Invocations of package require to load other packages unrelated to security policies will still succeed.

These restrictions are designed to prevent a tclet from composing security policies either concurrently or sequentially, in ways not supported or forseen by the authors of the policies. Allowing such composition would expose the application to unknown security risks, because a security policy that is safe in isolation is not necessarily safe when used in conjunction with other security policies. For example, a security policy that allows read-only access to the local file system can not disclose private data belonging to the application if it does not have access to network communication commands such as socket. However, when used in conjunction with another security policy that enables the socket command, this policy is no longer safe.


An application using Safe Tcl is usually structured as one or more unsafe interpreters in which trusted code belonging to the application is executed. Each such master interpreter controls one or more safe slave interpreters in which tclets are executed. Tclets communicate with their master interpreter via the aliases provided by the Safe Base and via additional mechanisms installed by each security policy. This section describes the procedures an application invokes to use Safe Tcl and to manage slave interpreters.

An application invokes tcl_safeCreateSlave slave to create a new slave interpreter; this new interpreter will contain the aliases provided by the Safe Base. A new command named slave is also created in the invoking interpreter, to allow the application to manipulate the new slave interpreter.

An application should invoke tcl_safeDeleteSlave slave to delete an interpreter previously created by tcl_safeCreateSlave. This procedure terminates the execution of the tclet in the slave interpreter and cleans up associated state maintained by the Safe Tcl mechanism.

An application can control which packages can be found and loaded by each slave interpreter. Invoking tcl_safeAutoPath with one argument, the name of a slave, retrieves the auto-path search path used to find packages for that slave in response to an invocation of package require. Invoking tcl_safeAutoPath with two arguments sets the auto-path search path used for the slave interpreter named by the first argument to the path specified by the second argument.

Security policies are installed on the file system of the system on which the application is executing. To control the locations from which security policies can be retrieved, an application can use tcl_safePolicyPath. Invoked with no arguments, it returns the current search path for policies. When invoked with an argument, it uses the value as the new search path.

Safe Tcl will invoke, on behalf of an application, additional procedures provided by individual security policies to manage the lifecycle of those policies. These additional procedures are described in the next section.


Writing a security policy is a complex effort that should not be undertaken lightly. It involves careful design, exhaustive testing, public review and analysis and continuous debugging. In addition to considering what features a security policy should provide, the implementer has to constantly keep in mind the security risks to which an application using the policy may be exposed. Actively considering each feature to see if it can be used to compromise an application will help to minimize the chance of a security mishap later on.

A security policy is a Tcl script or a shared library that is loaded into an unsafe master interpreter. A security policy consists of two parts: a management part, concerned with installing the policy into safe slaves and cleaning up after a slave is destroyed, and a runtime part, concerned with actually implementing the features of the policy.

The management part of a security policy consists of two Tcl procedures or commands, one for installing the security policy features into a safe slave, and the other for cleaning up any associated state when a slave is destroyed. The names of these procedures or commands are policy_policyInit and policy_policyFinalize, where policy is the name of the policy as used by the slave interpreter in the package require invocation.

The policy initialization procedure policy_policyInit called in the master interpreter with one argument, the name of the slave interpreter, when a slave requests to use the policy security policy. Error returns indicate that the slave was denied permission to use this policy; the error is propagated back to the slave interpreter. Successful return indicates that the policy is now available in the requesting slave. If it decides to allow the slave to use the requested policy, policy_policyInit should install new aliases and command into the slave, initialize variables both in the master interpreter and in the slave, and do any other initialization work to make the policy features available in the slave. Policy initialization procedures may also perform other tasks, such as creating policy specific state data for the new slave using this policy.

Policy initialization procedures should be careful to leave a clean state in the slave interpreter if a failure occurs during initialization; the rule is that if an error is returned, no changes in any variables, procedures or aliases should be detectable in the slave. For example, if use of a security policy requires creation of a socket to a remote host at initialization time, and if that host is not accessible, all aliases created in the slave to use the policy should be removed. Otherwise, these aliases might open security holes when used in conjunction with another security policy subsequently requested by the slave. Without this, a malicious tclet could purposely cause a failure during initialization in one security policy and compose features provided by that policy in an unsafe manner with another security policy requested later.

When an application invokes tcl_safeDeleteSlave to delete a slave interpreter, the policy finalization procedure policy_policyFinalize for the policy in use by the slave is called. It receives one argument, the name of the slave interpreter being deleted. This procedure should ensure that subsequently if a slave by the same name is re-created, the new slave will be able to use this policy. It may also wish to remove any policy specific state data created by policy_policyInit.

During initialization, a number of aliases may be created in the slave; when these aliases are invoke, they cause commands defined in the master to execute. The runtime part of a security policy consists of implementations of all the target commands that handle the invocation of aliases in the slave. Because these commands execute in a trusted interpreter, they have full access to all the capabilities of Tcl and any extensions loaded into the master interpreter.

A security policy must provide a tclIndex file in addition to files containing Tcl procedures and shared libraries implementing the policy. To generate a tclIndex file, use the Tcl command auto_mkindex which is described in the manual page for the Tcl library.


Safe Tcl uses a platform dependent mechanism for obtaining the initial setting for the search path for finding security policies. On Unix, the environment variable TCL_POLICY_PATH is consulted. On Win32 systems, the registry values HKEY_CURRENT_USER\Software\Sun\Safe Tcl\PolicyPath and HKEY_LOCAL_MACHINE\Software\Sun\Safe Tcl\PolicyPath are concatenated to form the initial search path. On MacOS there is currently no mechanism provided to obtain the initial value; each application should provide its own mechanism for obtaining the initial search path.

The search path is searched in reverse order of the order in which entries appear. Thus, if two or more policies by the same name occur in the path, the last policy by that name will be used by Safe Tcl. This enable system administrators to install system wide security policies in a centralized directory and then require users to include that directory as the last component in the search path. Doing so will ensure that system wide policies are used in preference of policies installed by individual users.

To install a policy, create a sub-directory of one of the directories mentioned in the policy search path, and copy all the files comprising the policy into the new directory. Applications should be able, in most situations, to use the newly available policy immediately, without having to restart. If a security policy uses the same name as a regular package, a package require invocation in a slave interpreter will preferentially use the security policy over the regular package. However, if a security policy is installed after the first invocation of package require in an application, and a regular package exists by the same name, the security policy will not be available for use in that application. In this case you must restart the application for the policy to become available.


The security policy mechanism extends and expands on the Safe-Tcl prototype first implemented by Nathaniel Borenstein and Marshall Rose.


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


alias, auto-loading, load, master interpreter, security policy, safe interpreter, slave interpreter, source

Last change: 7.7

[ tcl8.0a1 | tk8.0a1 | X-ref ]

Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.