diff options
Diffstat (limited to 'contrib/tcl/doc/safe.n')
| -rw-r--r-- | contrib/tcl/doc/safe.n | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/contrib/tcl/doc/safe.n b/contrib/tcl/doc/safe.n new file mode 100644 index 0000000000000..acc50ed7a18e8 --- /dev/null +++ b/contrib/tcl/doc/safe.n @@ -0,0 +1,303 @@ +'\" +'\" 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 |