NAME

feature - Features of Safe Tcl applications.

SYNOPSYS

package require safefeature

DESCRIPTION

This manual entry describes the feature mechanism of Safe Tcl. It explains how features work and how to write and install new features.

FEATURE

A feature is a named collection of capabilities installed into a Safe-Tcl program via command aliases. Features are installed into a Safe-Tcl interpreter by a security policy when the feature is allowed by the policy. Command aliases execute code in the master interpreter when invoked in the slave interpreter. For a discussion of multiple interpreters see the interp manual page included in the Tcl 8.0 distribution.

The configuration management package maintains a list of installed features in cfg::featureList. When a Tclet obtains a policy, the master interpreter attempts to install the features mentioned in cfg::featureList into the interpreter executing the Tclet. For each feature, if the feature is allowed by the policy, it invokes safefeature::feature::install with the name of the interpreter, to install aliases and other resources for that feature. If the install procedure generates an error, the interpreter executing the Tclet is killed, to prevent the Tclet from executing in a potentially unsafe undefined state.

The feature must declare a package named safefeature::feature. This ensures that the feature can be dynamically loaded as needed. The feature's install procedure, as mentioned above, should be implemented in the safefeature::feature namespace. Note that only the install procedure is required to be defined in this namespace. Other aspects of the implementation of the feature can be in other namespaces. This is a hidden internal property of the implementation of each feature.

The implementation of each feature should call safefeature::setup to properly link up with common functionality supplied in the safefeature namespace. By convention, this call is made at the same time as defining the install procedure, to ensure that these capabilities are available when needed.

FEATURE CONTROL

To disable a feature for use in all policies, remove the name of that feature from the value of cfg::featuresList. This variable is defined in the plugin.cfg file in the directory cfg::configDir. If a feature is not mentioned by name in the value of this variable, it is not installed into any Tclet on this site.

Each policy individually enables or disables features in its features section. It is not a good idea to modify the list of features available in a policy, because a Tclet expects to get a predefined set of features when it requests to use a policy.

By convention, the feature implementation files are stored in the utils directory of the plugin installation. See the plugin manual page for a discussion of the plugin runtime library directory tree structure.

To install a new feature, follow these steps:

1
Add its name to the value of cfg::featuresList by editing plugin.cfg in the directory cfg::configDir. Note that the order of appearance in this list is important; features whose name appears later will be installed later into the Tclet, and can undo or modify the effects of installing features that appear earlier in the list.

2
Install the implementation file or files for the feature in the utils directory.

3
Add a package ifneeded statement to the pkgIndex.tcl file in the directory utils for the package declared by the feature. At present you must do this step by hand, because the Tcl code that generates this file does not yet properly handle namespaces.

These built in features (in the order in which they appear in the value of cfg::featuresList) are provided by the Tcl plugin: url, stream, network, persist and unsafe. Each of these features is described in its own manual page with the same name.

SEE ALSO

safe, plugin, policy, config

KEYWORDS

Safe Base, multiple interpreters, configuration management, policy, features, aliases
Tcl Plugin 2.0