Safe-Tcl - url manual page

The url 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 url feature adds aliases to a Safe-Tcl interpreter to allow it to fetch URLs over a network, post to forms, display the contents of URLs and responses from forms, and to show a status message in the hosting application's status bar.

The procedures that are provided by the url feature are described in the sections PROCEDURES and CALLBACKS, and the settings that control the behavior of these procedures at runtime are explained in the CONFIGURATION section. The SECURITY section discusses the risks associated with this feature and how to minimize them through proper configuration.

PROCEDURES

The url feature provides several aliases to an interpreter into which the feature is installed. Some of these take callbacks as arguments; the exact syntax and semantics of these callbacks is explained in the next section, titled CALLBACKS.

For those operations taking URLs as arguments, the requested URL must be allowed in the urls section of the controlling policy's configuration. All procedures that accept URL arguments internally canonicalize these URLs, to remove .. in the path specification and prevent other attempts to access resources outside those allowed by the controlling policy. See the manual page for each policy and the config manual page for details on configuration management, as well as the section CONFIGURATION below. If the requested URL is disallowed, the operation returns an error.

::browser::status message: The message, a string of any length, is displayed in the status bar of the hosting application. In the Tcl plugin, the message appears in the hosting browser's status bar window at the bottom of the browser window. Some applications may at various times replace the displayed message with new information as significant events occur. The status bar is shared among all sub-systems running within the application and the message posted with ::browser::status may be replaced by another sub-system at any time.
::browser::getURL URL ?timeOut? ?newCallback? ?writeCallback? ?endCallback?: This procedure fetches the contents of a URL URL and calls various callbacks during the operation. If no endCallback was given, the operation blocks until the complete contents of URL have been fetched or until the operation is aborted or times out. The optional timeOut argument specifies a length of time in milliseconds to wait or block before timing out. If no timeout is given, a default timeout is used. The optional newCallback argument specifies a callback to call when the contents of URL start to arrive from the network. The optional writeCallback argument specifies a callback to call each time a part of the contents of URL arrives from the network. The optional endCallback argument specifies a callback to call when the entire contents of URL have arrived, or when the operation is aborted or times out. Thus, when the data starts to arrive, the newCallback is called once, then for each subsequent part of the data writeCallback is called, and finally endCallback is called once. If no data ever arrives, endCallback is guaranteed to be called when the operation times out. If the call is blocking, it returns the data fetched from URL. If the call is non-blocking, it returns endCallback.
::browser::displayURL URL frame: Displays the contents of URL in a frame frame. This operation may create new top level frames in the hosting application. The operation is asynchronous and the invoking interpreter does not have access to the contents of URL. Several frame names have special meaning: _self and _current cause the hosting application to replace the contents of the frame containing the Tclet with the result. _blank always create new frames to display the result. _top causes the hosting application to replace the contents of the top-most frame in an application-specific hierarchy to be replaced with the result. _parent is the parent frame.
::browser::getForm URL data ?raw? ?timeOut? ?newCallback? ?writeCallback? ?endCallback?: This procedure posts data to a remote service identified by URL and receives the result. If raw is zero or ommitted, the data is taken to be unprotected and it is encoded to protect special characters such as spaces during transmission; in that case, data should be a list of alternating field names and values. If raw is non-zero, the data is taken to already be encoded. The optional timeOut, newCallback, writeCallback and endCallback arguments have the same meaning as in ::browser::getURL. The operation is blocking if no endCallback is given and returns the result of posting the data to the form. If the operation is non-blocking then endCallback.
::browser::displayForm URL frame data ?raw?: This procedure posts data to a remote service identified by URL and displays the result in a frame frame. The raw argument has the same meaning as for ::browser::getForm. The special frame names described that can be used in ::browser::displayURL have the same meaning for ::browser::displayForm.

CALLBACKS

The url feature defines several non-blocking procedures that retrieve the contents of URLs or the results of computations by remote services.

newCallback name stream URL mimeType lastModified size: The newCallback callback is invoked to inform a Tclet that data is starting to arrive for the requested URL. This URL may have been requested in a call to ::browser::getURL or ::browser::getForm. The name argument is the name of the Tclet that issued the request that generates this stream, and the stream argument contains the name of the new stream. The mimeType indicates the mime type associated with the data, and the expected size of the data is size bytes. The lastModified argument contains the time at which the document was last modified, in seconds since midnight, January 1, 1970.
writeCallback name stream size data: The writeCallback callback is invoked repeatedly as parts of the data for stream arrive. The name of the requesting Tclet is passed in the name argument, and the size in bytes of the current part of the data is passed in size.
endCallback name stream reason data: The endCallback callback is invoked when all the data has arrived on stream, the operation that caused the stream to be sent has timed out, or the operation was cancelled or caused an error. The exact reason for calling endCallback is passed in reason; it is one of the strings EOF, NETWORK_ERROR, USER_BREAK or TIMEOUT. The name of the Tclet that requested this stream is name, and whatever data was received until the callback is invoked is passed in data.

CONFIGURATION

The configuration options for the url feature are contained in the configuration for the controlling policy, in the section urls and frames. The urls section contains allow and disallow statements that define exactly what URLs are allowed in procedures such as ::browser::getURL. The frames section specifies which frames are allowed in procedures such as ::browser::displayURL. The configuration variable maxFrames controls the global total number of frames that the tclets can access. 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.

For example, the following urls section from the configuration file for the home policy only allows URLs if they refer to resources on the same server and in the same directory as the file from which the Tclet was loaded:

section urls
allow   $originHomeDirURL*

If a procedure is not allowed in the aliases section of the controlling policy's configuration, it is not installed into a Tclet using the policy. This allows a policy fine control over the use of individual aliases provided by each feature.

SECURITY

This feature enables a Tclet to fetch the contents of URLs and to post data to remote services via the HTTP network protocol. This can be used to leak private information which belongs to the hosting site to remote sites. A Tclet may also attempt to harm the user's reputation by posting data to remote services, to make it appear that the user is making bogus or objectionable submissions. Careful control over the set of accessible URLs limits the potential for privacy and reputation attacks by a Tclet. Consideration must also be given to the combination of this feature with other features, especially the network feature, to eliminate unintentional information leaks.

The url feature also allows a Tclet to display a status message in the hosting application's status bar. This can be used to harm the reputation of the user, or for annoyance attacks.

KEYWORDS

configuration, Safe Base, Safe-Tcl, aliases, multiple interpreters, policy, URLs, posting, status messages

Tcl Plugin 2.0