304 lines
14 KiB
Plaintext
304 lines
14 KiB
Plaintext
'\"
|
|
'\" 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
|