The Flash Player client run-time security model has been designed around resources, which are objects such as SWF files, local data, and Internet URLs. Stakeholders are the parties who own or use those resources. Stakeholders can exercise controls (security settings) over their own resources, and each resource has four stakeholders. Flash Player strictly enforces a hierarchy of authority for these controls, as the following illustration shows:

This means, for instance, that if an administrator restricts access to a resource, no other stakeholders can override that restriction.

Administrator, user, and website controls are detailed in the following sections. Author (developer) settings are described in the rest of this chapter.

Subtopics

• Administrative user controls
• User controls
• Website controls (cross-domain policy files)
• Author (developer) controls

Administrative user controls

An administrative user of a computer (a user who has logged in with administrative rights) can apply Flash Player security settings that affect all users of the computer. In a nonenterprise environment, such as on a home computer, there is usually one user who also has administrative access. Even in an enterprise environment, individual users may have administrative rights to the computer.

There are two types of administrative user controls:

• The mms.cfg file
• The Global Flash Player Trust directory

The mms.cfg file

On Mac OS X systems, the mms.cfg file is located at /Library/Application Support/Macromedia/mms.cfg. On Microsoft Windows systems, the file is located in the Macromedia Flash Player folder in the system directory (for example, C:\windows\system32\macromed\flash\mms.cfg on a default Windows XP or Windows Vista installation).

When Flash Player starts, it reads its security settings from this file, and uses them to limit functionality.

The mms.cfg file includes settings that the administrator uses to perform the following tasks:

• Data loading--Restrict the reading of local SWF files, disable file downloading and uploading, and set the storage limit for persistent shared objects.
• Privacy controls--Disable microphone and camera access, prevent SWF files from playing windowless content, and prevent SWF files in a domain that does not match the URL displayed in a browser window from accessing persistent shared objects.
• Flash Player updates--Set the interval for checking for an updated version of Flash Player, specify the URL to check for Flash Player update information, specify the URL from which to download updated versions of Flash Player, and disable automatic updates of Flash Player entirely.
• Legacy file support--Specify whether older-version SWF files should be placed in the local-trusted sandbox.
• Local file security--Specify whether local files can be placed in the local-trusted sandbox.
• Full-screen mode--Disable full-screen mode.

A SWF file can access some information on capabilities that have been disabled by calling the Capabilities.avHardwareDisable and Capabilities.localFileReadDisable properties. However, most of the settings in the mms.cfg file cannot be queried from ActionScript.

To enforce application-independent security and privacy policies for a computer, the mms.cfg file should be modified only by system administrators. The mms.cfg file is not for use by application installers. While an installer running with administrative privileges could modify the contents of the mms.cfg file, Adobe considers such usage a violation of the user's trust and urges creators of installers never to modify the mms.cfg file.

The Global Flash Player Trust directory

Administrative users and installer applications can register specified local SWF files as trusted. These SWF files are assigned to the local-trusted sandbox. They can interact with any other SWF files, and they can load data from anywhere, remote or local. Files are designated as trusted in the Global Flash Player Trust directory, which is in the same directory as the mms.cfg file, in the following locations (locations are specific to the current user):

• Windows: system\Macromed\Flash\FlashPlayerTrust

  (for example, C:\windows\system32\Macromed\Flash\FlashPlayerTrust)

• Mac: app support/Macromedia/FlashPlayerTrust

  (for example, /Library/Application Support/Macromedia/FlashPlayerTrust)

The Flash Player Trust directory can contain any number of text files, each of which lists trusted paths, with one path per line. Each path can be an individual SWF file, HTML file, or directory. Comment lines begin with the # symbol. For example, a Flash Player trust configuration file containing the following text grants trusted status to all files in the specified directory and all subdirectories:

# Trust files in the following directories:
C:\Documents and Settings\All Users\Documents\SampleApp

The paths listed in a trust configuration file should always be local paths or SMB network paths. Any HTTP path in a trust configuration file is ignored; only local files can be trusted.

To avoid conflicts, give each trust configuration file a filename corresponding to the installing application, and use a .cfg file extension.

As a developer distributing a locally run SWF file through an installer application, you can have the installer application add a configuration file to the Global Flash Player Trust directory, granting full privileges to the file that you are distributing. The installer application must be run by a user with administrative rights. Unlike the mms.cfg file, the Global Flash Player Trust directory is included for the purpose of installer applications granting trust permissions. Both administrative users and installer applications can designate trusted local applications using the Global Flash Player Trust directory.

There are also Flash Player Trust directories for individual users (see the next section, User controls).

User controls

Flash Player provides three different user-level mechanisms for setting permissions: the Settings UI, the Settings Manager, and the User Flash Player Trust directory.

The Settings UI and Settings Manager

The Settings UI is a quick, interactive mechanism for configuring the settings for a specific domain. The Settings Manager presents a more detailed interface and provides the ability to make global changes that affect permissions for many or all domains. Additionally, when a new permission is requested by a SWF file, requiring run-time decisions concerning security or privacy, dialog boxes are displayed in which users can adjust some Flash Player settings.

The Settings Manager and Settings UI provide the following security-related options:

• Camera and microphone settings--The user can control Flash Player access to the camera and microphone on the computer. The user can allow or deny access for all sites or for specific sites. If the user does not specify a setting for all sites or a specific site, a dialog box is displayed when a SWF file attempts to access the camera or microphone, letting the user choose whether or not to allow the SWF file to access the device. The user can also specify the camera or microphone to use, and can set the sensitivity of the microphone.
• Shared object storage settings--The user can select the amount of disk space that a domain can use to store persistent shared objects. The user can make these settings for any numbers of specific domains, and can specify the default setting for new domains. The default limit is 100 KB of disk space. For more information on persistent shared objects, see the SharedObject class in the ActionScript 3.0 Language and Components Reference.

For details on the Settings Manager, see www.adobe.com/go/settingsmanager.

The User Flash Player Trust directory

Users and installer applications can register specified local SWF files as trusted. These SWF files are assigned to the local-trusted sandbox. They can interact with any other SWF files, and they can load data from anywhere, remote or local. A user designates a file as trusted in the User Flash Player Trust directory, which is in same directory as the Flash shared object storage area, in the following locations (locations are specific to the current user):

• Windows: app data\Macromedia\Flash Player\#Security\FlashPlayerTrust

  (for example, C:\Documents and Settings\JohnD\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust on Windows XP or C:\Users\JohnD\AppData\Roaming\Macromedia\Flash Player\#Security\FlashPlayerTrust on Windows Vista)

• Mac: app data/Macromedia/Flash Player/#Security/FlashPlayerTrust

  (for example, /Users/JohnD/Library/Preferences/Macromedia/Flash Player/#Security/FlashPlayerTrust)

These settings affect only the current user, not other users who log in to the computer. If a user without administrative rights installs an application in their own portion of the system, the User Flash Player Trust directory lets the installer register the application as trusted for that user.

As a developer distributing a locally run SWF file by way of an installer application, you can have the installer application add a configuration file to the User Flash Player Trust directory, granting full privileges to the file that you are distributing. Even in this situation, the User Flash Player Trust directory file is considered a user control, because a user action (installation) initiates it.

There is also a Global Flash Player Trust directory, used by the administrative user or installers to register an application for all users of a computer (see Administrative user controls).

Website controls (cross-domain policy files)

To make data from a web server available to SWF files from other domains, you can create a cross-domain policy file on your server. A cross-domain policy file is an XML file that provides a way for the server to indicate that its data and documents are available to SWF files served from certain domains or from all domains. Any SWF file that is served from a domain specified by the server's policy file is permitted to access data or assets from that server.

Cross-domain policy files affect access to a number of assets, including the following:

• Data in bitmaps, sounds, and videos
• Loading XML and text files
• Access to socket and XML socket connections
• Importing SWF files from other security domains into the security domain of the loading SWF file

Full details are provided in the rest of this chapter.

Policy file syntax

The following example shows a policy file that permits access to SWF files that originate from *.example.com, www.friendOfExample.com and 192.0.34.166:

When a SWF file attempts to access data from another domain, Flash Player automatically attempts to load a policy file from that domain. If the domain of the SWF file that is attempting to access the data is included in the policy file, the data is automatically accessible.

By default, policy files must be named crossdomain.xml and must reside in the root directory of the server. However, a SWF file can check for a different name or in a different directory location by calling the Security.loadPolicyFile() method. A cross-domain policy file applies only to the directory from which it is loaded and to its child directories. So a policy file in the root directory applies to the whole server, but a policy file loaded from an arbitrary subdirectory applies only to that directory and its subdirectories.

A policy file affects access only to the particular server on which it resides. For example, a policy file located at https://www.adobe.com:8080/crossdomain.xml will apply only to data- loading calls made to www.adobe.com over HTTPS at port 8080.

A cross-domain policy file contains a single tag, which in turn contains zero or more tags. Each tag contains an attribute, domain, which specifies either an exact IP address, an exact domain, or a wildcard domain (any domain). Wildcard domains are indicated by either a single asterisk (*), which matches all domains and all IP addresses, or an asterisk followed by a suffix, which matches only those domains that end with the specified suffix. Suffixes must begin with a dot. However, wildcard domains with suffixes can match domains that consist of only the suffix without the leading dot. For example, foo.com is considered to be part of *.foo.com. Wildcards are not allowed in IP domain specifications.

If you specify an IP address, access is granted only to SWF files loaded from that IP address using IP syntax (for example, http://65.57.83.12/flashmovie.swf), not those loaded using domain-name syntax. Flash Player does not perform DNS resolution.

You can permit access to documents originating from any domain, as shown in the following example:

Each tag also has the optional secure attribute, which defaults to true. You can set the attribute to false if your policy file is on an HTTPS server, and you want to allow SWF files on a non-HTTPS server to load data from the HTTPS server.

Setting the secure attribute to false could compromise the security offered by HTTPS. In particular, setting this attribute to false opens secure content to snooping and spoofing attacks. Adobe strongly recommends that you not set the secure attribute to false.

If data to be loaded is on a HTTPS server, but the SWF file loading it is on an HTTP server, Adobe recommends that you move the loading SWF file to an HTTPS server so that you can keep all copies of your secure data under the protection of HTTPS. However, if you decide that you must keep the loading SWF file on an HTTP server, add the secure="false" attribute to the tag, as shown in the following code:

A policy file that contains no tags has the same effect as not having a policy on a server.

Socket policy files

ActionScript objects instantiate two different kinds of server connections: document-based server connections and socket connections. ActionScript objects like Loader, Sound, URLLoader, and URLStream instantiate document-based server connections, and these each load a file from a URL. ActionScript Socket and XMLSocket objects make socket connections, which operate with streaming data, not loaded documents. Flash Player supports two kinds of policy files: document-based policy files and socket policy files. Document-based connections require document-based policy files, while socket connections require socket policy files.

Flash Player requires that a policy file be transmitted using the same kind of protocol that the attempted connection wishes to use. For example, when you place a policy file on your HTTP server, SWF files from other domains are allowed to load data from it as an HTTP server. However, by not providing a socket policy file at the same server, you are forbidding SWF files from other domains to connect to the server at the socket level. The means by which a socket policy file is retrieved must match the means of connecting.

A policy file served by a socket server has the same syntax as any other policy file, except that it must also specify the ports to which it grants access. When a policy file comes from a port number that is less than 1024, it may grant access to any ports; when a policy file comes from port 1024 or higher, it may only grant access to ports 1024 and higher. The allowed ports are specified in a to-ports attribute in the tag. Single port numbers, port ranges, and wildcards are accepted values.

Here is an example XMLSocket policy file:

When policy files were first introduced in Flash Player 6, there was no support for socket policy files. Connections to socket servers were authorized by a policy file from the default location of the cross-domain policy file on an HTTP server on port 80 of the same host as the socket server. To make it possible to preserve existing server arrangements, Flash Player 9 still supports this capability. However, Flash Player's default is now to retrieve a socket policy file on the same port as the socket connection. If you wish to use an HTTP-based policy file to authorize a socket connection, you must explicitly request the HTTP policy file using code such as the following:

Security.loadPolicyFile("http://socketServerHost.com/crossdomain.xml")

In addition, in order to authorize socket connections, an HTTP policy file must come only from the default location of the cross-domain policy file, and not from any other HTTP location. A policy file obtained from an HTTP server implicitly authorizes socket access to all ports 1024 and above; any to-ports attributes in an HTTP policy file are ignored.

For more information on socket policy files, see Connecting to sockets.

Preloading policy files

Loading data from a server or connecting to a socket is an asynchronous operation, and Flash Player simply waits for the cross-domain policy file to finish downloading before it begins the main operation. However, extracting pixel data from images or extracting sample data from sounds is a synchronous operation--the cross-domain policy file must load before you can extract data. When you load the media, you need to specify that it check for a cross-domain policy file:

• When using the Loader.load() method, set the checkPolicyFile property of the context parameter, which is a LoaderContext object.
• When embedding an image in a text field using the tag, set the checkPolicyFile attribute of the tag to "true", as in the following: .
• When using the Sound.load() method, set the checkPolicyFile property of the context parameter, which is a SoundLoaderContext object.
• When using the NetStream class, set the checkPolicyFile property of the NetStream object.

When you set one of these parameters, Flash Player first checks for any policy files that it already has downloaded for that domain. Then it considers any pending calls to the Security.loadPolicyFile() method to see if they are in scope, and waits for those if they are. Then it looks for the cross-domain policy file in the default location on the server.

Author (developer) controls

The main ActionScript API used to grant security privileges is the Security.allowDomain() method, which grant privileges to SWF files in the domains that you specify. In the following example, a SWF file grants access to SWF files served from the www.example.com domain:

Security.allowDomain("www.example.com")

This method grants permissions for the following:

• Cross-scripting between SWF files (see Cross-scripting)
• Display list access (see Traversing the display list)
• Event detection (see Event security)
• Full access to properties and methods of the Stage object (see Stage security)

The primary purpose of calling the Security.allowDomain() method is to grant permission for SWF files in an outside domain to script the SWF file calling the Security.allowDomain() method. For more information, see Cross-scripting.

Specifying an IP address as a parameter to the Security.allowDomain() method does not permit access by all parties that originate at the specified IP address. Instead, it permits access only by a party that contains the specified IP address as its URL, rather than a domain name that maps to that IP address. For example, if the domain name www.example.com maps to the IP address 192.0.34.166, a call to Security.allowDomain("192.0.34.166") does not grant access to www.example.com.

You can pass the "*" wildcard to the Security.allowDomain() method to allow access from all domains. Because it grants permission for SWF files from all domains to script the calling SWF file, use the "*" wildcard with care.

ActionScript includes a second permission API, called Security.allowInsecureDomain(). This method does the same thing as the Security.allowDomain() method, except that, when called from a SWF file served by a secure HTTPS connection, it additionally permits access to the calling SWF file by other SWF files that are served from an insecure protocol, such as HTTP. However, it is not a good security practice to allow scripting between files from a secure protocol (HTTPS) and those from insecure protocols (such as HTTP); doing so can open secure content to snooping and spoofing attacks. Here is how such attacks can work: since the Security.allowInsecureDomain() method allows access to your secure HTTPS data by SWF files served over HTTP connections, an attacker interposed between your HTTP server and your users could replace your HTTP SWF file with one of their own, which can then access your HTTPS data.

Another important security-related method is the Security.loadPolicyFile() method, which causes Flash Player to check for a cross-domain policy file at a nonstandard location. For more information, see Website controls (cross-domain policy files).