Website controls (policy files)



To make data from your web server available to SWF files from other domains, you can create a policy file on your server. A policy file is an XML file placed in a specific location on your server.

Policy files affect access to a number of assets, including the following:

  • Data in bitmaps, sounds, and videos

  • Loading XML and text files

  • Importing SWF files from other security domains into the security domain of the loading SWF file

  • Access to socket and XML socket connections

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 objects load a file from a URL. ActionScript Socket and XMLSocket objects make socket connections, which operate with streaming data, not loaded documents.

Because Flash Player supports two kinds of server connections, there are two types of policy files—URL policy files and socket policy files.
  • Document-based connections require URL policy files. These files let the server indicate that its data and documents are available to SWF files served from certain domains or from all domains.

  • Socket connections require socket policy files, which enable networking directly at the lower TCP socket level, using the Socket and XMLSocket classes.

Flash Player requires policy files to be transmitted using the same protocol that the attempted connection wants 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, if you don’t 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. In other words, the means by which a policy file is retrieved must match the means of connecting.

Policy file usage and syntax are discussed briefly in the rest of this section, as they apply to SWF files published for Flash Player 10. (Policy file implementation is slightly different in earlier versions of Flash Player, as successive releases have strengthened Flash Player security.) For more detailed information on policy files, see the Flash Player Developer Center topic “Policy File Changes in Flash Player 9” at www.adobe.com/go/devnet_security_en.

Master policy files

By default, Flash Player (and AIR content that is not in the AIR application sandbox) first looks for a URL policy file named crossdomain.xml in the root directory of the server, and looks for a socket policy file on port 843. A file in either of these locations is called the master policy file. (In the case of socket connections, Flash Player also looks for a socket policy file on the same port as the main connection. However, a policy file found on that port is not considered a master policy file.)

In addition to specifying access permissions, the master policy file can also contain a meta-policy statement. A meta-policy specifies which locations can contain policy files. The default meta-policy for URL policy files is “master-only,” which means that /crossdomain.xml is the only policy file allowed on the server. The default meta-policy for socket policy files is “all,” which means that any socket on the host can serve a socket policy file.

Note: In Flash Player 9 and earlier, the default meta-policy for URL policy files was “all,” which means that any directory can contain a policy file. If you have deployed applications that load policy files from locations other than the default /crossdomain.xml file, and those applications might now be running in Flash Player 10, make sure you (or the server administrator) modify the master policy file to allow additional policy files. For information on how to specify different a different meta-policy, see the Flash Player Developer Center topic “Policy File Changes in Flash Player 9” at www.adobe.com/go/devnet_security_en.

A SWF file can check for a different policy filename or a different directory location by calling the Security.loadPolicyFile() method. However, if the master policy file doesn’t specify that the target location can serve policy files, the call to loadPolicyFile() has no effect, even if there is a policy file at that location. Call loadPolicyFile() before attempting any network operations that require the policy file. Flash Player automatically queues networking requests behind their corresponding policy file attempts. So, for example, it is acceptable to call Security.loadPolicyFile() immediately before initiating a networking operation.

When checking for a master policy file, Flash Player waits three seconds for a server response. If a response isn’t received, Flash Player assumes that no master policy file exists. However, there is no default timeout value for calls to loadPolicyFile(); Flash Player assumes that the file being called exists, and waits as long as necessary to load it. Therefore, if you want to make sure that a master policy file is loaded, use loadPolicyFile() to call it explicitly.

Even though the method is named Security.loadPolicyFile(), a policy file isn’t loaded until a network call that requires a policy file is issued. Calls to loadPolicyFile() simply tell Flash Player where to look for policy files when they are needed.

You can’t receive notification of when a policy file request is initiated or completed, and there is no reason to do so. Flash Player performs policy checks asynchronously, and automatically waits to initiate connections until after the policy file checks have succeeded.

The following sections contain information that applies only to URL policy files. For more information on socket policy files, see Connecting to sockets.

URL policy file scope

A URL policy file applies only to the directory from which it is loaded and to its child directories. A policy file in the root directory applies to the whole server; 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 applies only to data- loading calls made to www.adobe.com over HTTPS at port 8080.

Specifying access permissions in a URL policy file

A policy file contains a single <cross-domain-policy> tag, which in turn contains zero or more <allow-access-from> tags. Each <allow-access-from> 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 in one of two ways:
  • By a single asterisk (*), which matches all domains and all IP addresses

  • By 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, xyz.com is considered to be part of *.xyz.com. Wildcards are not allowed in IP domain specifications.

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

<?xml version="1.0"?> 
<cross-domain-policy> 
    <allow-access-from domain="*.example.com" /> 
    <allow-access-from domain="www.friendOfExample.com" /> 
    <allow-access-from domain="192.0.34.166" /> 
</cross-domain-policy>

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). Access isn’t granted to SWF files 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:

<?xml version="1.0"?> 
<!-- http://www.foo.com/crossdomain.xml --> 
<cross-domain-policy> 
<allow-access-from domain="*" /> 
</cross-domain-policy>

Each <allow-access-from> tag also has the optional secure attribute, which defaults to true. 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, you can set the attribute to false.

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 an 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. Doing so lets you 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 <allow-access-from> tag, as shown in the following code:

<allow-access-from domain="www.example.com" secure="false" /> 
Another element you can use to permit access is the allow-http-request-headers-from tag. This element grants a client hosting content from another permission domain to send user-defined headers to your domain. While the <allow-access-from> tag grants other domains permission to pull data from your domain, the allow-http-request-headers-from tag grants other domains permission to push data to your domain, in the form of headers. In the following example, any domain is permitted to send the SOAPAction header to the current domain:
<cross-domain-policy> 
    <allow-http-request-headers-from domain="*" headers="SOAPAction"/> 
</cross-domain-policy>

If the allow-http-request-headers-from statement is in the master policy file, it applies to all directories on the host. Otherwise, it applies only to the directory and subdirectories of the policy file that contains the statement.

Preloading policy files

Loading data from a server or connecting to a socket is an asynchronous operation. Flash Player simply waits for the 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 policy file must load before you can extract data. When you load the media, specify that it check for a 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 <img> tag, set the checkPolicyFile attribute of the <img> tag to "true", as in the following:

    <img checkPolicyFile = "true" src = "example.jpg">
  • 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 looks for the policy file in the default location on the server, checking both for <allow-access-from> statements and for the presence of a meta-policy. Finally, it considers any pending calls to the Security.loadPolicyFile() method to see if they are in scope.