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.
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.
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.