Local Sandboxes

This section describes the various local sandboxes into which SWFs are placed.

Privileges

Flash Player defines the following types of privileges for local files:

• Local-read: This privilege is available to local-with-filesystem SWFs but not to local-with-networking SWFs. It includes operations that load data from external files into ActionScript variables, where the data comes from files that reside in local filesystems. Examples of local URL forms are given earlier in the section “What Is Affected.” The affected data-loading operations are as follows:

• XML.load, XML.sendAndLoad
• LoadVars.load, LoadVars.sendAndLoad, loadVariables, loadVariablesNum, MovieClip.loadVariables
• Import of a symbol from another SWF’s Library

• Net-send: This privilege is available to local-with-networking SWFs but not to local-with-filesystem SWFs. This privilege includes operations that send data or requests to Internet locations or HTTP servers. This includes all of the following operations used with non-local URLs:

• XML.load, XML.send, XML.sendAndLoad
• LoadVars.load, LoadVars.send, LoadVars.sendAndLoad, loadVariables, loadVariablesNum, MovieClip.loadVariables
• XMLSocket.connect
• NetConnection.call (Flash Remoting)
• Import of a symbol from another SWF’s Library
• getURL, MovieClip.getURL
• loadMovie, loadMovieNum, MovieClip.loadMovie, MovieClipLoader.loadClip
• Sound.loadSound

• Net-read: Local-with-networking SWFs may perform net-send operations. Some net-send operations are one-way operations, where data is sent but no reply comes back; other net-send operations are requests for which a response is received. These latter operations are called net-read operations, a superset of net-send operations. Local-with-networking SWFs may attempt net-read operations, although permission is required from the data’s origin domain. These are the the following operations, using non-local URLs:

• XML.load, XML.sendAndLoad
• LoadVars.load, LoadVars.sendAndLoad, loadVariables, loadVariablesNum, MovieClip.loadVariables
• XMLSocket.connect
• NetConnection.call (Flash Remoting)
• Import of a symbol from another SWF’s Library

• SWF-HTML: This includes operations that allow SWF files to script HTML files and vice versa. Of the three local sandboxes, only local-trusted files are given the SWF-HTML privilege, due to potential mismatches between the security models of Flash Player and web browsers. These operations include the following:

  

• SWF-to-HTML operations:

  fscommand
   getURL("javascript:...") 
  ExternalInterface.call           

• HTML-to-SWF operations:

  The JavaScript API (SetVariable, GotoFrame, and so on)
  Calling a callback established with ExternalInterface.addCallback

Electing a SWF into the Local-With-Networking Sandbox

A local SWF is placed in this sandbox if it contains a flag called UseNetwork. This flag can be placed in a SWF of any version, although it is meaningful only to Flash Player 8 and later. This flag is established in one of two ways:

• When publishing from Flash 8, in the Publish Settings dialog box, select the Flash tab, find the Local Playback Security option toward the bottom, and choose Access Network Only (see Figure 1).

  

  Figure 1. Setting local playback security to access the network only

• If you do not own Flash 8 or would prefer to work with SWFs after they are published, rather than republishing them, you can use the Flash Local Content Updater, a free command-line utility available for download at macromedia.com. The Local Content Updater can add, remove, or check for the UseNetwork flag, operating on one or many SWFs. The Local Content Updater is available for Windows, Mac OS X, and Linux, and also as source code.

Note that the UseNetwork flag does not affect SWFs that are loaded over HTTP—these are always placed in remote sandboxes—or that have been trusted by the user—these are always placed in the local-trusted sandbox. The UseNetwork flag only affects SWFs that would otherwise be placed in the local-with-filesystem sandbox.

Configuring Files into the Local-Trusted Sandbox

A local SWF (or HTML file) is placed in this sandbox if it falls under a local path that has been designated as trusted in the user’s local configuration. Paths to individual files can be trusted, or directories can be trusted, resulting in all files in each selected directory and any of its subdirectories being trusted. Trust designations can be achieved in two ways:

• Settings Manager: Users can visit the Security panel of the Settings Manager and manually add, edit, or remove trusted paths from a list (see Figure 2).

  

  Figure 2. Security settings in the Flash Player Settings Manager

  Users may also make a global decision about how Flash Player should handle older SWFs (local-with-filesystem SWFs of version 7 and lower) using the “Ask/Allow/Deny” options in this panel. The default here is “Ask,” which fails any prohibited operations but shows the warning dialog box. Choosing “Always allow” instead allows prohibited operations to succeed, thus reverting to the default behavior of Flash Player 7. However, this setting does not affect SWFs of version 8 or higher; it is only intended to affect content that was developed before the newer local rules were made. Choosing “Always deny” causes all prohibited operations to fail without showing the dialog box.

  Note: The Ask/Allow/Deny options govern not only local security prompt situations but also the exact domain match prompt situations that have occurred since Flash Player 7.

• FlashPlayerTrust configuration files: These are simple text files that list trusted paths. They are intended to be created by executable installer programs. When an installer installs SWFs onto a user’s computer, it can install trust configuration files to designate the SWFs as trusted. While this practice does not represent an explicit user decision about each SWF being trusted, the user has implicitly given their trust to the installer program by running it—it is, after all, an executable program. Flash Player recognizes trust configuration files in two locations: one that affects all users of the computer and one that affects only the current user. The all-users location has been chosen to require administrative privileges at the OS level. The locations are as follows:

• Windows all users:

  <system>MacromedFlashFlashPlayerTrust
  

  (e.g. c:WINNTsystem32MacromedFlashFlashPlayerTrust)

• Windows single user:

  <app data>MacromediaFlash Player#SecurityFlashPlayerTrust

  (e.g. c:Documents and SettingsfredApplication DataMacromediaFlash
  Player#SecurityFlashPlayerTrust)

• Mac OS all users:

  <app support>/Macromedia/FlashPlayerTrust
  

  (e.g. /Library/Application Support/Macromedia/FlashPlayerTrust)

• Mac OS single user:

  <app data>/Macromedia/Flash Player/#Security/FlashPlayerTrust
  

  (e.g. /Users/fred/Library/Preferences/Macromedia/Flash
  Player/#Security/FlashPlayerTrust)

These locations are directories, not individual files. Any number of configuration files may be installed in each of these directories; Flash Player will read all files it finds in them. Configuration files may not be placed in subdirectories of FlashPlayerTrust; they must be placed directly in the FlashPlayerTrust directories. The individual configuration files may be given any name but, to avoid naming conflicts, installers should name their configuration files in some way that is specific to their product. The FlashPlayerTrust directories will not necessarily exist on any given system, so installers may need to create them.

The syntax of these files is simple: They contain any number of local paths, one per line. Whitespace and blank lines are allowed. Comments can be included with the # character; these comments go to the end of a line. Quotes are unnecessary (and will cause problems) for paths that contain spaces.

These files contain filesystem paths, which on some users’ computers may include non-ASCII characters, so the text encoding used in FlashPlayerTrust files is significant. Flash Player will look for Unicode byte-order mark characters at the beginnings of these files, and will recognize UTF-8 and UTF-16 byte order marks, treating the rest of the file as UTF-8 or UTF-16 accordingly. (Windows Notepad and Mac TextEdit, for example, can write Unicode text files containing these byte-order mark characters; many other text editors can as well.) If Flash Player does not find a byte-order mark character at the beginning of a FlashPlayerTrust file, it will interpret the file using the current “codepage” (default local encoding) of the computer.

HTML Sandboxes

While we usually speak of SWFs being placed in sandboxes, Flash Player also places HTML files in sandboxes for purposes of controlling SWF-HTML interactions. Local HTML files only have two sandboxes: trusted and untrusted. Local HTML files are untrusted by default, and can be designated as trusted in the same way as SWFs. The sandbox of a local HTML file matters only for HTML-to-SWF scripting, such as with the Flash Player JavaScript API.

Determining a SWF’s Sandbox

A SWF may determine its own sandbox type using the following read-only ActionScript property:

System.security.sandboxType

This property has one of the following four string values:

• “remote”
• “localWithFile”
• “localWithNetwork”
• “localTrusted”

Behavior of Local-With-Filesystem Sandbox

SWFs in the local-with-filesystem sandbox may perform local-read operations but not net-send or SWF-HTML operations.

If you are using a Debug version of Flash Player, and you are connected to the debugger in Macromedia Flash, then whenever a SWF in this sandbox attempts a prohibited operation, you will see a diagnostic message in the Output panel describing the failed operation.

When a user is playing a SWF with a publish version of 7 or earlier in this sandbox, and the SWF attempts a prohibited operation, a security warning dialog box will appear, indicating that the content may have stopped working as intended due to the change in Flash Player 8’s local security rules (see Figure 3).

Figure 3. Security dialog box alerting the user to a stopped operation

This dialog box is shown at most once each time an application runs—subsequent operations will not trigger it but will fail silently instead.

The attempted operation will fail no matter what action the user takes in the dialog box. However, if the user clicks the Settings button, a new window will open displaying the Settings Manager, where the user may opt to trust the local content that attempted the prohibited operation. If the user chooses the Add Location command in the Settings Manager within a short time of seeing the Flash Player Settings Manager in Figure 2, a tip shows the path of the local SWF that attempted the prohibited operation (see Figure 4).

Figure 4. Specifying a trusted location with a “tip” prompt

The user may opt simply to copy this path into the Trust This Location text box, thus trusting the individual SWF that triggered the dialog box. This is sometimes sufficient; however, sometimes an application will consist of multiple files, and it may be necessary to trust more than one file in order to get the application to work as intended. Thus, the user may have to experiment with trusting multiple files or the entire directory containing the SWF that triggered the dialog box.

If the user makes changes in the Settings Manager, they must restart the original application (generally by refreshing their browser) before their changes take effect.

FlashAuthor.cfg

For end users, the local security warning dialog box appears only for SWFs of version 7 and earlier. The dialog box is intended to permit users to fix pre–Flash 8 content that has been affected by the new local security rules.

However, for authors of Flash content, the security warning dialog box may be a helpful indicator of why failures are occurring. Authors may wish to be informed immediately whenever a SWF of any version attempts an operation prohibited by the local security rules.

To support this need, a variety of Macromedia authoring tools, including Macromedia Flash 8, install a file called FlashAuthor.cfg that instructs Flash Player to show the warning dialog box for a prohibited operation by any local-with-filesystem SWF, regardless of version. Any user is free to create this file themselves as well. The file can be placed in either of two locations, each alongside the FlashPlayerTrust directories:

• Windows all users:

  <system>MacromedFlashFlashAuthor.cfg
  

  (e.g. c:WINNTsystem32MacromedFlashFlashAuthor.cfg)

• Windows single user:

  <app data>MacromediaFlash Player#SecurityFlashAuthor.cfg
  

  (e.g. c:Documents and SettingsfredApplication DataMacromediaFlash
  Player#SecurityFlashAuthor.cfg)

• Mac OS all users:

  <app support>/Macromedia/FlashAuthor.cfg
  

  (e.g. /Library/Application Support/Macromedia/FlashAuthor.cfg)

• Mac OS single user:

  <app data>/Macromedia/Flash Player/#Security/FlashAuthor.cfg
  

  (e.g. /Users/fred/Library/Preferences/Macromedia/Flash
  Player/#Security/FlashAuthor.cfg)

Only one directive is currently recognized in this file:

LocalSecurityPrompt=Author

This directive causes Flash Player to ignore SWF version when deciding whether to show the warning dialog box in Figure 3.

FlashAuthor.cfg may also contain whitespace, and comments denoted by the # character, running to the end of the line.

If you are developing SWF content that is designed to play as local files, the LocalSecurityPrompt=Author directive may be undesirable for you because it prevents Flash Player from simulating end-user behavior perfectly. You can disable the author-specific behavior by changing the contents of FlashAuthor.cfg to anything other than LocalSecurityPrompt=Author as shown above. For example, you can comment out the line above, or you can change it to something easy to understand, such as:

LocalSecurityPrompt=User

Note that Macromedia Flash 8 installs FlashAuthor.cfg in both the all-users and single-user locations. When FlashAuthor.cfg is present in both locations, Flash Player honors the copy in the single-user location, so be sure to edit the single-user file.

Behavior of Local-With-Networking Sandbox

SWFs in the local-with-networking sandbox may perform net-send operations but not local-read or SWF-HTML operations.

If you are using a Debug version of Flash Player, and you are connected to the debugger in Flash, then whenever a SWF in this sandbox attempts a prohibited operation, you will see a diagnostic message in the Output panel describing the failed operation.

SWFs in this sandbox will not cause the security warning dialog box to be displayed because there are no situations in which content could have been made before the local security rules were changed, and yet be in the local-with-networking sandbox. From an end-user perspective, all prohibited operations in this sandbox fail silently.

Local-with-networking SWFs may perform net-send operations. Some net-send operations are one-way operations, where data is sent but no reply comes back; other net-send operations are requests for which a response is received. These latter operations are called net-read operations, a superset of net-send operations. An example of a net-read operation is XML.load("http://mysite.com/data/schedule.xml"). Local-with-networking SWFs are permitted to attempt net-read operations. However, in keeping with Flash Player’s global permission principle, in order for a local-with-networking SWF to load data from a given domain, that domain must serve a policy file that authorizes all domains to read the relevant data, stating <allow-access-from domain="*" />. In the above example, mysite.com would need a policy file at either the default location (http://mysite.com/crossdomain.xml) or next to the desired data (http://mysite.com/data/crossdomain.xml). In the latter case, the loading SWF would need to call the following in order to inform Flash Player of the non-default policy file location:

System.security.loadPolicyFile("http://mysite.com/data/crossdomain.xml")