Security Restrictions for Data Loading

This section describes the only change that can prevent existing Macromedia Flash content from working as intended.

The security restrictions affect all data-loading operations:

• loadVariables, loadVariablesNum, MovieClip.loadVariables, LoadVars.load, LoadVars.sendAndLoad
• XML.load, XML.sendAndLoad
• XMLSocket.connect
• Symbol importing from runtime shared libraries
• Flash Remoting (NetServices.createGatewayConnection)

In Macromedia Flash Player 7, these operations will fail under the following conditions:

• When they reference a URL that is outside the exact domain of the movie that makes a request
• When they reference an HTTPS URL where the movie that makes the request is not served over HTTPS

For most of these operations, the new rules apply regardless of the movie’s published version. For runtime shared libraries, however, the new rules apply only if either the importing movie or library movie (or both) are made for Macromedia Flash Player 7.

Fallback Dialog Box

If a movie made for Macromedia Flash Player 6 or earlier makes a forbidden data-loading request, and the request would have been permitted in Flash Player 6, the request does not completely fail. Instead, Flash Player displays a dialog box to the user (see Figure 1).

Figure 1. On the left is an exact-domain example; on the right is an HTTP/HTTPS example. If a movie made for Macromedia Flash Player 6 or earlier makes a forbidden data-loading request that would have been permitted in version 6, Macromedia Flash Player 7 displays this dialog box.

If the user clicks Allow, the request succeeds. If the user clicks Deny, the request fails. If the movie that makes the request is too small to display the dialog box (if the movie is smaller than 215 x 138 pixels), the dialog box does not appear and Macromedia Flash Player acts as though the user had clicked Deny.

If the user selects “Never ask again,” Macromedia Flash Player remembers their answer and applies it to all movies that prompt the dialog box, even those movies that are too small to display the dialog box.

Determining If the New Restrictions Affect Your Movies

For movies that are 215 x 138 pixels or larger, test your movie using Macromedia Flash Player 7. If the new rules adversely affect your movie, the above dialog box will appear.

However, if you have at some time chosen “Never ask again,” or if your movie is smaller than 215 x 138 pixels, the dialog box will not appear. In these situations, you can do the following:

1. Install a Debug version of a Macromedia Flash Player 7 browser player (plug-in or ActiveX control).
2. Determine the logging location for Macromedia Flash Player. In Mac OS X, the logging location is /Library/Application Support/Macromedia. In Mac Classic, it is Application Support:Macromedia under your System folder. In Windows, the location varies and your HOMEDRIVE and HOMEPATH environment variables determine the location. Go to a command prompt and type echo %HOMEDRIVE% and echo %HOMEPATH%.
3. Create a text file in this directory called mm.cfg. Write the following line in this file:

   SecurityDialogReportingEnable = true

4. Test your movie in a browser.
5. Look for a file alongside mm.cfg called flashlog.txt. If this file does not exist, the new rules do not affect your movie. If flashlog.txt exists, open it. If your movie is affected, a line similar to the following will appear in the file:

   Legacy domain match encountered - http://www.mysite.com/myMovie.swf is trying to access http://store.mysite.com/anotherMovie.swf

Fixing Problems in Your Existing Movies

Once you determine that exact domain matching affects one of your existing movies, you can easily make your movie function again as intended. Create a policy file on the server that your movie is trying to access. Read more about policy files in the next section.

Here is a brief overview of the steps:

1. Determine the server from which your movie is trying to load data. Follow the steps in the previous section about mm.cfg to identify a particular server. In the example in that section, the server was store.mysite.com. If your movie accesses an XMLSocket server, you must create the policy file on an HTTP server on port 80 of the same domain as the XMLSocket server. You can tell when your movie accesses an XMLSocket server because the dialog box reports “[domain]:[port]” instead of just “[domain]” and flashlog.txt reports “[domain]:[port]” instead of a full URL.
2. Create a file in the document root directory of the server and name it crossdomain.xml.
3. Copy the following text into crossdomain.xml:

   <cross-domain-policy>
      <allow-access-from domain="" />
    </cross-domain-policy> 

4. For the value of the domain attribute in the <allow-access-from> tag, enter the exact domain of the movie making the request. In our example, that domain would be www.mysite.com.
5. If the HTTPS restriction affects your movie—that is, a non-HTTPS server serves the movie, but the movie downloads data from an HTTPS server—add the secure="false" attribute to your <allow-access-from> tag, as in the following example:
   <allow-access-from domain="www.mysite.com" secure="false" />
6. If you have movies from additional domains that must access the server where you have created the policy file, add an <allow-access-from> tag for each necessary domain.
7. If you have other servers that your movies access to load data, create a policy file for each of those servers.

After you follow these steps, all problems with your existing movies should be resolved. The remainder of this article applies only to new movies targeting Macromedia Flash Player 7 or to older movies that you are upgrading for Macromedia Flash Player 7.

Writing Policy Files for New Movies

Policy files are a great tool for solving problems with existing content, as you saw above. But that isn’t their only purpose. Policy files are a general-permission mechanism, a way for a server to declare that the documents it serves should be available to Macromedia Flash movies from certain domains, or from all domains. If you’re familiar with the System.security.allowDomain method in ActionScript, think of policy files as an equivalent mechanism, but one that governs data-loading operations, rather than ActionScript access between movies.

For example, policy files can be useful when you have a public XML feed that describes transit timetables or the contents of a weblog. By creating an all-domains policy file, you enable any Flash developer to create Macromedia Flash movies that load your XML data directly without requiring any kind of server-side proxy.

Policy File Basics

Whenever Macromedia Flash Player 7 detects an out-of-domain data-loading request, the player tries to find a policy file on the server from which it attempts to load data. If a policy file exists and it grants access to the origin domain of the Macromedia Flash movie making the request, then the operation succeeds.

Flash Player can find a policy file in two ways:

• A movie can tell the player where to find a policy file by calling System.security.loadPolicyFile
• The player can look in the default location, /crossdomain.xml.

Compare the two techniques in the table below:

It is easier to use the default location technique for the following reasons:

• It opens up the entire server.
• It is compatible with all versions of Flash Player 7 and above.
• It doesn’t require movies to say anything about policy files.

However, sometimes you may find it inconvenient to place a file in a root location on your server, or you may need to serve a policy file from an XMLSocket server. In these cases, you should use the loadPolicyFile technique.

Call System.security.loadPolicyFile to specify the location of a policy file for Flash Player. Thereafter, the Flash Player will use that policy file whenever your movie makes a data-loading request for a URL that falls within the scope of the policy file—that is, when the data-loading URL matches the policy file URL up to and including the directory in which the policy file resides. You can make multiple calls to System.security.loadPolicyFile, and their scopes may even overlap; the Flash Player will always allow a request as long as one or more in-scope policy files permit it. The Flash Player will always wait for any pending loadPolicyFile downloads to complete before accepting or rejecting a data-loading request; therefore, you may call loadPolicyFile immediately followed by your data-loading request without worrying about asynchronous timing. (One exception, however, is runtime shared libraries; see below.) As a final fallback, if you make a data-loading request that any already-loaded policy file cannot authorize, the Flash Player will attempt to retrieve a policy file from the default location, /crossdomain.xml.

Here is an example of calling loadPolicyFile:

System.security.loadPolicyFile( "http://www.mysite.com/flash/myPolicy.xml");
    loadVariablesNum( "http://www.mysite.com/flash/vars/myVars.txt",5);

Note that the above policy file authorizes the retrieval of data from any URLs that begin with http://www.mysite.com/flash/, but not from other areas of www.mysite.com.

A default policy file must reside at the location /crossdomain.xml—that is the only location that Macromedia Flash Player checks automatically. You must place a default policy file in the root directory of the server’s document space and you must name it crossdomain.xml.

A policy file controls access for the server it resides upon, no matter how a movie contacts that server. The same policy file can handle requests to a variety of different URLs that resolve to the same server. For example, a Flash movie might try to load data from your server based on its IP address, any of several domain names that resolve to the same server, or different protocols (such as HTTP and HTTPS) that are actually handled by the same server.

Normally, Macromedia Flash Player looks for a default policy file on the server where the movie requests data. There is one exception, however. When a movie attempts to connect to an XMLSocket outside its domain, and there is no xmlsocket:// policy file to authorize the connection (see below), Macromedia Flash Player looks for a policy file on an HTTP server on port 80 in the domain where the request attempts the connection.

Policy files work for any version of Macromedia Flash movies. However, policy files are only effective when you play movies in Macromedia Flash Player 7.

Macromedia Flash Player will ignore any policy file that is served using a cross-domain redirect. For example, if the Macromedia Flash Player request for http://www.mysite.com/crossdomain.xml redirects to http://elsewhere.mysite.com/crossdomain.xml, Flash Player will ignore that policy file. Be sure not to use cross-domain redirects to serve policy files. (Redirects within the same domain are allowed.)

The security fallback dialog box (discussed earlier) only appears when a movie made for Macromedia Flash Player 6 or earlier tries a cross-domain operation that Flash Player 6 would have allowed and when a policy file doesn’t exist on the server providing the data. In other words, as soon as you provide a policy file on a server, users will no longer see the fallback dialog box when movies attempt to download data from that server. Don’t use the dialog box to let users override the Macromedia Flash security model; it is only intended to permit older movies to continue working until their maintainers have a chance to create policy files. Once there is a policy file, the dialog box is no longer necessary: The policy file either authorizes the operation or it doesn’t. The dialog box never appears for movies made for Macromedia Flash Player 7 because you’re developing and testing those movies in situations where the new, stricter security rules are already understood and where you’re putting policy files in place before you deploy the movies.

If you call loadPolicyFile, ensure that you call it prior to any operations that require the policy file you are loading. This can be especially tricky when you are using loadPolicyFile to authorize cross-domain RSLs (runtime-shared libraries). You must call loadPolicyFile at least one frame before the first time you use a symbol from the RSL. For example, let’s say you have a movie at http://www.mysite.com/myMovie.swf, and in myMovie.swf at frame 15, you import a symbol called airplane_mc from http://www.myothersite.com/assets/airplane.swf, and you have a policy file at http://www.myothersite.com/assets/policy.xml. You must be sure that you call System.security.loadPolicyFile( "http://www.myothersite.com/assets/policy.xml") in the actions for frame 14 or earlier. This means that it is impossible to use loadPolicyFile to authorize usage of symbols in frame 1; the earliest you could use RSL symbols, authorized by loadPolicyFile, is in frame 2; you would have to call loadPolicyFile in frame 1.

Policy File Syntax

Policy files must be in XML format. You may include XML comments:

<!-- comment -->

Policy files always consist of a single <cross-domain-policy> tag that includes zero or more <allow-access-from> tags. Each <allow-access-from> tag has one required attribute, called domain, which specifies a domain from which you want to permit access. The value of domain can be any of the following:

• An exact domain name, such as www.mysite.com.
• An exact IP address, such as 65.57.83.12. This only gives movies access when they are explicitly loaded from that IP address. It does not give movies access when they load using domain names that just happen to resolve to that IP address.
• A wildcard domain name, such as *.mysite.com. These wildcards must always begin with an asterisk followed by a dot, and they must not contain asterisks anywhere except at the beginning. The characters after the dot are the suffix that matches. The wildcard *.mysite.com permits access to Flash movies loaded from any domain that ends in .mysite.com, such as www.mysite.com, store.mysite.com, or longer.subdomain.mysite.com. As a special case, the wildcard also permits the domain mysite.com—that is, without the subdomain.
• A pure wildcard: * (a single asterisk). This allows access from all domains and IP addresses.

Each <allow-access-from> tag may contain the secure attribute, which has two possible values, true and false. The default value is true. When you specify secure="false", you allow access by movies served over protocols other than HTTPS. This only affects policy files that reside on HTTPS servers.

Macromedia recommends against using secure="false" because allowing non-HTTPS documents to access HTTPS data can compromise HTTPS security. Instead, Macromedia recommends that you serve over HTTPS all Flash movies that require access to HTTPS data. However, if using HTTPS for all of your documents is prohibitively expensive or impractical, secure="false" will override Macromedia Flash Player’s default HTTPS protection.

If a policy file has no <allow-access-from> tags, it serves as an explicit deny-all policy file. The only difference between a deny-all policy file and no policy file at all is that movies made for Macromedia Flash Player 6 or earlier won’t display the fallback dialog box when they try to load data from a server that has a deny-all policy file.

Here is an example of a policy file:

<?xml version="1.0"?>
 <!DOCTYPE cross-domain-policy SYSTEM 
     "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
 <!-- Policy file for http://www.mysite.com -->
 <cross-domain-policy>
    <allow-access-from domain="*.mysite.com" />
    <allow-access-from domain="www.myothersite.com" />
 </cross-domain-policy>

XMLSocket Policy Files

Prior to version 7r19, XMLSockets suffered from two security limitations. First, policy files authorizing XMLSocket operations could only come from an HTTP server on port 80 in the same domain as the XMLSocket server. This is sometimes inconvenient, because sometimes you may have an XMLSocket server in a domain where there is no reason to set up an HTTP server, except to serve policy files. Secondly, XMLSocket connections have historically been limited to server ports of 1024 and above. You can overcome both of these limitations, however, using XMLSocket policy files.

Starting with version 7r19, the Flash Player supports the ActionScript API System.security.loadPolicyFile. There is a special syntax you can use to retrieve a policy file directly from an XMLSocket server:

System.security.loadPolicyFile("xmlsocket://socks.mysite.com:123");

mySocket.connect("socks.mysite.com", 456);

With this command, Flash Player will attempt to connect to an XMLSocket server at socks.mysite.com, port 123, and download an XMLSocket policy file. This policy file may permit XMLSocket connections to all ports on the XMLSocket server or only to certain ports. If the policy file permits access from the origin domain of the movie, and includes port 456 in the range of ports available to that domain, then the XMLSocket.connect request above will succeed.

A policy file served by an XMLSocket 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 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 <allow-access-from> tag. Single port numbers, port ranges, and wildcards are accepted values. Here is an example XMLSocket policy file:

<?xml version="1.0"?>
 <!DOCTYPE cross-domain-policy SYSTEM 
      "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
 <!-- Policy file for xmlsocket://socks.mysite.com -->

<cross-domain-policy> 
    <allow-access-from domain="*" to-ports="507" /> 
    <allow-access-from domain="*.mysite.com" to-ports="507,516" /> 
    <allow-access-from domain="*.myothersite.com" to-ports="516-523" /> 
    <allow-access-from domain="www.myothersite.com" to-ports="507,516-523" />  
   <allow-access-from domain="www.mysite.com" to-ports="*" /> 
 </cross-domain-policy> 

A policy file obtained from the default location ( /crossdomain.xml on an HTTP server on port 80) implicitly authorizes XMLSocket access to all ports 1024 and above. There is no way to retrieve a policy file to authorize XMLSocket operations from any other location on an HTTP server; any custom locations for XMLSocket policy files must be on an XMLSocket server.

To connect an XMLSocket to a port lower than 1024, you must always first load a policy file with loadPolicyFile, even when your movie connects to its own exact domain.

Here is the sequence of how the player downloads XMLSocket policy files:

1. Upon establishing a connection with the specified port, the Flash Player transmits <policy-file-request/>, terminated by a null byte.
2. You may configure an XMLSocket server to serve both policy files and normal XMLSocket connections over the same port, in which case, the server should wait for <policy-file-request/> before transmitting a policy file.
3. You may also set up a server to serve policy files over a separate port from normal connections, in which case, it may send a policy file as soon as the player establishes a connection on the dedicated policy file port.
4. The server must send a null byte to terminate a policy file and may then close the connection; if the server does not close the connection, the Flash Player will do so upon receiving the terminating null byte.

If you are using a third-party XMLSocket server, check with your server vendor to see if your server includes support for policy files, or if a future release will add support for policy files.

Are Policy Files Safe?

Policy files grant cross-domain permissions. They permit operations that would not be permitted by default. It is important to understand what a policy file enables, rather than simply regarding the default rules as a barrier and creating a policy file that accomplishes your task without considering the consequences.

When you specify a domain in a policy file, you declare that you are willing to allow the operators of any servers in that domain to obtain any document on the server where the policy file resides. Often this is exactly what you want. For example, if you serve only public documents from a particular server, you should have no qualms about who can obtain documents on that server because anyone can simply visit your server and download files they want. In this situation, it is safe to open your server to all domains:

<allow-access-from domain="*" />

On the other hand, if you serve private documents or anything that requires some form of authentication, such as a password, or if your server is behind a firewall, where only certain users can access it, then it is risky to put a public policy file on that server. Doing so would enable Macromedia Flash movies to download documents from your server whenever they run on the computers of users that your server trusts. These Macromedia Flash movies could potentially reveal private data from your server to people whom you do not trust.

If you need to create a policy file in such a situation, it is best to permit access for domains that you specifically know need access. For example, if you run a server at bigbang.staticland.net that provides XML data and you serve Macromedia Flash movies from www.bigbang-corp.com, which needs to load the XML data, put a policy file on bigbang.staticland.net that enables access specifically from www.bigbang-corp.com.

If you run a server that serves especially sensitive documents and you know there are no Macromedia Flash movies under your control that need to access those documents, it is safest to create a deny-all policy file on that server:

<cross-domain-policy>

</cross-domain-policy>