The Browser Plugin and Safe-Tcl

21.3 Writing Tclets

This section brings together some bits of information about the interpreter that runs tclets and the global variables available to them. Emphasis is on what makes conditions different than with a normal Tk interpreter. Most of what you need to know about writing a tclet is covered in the first twenty chapters of this book. The actual mechanism for creating the interpreter that runs a tclet is described in the next section.

All tclets begin execution in the Safe Base interpreter which is a version of Tk that lacks access to the following commands and library procedures.

   bell           cd             clipboard      exec           fconfigure
   glob           grab           history        load           menu
   open           pwd            selection      socket         source
   tcl_TraceProc  tk_changeColor tk             tk_getOpenFile tk_getSaveFile
   tk_messageBox  vwait

(This list includes some commands and procedures that are not discussed in this book.)

In addition, the Safe Base interpreter provides modified versions of the following Tcl commands:

   exit        file        load        source      tclPkgUnknown

The modifications remove potentially dangerous capabilities.

Finally, the Safe Base interpreter contains a couple of extra commands: getattr and policy.

The getattr command can be used as follows.

getattr VARIABLE_NAME

It returns the value of VARIABLE_NAME which may be a browser-related variable such as originURL, originHomeDirURL, originPath, or originSocketHost. A list of such browser-related variables can be found in the plugin page of the plugin's on-line manual. The four mentioned give, respectively, the URL that actually fetched the tclet, the directory part of that URL, the path part of that URL (that is, the part after the host name/port and before the final file name), and the host name used for connecting back to the tclet's host. Variables whose values are available through getattr cannot be changed by a tclet.

If a tclet is to use any of the resources made available by the features described in the previous section, it must run under an appropriate security policy. This it does by executing

policy POLICY_NAME

which will either terminate with an error or return POLICY_NAME. In the latter case, the interpreter executing the tclet has been upgraded in a way that is consistent with the named policy. This will happen if the tclet is authorized to use the policy. If the tclet is already running under the policy, then POLICY_NAME is also returned. If, however, the tclet is not authorized to run under the policy or it is already running under a different policy, an error is generated. Each tclet is permitted to run under at most one policy per execution.

As described above in The Tcl/Tk Plugin, a tclet with the ability to use persistent storage has a limited ability to modify the directory where its files are stored. The particular storage directory that a tclet can use is a function of a policy name and a URL path. The policy name is determined by the security policy under which the tclet executes. The URL path is a prefix of the URL from which the tclet was downloaded. This prefix is determined by a global variable, embed_args(prefix). This variable contains only the part of the URL path which the tclet can change – that to the right of the part identifying the server and port.

For example, if the tclet is obtained from

http://www.mapfree.com:80/sbf/tcl/book/safeTk.tcl

then the default value of embed_args(prefix) initially will be

sbf/tcl/book/safeTk.tcl

Changing embed_args(prefix) before requesting a security policy will affect the directory used for persistent storage. The value you assign to embed_args(prefix) must be a subpath of originPath. If it is not, it will be ignored. If it is, then the directory chosen by the plugin for persistent storage will be the same as for any other tclet that successfully assigns the same value to embed_args(prefix).

For example, assume that two tclets are loaded respectively from the following URLs.

http://www.benign.org/a/b/c/tclet1.tcl
http://www.benign.org/a/b/tclet2.tcl

If both tclets begin this way

set embed_args(prefix) www.benign.org/a
policy home

then both will share the same directory for persistent storage. If one of them ran under a policy different than home, this would not be true.

Author's Home Page

Order from Amazon.