Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 20.  Safe-Tk and the Browser Plugin

Configuring Security Policies

There are three aspects to the plugin security policy mechanism: policies, features, and trust maps. A policy is an umbrella for a set of features that are allowed for certain Tclets based on the trust map. A feature is a set of commands and aliases that are defined for a safe interpreter that requests a policy. The trust map is kind of filter based on the URL of the Tclet. In the future, trust may bet determined by digital signatures instead of URLs. The trust map determines if a Tclet can request a given policy.


Security Policies are configured for each client.

Remember that the configuration files affect the client machine, which is the workstation that runs the Web browser. If you create Tclets that require custom security policies, you have the burden of distributing the configuration files to clients that will use your Tclets. You also have the burden of convincing them your security policy is safe!

The config/plugin.cfg File

The main configuration file is the config/plugin.cfg file in the plugin distribution. This file lists what features are supported by the plugin, and it defines the URL filters for the trust map.

The configuration file is defined into sections with a section command. The policies section defines which Tclets can use which security policies. For example, the default configuration file contains these lines in the policies section:

section policies
    allow home
    disallow intercom
    disallow inside
    disallow outside
    disallow trusted
    allow javascript ifallowed trustedJavaScriptURLS \

This configuration grants all Tclets the right to use the home policy, disallows all Tclets from using the intercom, inside, outside, and trusted policies, and grants limited access to the javascript policy.

If you are curious, the config files are almost Tcl, but not quite. I lost an argument about that one, so these are stylized configuration files that follow their own rules. For example, the originURL variable is not defined in the config file, but is a value that is tested later when the Tclet is loaded. I'll just give examples here and you can peer under the covers if you want to learn how they are parsed.

The ifallowed clause depends on another section to describe the trust mapping for that policy. For the javascript policy, the config/plugin.cfg file contains:

section trustedJavascriptURLs
    allow http://sunscript.sun.com:80/plugin/javascript/*

Unfortunately this server isn't running anymore, so you may want to add the Scriptics web server to your own configuration:

   allow http://www.scriptics.com:80/plugin/javascript/*

You can use a combination of allow and disallow rules in a section. The arguments to allow and disallow are URL string match patterns, and they are processed in order. For example, you could put a liberal allow rule followed by disallow rules that restrict access, or vice versa. It is probably safest to explicitly list each server that you trust.

Policy Configuration Files

Each security policy has a configuration file associated with it. For example, the outside policy uses the file outside.cfg file in the config directory. This file specifies what hosts and ports are accessible to Tclets using the outside policy. For the inside and outside policies, the configuration files are similar in spirit to the safesock array used to configure the Safesock security policy shown on page 286. There are a set of allowed hosts and ports, and a set of excluded hosts. The excluded hosts are an exception list. If a host matches the include set but also matches the exclude set, it is not accessible. There is an include and exclude set for URLs that affect browser::geturl. The settings from the Tempfile policy shown on page 288 are also part of the home, inside, and outside configuration files. The configuration files are well commented, and you should read through them to learn about the configuration options for each security policy.

Security Policy Features

The aliases that make up a security policy are organized into sets called features. The features are listed in the main config/plugin.cfg configuration file:

variable featuresList {url stream network persist unsafe}

In turn, each security policy configuration file lists what features are part of the policy. For example, the config/home.cfg file lists these features:

section features
    allow url
    allow network
    allow persist unless {[string match {UNKNOWN *}\
        [getattr originURL]]}

Each feature is implemented in a file in the safetcl directory of the distribution. For example, the url feature is implemented in safetcl/url.tcl. The code in these files follows some conventions in order to work with the configuration mechanism. Each one is implemented inside a namespace that is a child of the safefeature namespace (e.g., safefeature::url). It must implement an install procedure that is called to initialize the feature for a new Tclet. It is inside this procedure that the various allow/disallow rules are checked. The cfg::allowed command supports the rule language used in the .cfg files.

Creating New Security Policies

This book does not describe the details of the configuration language or the steps necessary to create a new security policy. There are several manual pages distributed with the plugin that explain these details. They can be found on the web at:


If you are serious about tuning the existing security policies or creating new ones, you should read the existing feature implementations in detail. As usual, modifying a working example is the best way to proceed! I think it is a very nice property of the plugin that its security policies are implemented in Tcl source code that is clearly factored out from the rest of the Tcl/Tk and plugin implementation.

      Previous section   Next section