NAME
persist - Local persistent file storage for Safe Tcl.
SYNOPSIS
open fileName ?mode?
close channel
fconfigure channel ?options...?
puts ?-nonewline? ?channelName? string
file arg ?arg...?
seek channel offset ?whence?
tell channel
glob pattern ?pattern...?
DESCRIPTION
PROCEDURES
open fileName ?mode?
close channel
fconfigure channel ?options...?
puts ?-nonewline? ?channel? string
file delete fileName
seek channel offset ?whence?
tell channel
glob pattern ?pattern...?
CONFIGURATION
SECURITY
SEE ALSO
KEYWORDS

NAME

persist - Local persistent file storage for Safe Tcl.

SYNOPSIS

open fileName ?mode?
close channel
fconfigure channel ?options...?
puts ?-nonewline? ?channelName? string
file arg ?arg...?
seek channel offset ?whence?
tell channel
glob pattern ?pattern...?

DESCRIPTION

This manual entry describes the persist feature which provides local persistent storage for programs executing in a Safe-Tcl interpreter. It explains the facilities provided and how to control the operation of this feature through settings in configuration files. This feature is installed into a Safe-Tcl interpreter by a security policy that enables the feature. This policy is called the controlling security policy, below.

The procedures provided by the persist feature are described in the section PROCEDURES. The section CONFIGURATION describes the different aspects of controlling the operation of this feature. The section SECURITY describes the security risks incurred by this feature and how to minimize them through proper configuration.

PROCEDURES

The following procedures are provided in a Tclet by the persist feature when it is installed by a security policy. These procedures are aliases redefining procedures present in Tcl 8.0. See the manual pages for each procedure for a full description of their operation. Here we only survey the limitations placed on their operation by security restrictions implemented by the controlling policy.

open fileName ?mode?
Opens a local persistent file with the name fileName in the requested mode, creates the file if necessary, and returns the name of the channel to this file. Only the last path component of fileName is used; calling open with /my/dirty/laundry.tcl causes it to open a file named laundry.tcl. The mode argument has the same meaning as in the standard Tcl open command. If the limit on the number of open channels or the limit on the number of stored files would be exceeded, the procedure returns an error.

close channel
Closes the channel and if this channel is to a local persistent file, decrements the number of currently open channels to local persistent files. If open was previously returning an error because the limit on the number of concurrently open channels to local persistent files was reached, it will again succeed after this call.

fconfigure channel ?options...?
This procedure is provided to allow a Tclet to configure settings for channels obtained from opening local persistent files as well as from other sources (e.g. the socket command).

puts ?-nonewline? ?channel? string
This is the same as the Safe-Tcl puts command described in the safe manual entry in the Tcl 8.0 distribution, except that it limits the size of local persistent files opened for writing. If channel is open for writing on a local persistent file and writing string to the file would cause it to grow larger than the file size limit imposed by the controlling policy, the procedure returns an error.

file delete fileName
In addition to the options supported by the file command provided in the Safe Base, this procedure allows the Tclet to delete local persistent files by name. For other operations supported by the file command, see the safe manual entry in the Tcl 8.0 distribution.

seek channel offset ?whence?
Moves the access point in channel to a new location as specified by offset and the optional whence argument. See the seek manual page in the Tcl 8.0 distribution for the details. This procedure prevents the seek from increasing the file size beyond the limit specified in the controlling policy's configuration. However, if the file is opened for reading, the Tclet is allowed to seek to all the file even if its current size exceeds the file size limit.

tell channel
Computes the offset of the current access point in channel from the start of the file.

glob pattern ?pattern...?
Like regular Tcl glob, returns the list of the filenames from the local persistent storage area that matches the given patterns.

CONFIGURATION

The persist feature is controlled by settings in the persist section in the configuration for the controlling policy. For an explanation of configurations and policies, see the config and policy manual pages, respectively. The location of these configuration files is governed by the value of ::cfg::configDir, as explained in the plugin manual page.

The storage constant, if defined, names a sub-directory of the persistent local storage area under which directories for Tclets using this policy are created. This allows file sharing between Tclets using the same policy or between Tclets using different policies that specify the same storage root. File sharing is described in the section SECURITY.

The constant openFilesLimit defines the number of concurrent channels that can be opened with open on persistent local files. If that many open channels are in use by a Tclet, further calls to open return an error until one of the open channels is closed with close.

The constant storedFilesLimit defines the number of concurrent local persistent files that can be stored in a directory. If that many files are present in a directory, further attempts to create new files with open return an error until one or more files are deleted with file delete.

The constant fileSizeLimit defines the size, in bytes, of persistent local storage files. If a call to puts or seek would increase the size of a file beyond this limit, an error is returned.

SECURITY

The persist feature allows Tclets to maintain local persistent files on a client's machine. These files persist between invocations of the Tclet. To prevent resource exhaustion attacks by Tclets, the number and size of these files is curtailed by configuration settings in the controlling policy.

A Tclet does not know the location on the file system of the directory used to store its persistent local files. This prevents Tclets from gleaning any information about the structure of the local file system by using the persist feature.

By default, files stored by a Tclet are accessible only in that Tclet and only when it is using the same policy as was used when these files were created. This prevents file sharing between Tclets and between different modes of operation of the same Tclet, and prevents privacy attacks by Tclets. For example, if no preventive measures were taken, a Tclet using a hypothetical localFileAccess policy could copy any local file to a local persistent file; later, when it uses the outside policy, it could copy the file to a remote host using a network socket. Preventing arbitrary file sharing eliminates these privacy attacks.

Sometimes, Tclets must share local persistent files for legitimate purposes, and the owner of the client host wants to allow sharing. By default, the directory name for storing the local persistent files is computed based on the originURL attribute of the Tclet. If the Tclet has set embed_args(prefix) to a proper prefix of the file path portion of this URL, this prefix is used instead to compute the name of the directory. Thus, two Tclets loaded from the same server and with the same protocol can share files by specifying a common prefix of the file path portion in the embed_args(prefix) variable. In the Tcl plugin this array is initialized from the arguments passed in the embed statement that created the Tclet in a web page; the variable can also be set programmatically by a Tclet. For example, suppose two Tclets were loaded from http://www.abc.com/root/def/one.tcl and http://www.abc.com/root/abc/second.tcl. If they both set embed_args(prefix) to root/ then they will both use the same directory to store local persistent files.

If a value is specified for embed_args(prefix) that does not consist of a proper prefix of the file path portion of the URL from which the Tclet was loaded, the whole URL is used to compute the directory name for local persistent files. No error is returned to the Tclet in this case, and the specified prefix is silently ignored (the actual prefix used by persist can be checked by the tclet because embed_args(prefix) is updated in the tclet to show the actual prefix used). In that case the Tclet will still be able to use local persistent files but will not be able to share these files with other Tclets. To avoid typos and errors it is recommended that the tclet computes the prefix from [getattr originPath].

Ordinarily, Tclets using one policy can not share files with Tclets using another policy. This is because the storage areas for the two policies are under different root directories on the local file system. To allow sharing between policies, set the storageRoot in the persist section to some common value. As explained in the CONFIGURATION section, if set, the value of this constant is used as the name of the root directory for storage for a policy. Other policies whose configurations specify the same value for storageRoot use the same storage area for Tclets using these policies. Tclets that specify the same prefix will now be able to share files. See the discussion below for the security risks of allowing this kind of file sharing.

File sharing between Tclets that are using the same policy and that were loaded from the same host may seem relatively safe, but you should carefully consider the risks. Information may unintentionally be shared amongst Tclets if a Tclet specifies a prefix that causes sharing with Tclets that it does not necessarily trusts. Tclets should examine the setting of embed_args(prefix) and modify it before invoking the policy command to ensure that only intended sharing occurs. Because the embed statement in a page can refer to a Tclet from a different author, it is not necessarily true that the author of the Tclet and the author of the web page trust each other. Thus, the web page may specify a prefix in the embed statement that will fool the Tclet into unintentional and unsafe sharing of its files with other Tclets.

File sharing between Tclets that are using different policies, even when they are loaded from the same host, is even more risky. This kind of sharing opens the possibility of privacy attacks on the client host where the Tclet executes by collaborating Tclets. One Tclet may store information obtained from a local resource accessible when using a certain policy, and the other Tclet (or even the same Tclet) could leak the information to a service executing on a remote host when using another policy. For example, this kind of attack is possible when file sharing is allowed between policies that allow connections to remote services using the url or network features. For this reason, file sharing between policies is disabled by default. It should probably never be enabled for policies that also enable features such as url or network, because these features allow the Tclet to connect to disparate remote services and resources.

Resource attacks can be mounted by a Tclet to exhaust the local storage space if the Tclet can cause execution of other Tclets. This attack is possible even though none of the collaborating Tclets exceeds its own storage space allocation. For example, if the Tclet also has access to the url feature it can use ::browser::displayURL to display pages that contain other Tclets.

SEE ALSO

safe, policy, config, open, seek, tell, close, file, url, network

KEYWORDS

Deleting, file sharing, files, local persistent storage, input, output, seeking, telling