path: root/contrib/tcl/doc/safe.n

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" SCCS: @(#) safe.n 1.10 97/03/24 09:21:12
'\" 
.so man.macros
.TH "Safe Tcl" n 7.7 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Safe Tcl \- A mechanism for managing security policies.
.SH SYNOPSIS
.nf
\fBtcl_safeCreateInterp\fR \fIslave\fR
.sp
\fBtcl_safeInitInterp\fR \fIslave\fR
.sp
\fBtcl_safeDeleteInterp\fR \fIslave\fR
.sp
\fIpolicy\fB_policyInit\fR \fIslave\fR
.sp
\fIpolicy\fB_policyFinalize\fR \fIslave\fR
.fi
.BE

.SH DESCRIPTION
.PP
This manual entry describes \fBSafe Tcl\fR, a mechanism and collection of
library procedures for managing security policies. \fBSafe Tcl\fR is used
in \fBapplications\fR that want to provide a flexible, extensible safe
hosting environment for untrusted guest scripts, \fBtclets\fR. 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.
.PP
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 \fBSAFE BASE\fR and on \fBUSING SAFE TCL IN TCLETS\fR.
Application authors will find relevant information in the section on
\fBUSING SAFE TCL IN APPLICATIONS\fR. To create a new security
policy, e.g. to enable tclets to have access to a new feature, read the
section on \fBWRITING SECURITY POLICIES\fB. Finally, system administrators
and people installing \fBSafe Tcl\fR will find useful information in the
section on \fBINSTALLING SECURITY POLICIES\fR.
.PP
\fBSecurity policies\fR 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
\fBinterp\fR command.
.PP
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.
.PP
The \fBSafe Tcl\fR approach to safe execution of untrusted code is further
discussed in \fBThe Safe\-Tcl Security Model\fR
(http://www.sunlabs.com/people/john.ousterhout/SafeTcl.ps).
This paper provides a detailed discussion of the underlying
motivations and philosophy, and compares the \fBSafe Tcl\fR model with
other current efforts.

.SH "SAFE BASE"
.PP
This section describes the environment in which tclets start execution in
an application using \fBSafe Tcl\fR. This environment is known as the
\fBSafe Base\fR, as it provides the basis on which further security
policies are built.
.PP
When a tclet starts execution in an environment using \fBSafe Tcl\fR,
its interpreter will contain aliases for the following commands:
.DS
.ta 1.2i 2.4i 3.6i
\fBexit	file	load	source
tclPkgUnknown\fR
.DE
The \fBexit\fR alias terminates the execution of the
invoking slave.
\fBFile\fR allows access to a subset of the sub\-commands of the full
\fBfile\fR command.
\fBload\fR and \fBsource\fR make extensions available to the tclet in a
controlled manner.
The \fBtclPkgUnknown\fR alias allows the application to interpose on
\fBpackage require\fR invocations by the tclet.
.PP
The following \fBTcl\fR commands are hidden in the Safe Base:
.DS
.ta 1.2i 2.4i 3.6i
\fBcd	exec	exit	fconfigure
file	glob	load	open
pwd	socket	source	vwait\fR
.DE
.PP
A tclet can also request to load packages using \fBpackage require\fR.
Please read the manual page on the \fBpackage\fR and \fBload\fR commands
for a discussion of package loading and special restrictions on loading
into safe interpreters.
.PP
Tclets can use auto-loading to obtain the definitions for procedures as
needed. The auto-loading mechanism in the Safe Base supports tclIndex files
generated by \fBauto_mkindex\fR Version 2 and later.

.SH "USING SAFE TCL IN TCLETS"
.PP
Tclets start executing in the environment described in the previous
section, on the \fBSAFE BASE\fR. If they need access to unsafe features,
tclets can request to use a named security policy by invoking \fBpackage
require\fR with the policy name. If the request is denied by the
application's master interpreter, an error is returned.
A tclet can \fBcatch\fR the error and request to use a different named
policy, until a request is granted.
.PP
A tclet can only use one security policy during its lifetime. Once an
invocation of \fBpackage require\fR to load a security policy succeeds,
Safe Tcl prevents subsequent invocations of \fBpackage require\fR 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 \fBpackage require\fR to load other packages unrelated to
security policies will still succeed.
.PP
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
\fBsocket\fR. However, when used in conjunction with another security
policy that enables the \fBsocket\fR command, this policy is no longer
safe.

.SH "USING SAFE TCL IN APPLICATIONS"
.PP
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 \fBmaster interpreter\fR controls one or more safe
\fBslave interpreters\fR 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.
.PP
An application invokes \fBtcl_safeCreateInterp\fR \fIslave\fR to create a
new slave interpreter; this new interpreter will contain the aliases
provided by the Safe Base. A new command named \fBslave\fR is also created
in the invoking interpreter, to allow the application to manipulate the new
slave interpreter.
.PP
An application can use \fBtcl_safeInitInterp\fR \fIslave\fR to initialize
an existing slave interpreter with the Safe-Tcl security policy mechanism.
This procedure is useful when an application already has a safe slave
interpreter created with \fBinterp create -safe\fR and wishes to enable it
to use security policies.
.PP
An application should invoke \fBtcl_safeDeleteInterp\fR \fIslave\fR to
delete an interpreter previously created by \fBtcl_safeCreateInterp\fR. This
procedure terminates the execution of the tclet in the \fIslave\fR
interpreter and cleans up associated state maintained by the Safe Tcl
mechanism.
.PP
Security policies are installed on the file system of the system on which
the application is executing. Security policies are found in the
\fIpolicies\fR sub-directories of directories mentioned in the
application's \fBauto_path\fR, and in sub-directories of these
\fIpolicies\fR directories.
.PP
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.

.SH "WRITING SECURITY POLICIES"
.PP
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.
.PP
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 \fBmanagement\fR part, concerned
with installing the policy into safe slaves and cleaning up after a slave
is destroyed, and a \fBruntime\fR part, concerned with actually
implementing the features of the policy.
.PP
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 \fIpolicy\fB_policyInit\fR
and \fIpolicy\fB_policyFinalize, where \fIpolicy\fR is the name of the
policy as used by the slave interpreter in the \fBpackage require\fR
invocation.
.PP
The policy initialization procedure \fIpolicy\fB_policyInit\fR called in
the master interpreter with one argument, the name of the slave
interpreter, when a slave requests to use the \fIpolicy\fR 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,
\fIpolicy\fB_policyInit\fR 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.
.PP
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.
.PP
When an application invokes \fBtcl_safeDeleteInterp\fR to delete a slave
interpreter, the policy finalization procedure
\fIpolicy\fB_policyFinalize\fR 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
\fIpolicy\fB_policyInit\fR.
.PP
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.
.PP
A security policy must provide a \fBtclIndex\fR file in addition to files
containing Tcl procedures and shared libraries implementing the policy.
To generate a \fBtclIndex\fR file, use the Tcl command \fBauto_mkindex\fR
which is described in the manual page for the Tcl library.

.SH "INSTALLING SECURITY POLICIES"
.PP
Safe Tcl uses a platform dependent mechanism for obtaining the initial
setting for the search path for finding security policies.
On \fBUnix\fR, the environment variable \fBTCL_POLICY_PATH\fR is consulted.
On \fBWin32\fR systems and on \fBMacOS\fR there is currently no mechanism
provided to obtain the initial value; each application should provide its
own mechanism for obtaining the initial search path. Such mechanisms will
be provided shortly.
.PP
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.
.PP
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 \fBpackage
require\fR 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
\fBpackage require\fR 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.

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

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

.SH KEYWORDS
alias, auto\-loading, auto_mkindex, load, master interpreter, security
policy, safe interpreter, slave interpreter, source