Flash Player Article

Policy file changes in Flash Player 9

Workflows

The following procedures should help you quickly address any issues relating to the policy file changes in Flash Player 9,0,115,0. Adobe recommends using these sections as a reference after reading the corresponding introductory sections earlier in this article.

Using logging

Flash Player 9,0,115,0 introduces policy file logging, a new feature. The policy file log shows messages for every event relating to policy files—attempts to retrieve them, successes and failures in processing them, the fates of the requests that depend on them. A complete reference to the messages you will find in the policy file log can be found in Appendix B.

To use the policy file log:

1. Install a Debug version of Flash Player 9,0,115,0 or later. You can use any type of Flash Player: ActiveX, Plug-In, or Standalone. You can get the Debug version of Flash Player from the Flash Player Support Center's Downloads page.

2. Find the location of your mm.cfg configuration file. This is a general debugging configuration file that Debug versions of Flash Player read on startup. mm.cfg is located in your "home" directory; here are some typical examples:

   Windows: C:\Documents and Settings\username

   Windows Vista: C:\Users\username

   Macintosh and Linux: /home/username

3. Create mm.cfg if it does not exist, then add one or both of the following lines to it:

   PolicyFileLog=1   # Enables policy file logging
   PolicyFileLogAppend=1  # Optional; do not clear log at startup

   If PolicyFileLogAppend is not enabled, each new root-level SWF will clear the log file. If PolicyFileLogAppend is enabled, the previous contents of the log file will always be kept, and the log file will grow at the end.

   If many different root-level SWF files are loaded during your testing, you will probably want to enable PolicyFileLogAppend. However, if you enable PolicyFileLogAppend, you will probably need to manually rename or delete the log file from time to time, since otherwise it will grow enormous, and it will be difficult to determine where previous output ends and new output begins.

4. Find the location where policyfiles.txt, the policy file log, will be written. It will not necessarily exist yet; Flash Player will create it the next time a SWF file is run. You can find policyfiles.txt in the following locations:

   Windows: C:\Documents and Settings\username\Application Data\Macromedia\Flash Player\Logs

   Windows Vista: C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs

   Macintosh: /Users/username/Library/Preferences/Macromedia/Flash Player/Logs (it is unconventional for a program to write log files to the Preferences directory, but that is in fact the case)

   Linux: /home/username/.macromedia/Flash_Player/Logs

5. Run any SWF file in Flash Player, then close Flash Player.
6. You should now see policyfiles.txt in the Logs directory. Verify that it has a recent modification time. Open it and verify that at least one message appears ("Root-level SWF loaded"). If so, policy file logging is working.
7. Visit whatever SWF content you need to test. Run the content through any scenarios that will cause it to encounter policy files. Close Flash Player when you are done.
8. Read policyfiles.txt for information about what occurred with policy files during your test run. If you see messages that aren't clear, see Appendix B.
9. If you find useful information in policyfiles.txt that you need to keep for future reference, rename the log file to something other than policyfiles.txt, or move it to another directory, so that Flash Player will not overwrite the log when it next runs.

Finding and fixing immediate issues

As described in the section on immediate strictness, a few of the changes in Flash Player 9,0,115,0 will affect SWF content immediately, possibly causing undesired behavior in a small percentage of SWF files. If you maintain SWF content, then as soon as possible, you should do the following:

1. Install a Debug version of Flash Player 9,0,115,0 or later. You should use a browser-based version of Flash Player, to simulate your production environment. You can use the ActiveX player or a Plug-In player; either should produce identical results. You can get the Debug version of Flash Player from the Flash Player Support Center's Downloads page.
2. For your testing, try to use a browser that is recent enough to support HTTP response headers for Flash Player, as this will provide a more complete test of immediate issues. See Appendix A for details on which browsers meet this requirement.
3. Enable policy file logging as shown above.
4. Test your SWF content. Try to exercise as much of your content as you can.
5. After you have tested your content, close Flash Player and examine your policy file log. Look for messages in the policy file log that include the label [strict]. This label is an indication of a potential immediate issue.

6. Make a note of any aspect of your content that does not work as you expect it to—such cases may indicate problems that you will need to debug. You should try to correlate such cases with the contents of the policy file log, and you should try to verify that such cases really do behave differently in Flash Player 9,0,115,0, by retesting these cases with an older version of Flash Player. Any cases that do not behave differently between older and newer versions of Flash Player are not issues related to policy file strictness.

   If you need to uninstall Flash Player to downgrade to an older version, use the Flash Player Uninstaller. Due to security features in the ActiveX control, you will need to run the uninstaller using the "/clean" command:

   uninstall_flash_player.exe /clean

   To obtain an earlier version of Flash Player to test with, visit this TechNote: Archived Flash players available for testing purposes.

7. Classify any [strict] messages that you find in your policy file log. These messages can include:

   • Ignoring policy file at (URL) due to incorrect syntax. A malformed policy file is being ignored, possibly causing cross-domain access to be denied. See this log message explanation and the section on malformed policy files.
   • Policy file requested from (URL) redirected to (URL); will use final URL in determining scope. A policy file redirect may be changing the scope of a policy file, possibly causing cross-domain access to be denied. See this log message explanation and the section on within-domain redirects.
   • Ignoring policy file at (URL) due to bad Content-Type '(content-type)'. An HTTP policy file has been received without a required textual Content-Type declared by the server, and will be ignored, possibly causing cross-domain access to be denied. See this log message explanation and the section on the Content-Type whitelist.
   • Ignoring policy file at (URL) due to missing Content-Type. An HTTP policy file has been received without a required textual Content-Type declared by the server, and will be ignored, possibly causing cross-domain access to be denied. See this log message explanation and the section on the Content-Type whitelist.
   • Local socket connection forbidden to host (host) without a socket policy file. SWF content attempted to connect to a socket that is apparently on the local host, but did not refer to the host as localhost. Strict socket rules are being applied immediately, and access is denied. See this log message explanation and the section on immediately strict sockets.

Configuring URL meta-policies

As described in the section on meta-policies, there are two reasons you should choose and declare a meta-policy on an HTTP, HTTPS, or FTP server:

• If your server serves any policy files, and you do not declare a meta-policy permitting those policy files, then they will stop working for users who install a Phase 2 version of Flash Player. Configuring a meta-policy ensures that policy files from your server will smoothly transition for users of Phase 2 versions of Flash Player.
• Whether or not your server deliberately serves policy files, or even any Flash Player compatible content at all, anyone with the ability to create text files on your server can create a policy file, which may then be used to obtain data that is private to your server, your users, or both. Declaring a meta-policy helps ensure that the default meta-policy of all is not applied for users of Phase 1 versions of Flash Player.

If you are operating a site on a server that you do not administer, be sure to read the section on considerations for users of hosted services.

To configure a meta-policy on a server that you control:

1. Familiarize yourself with the basics of meta-policies.

2. Read the list of available meta-policies. Decide which is most appropriate for your server. Some guidelines for HTTP and HTTPS servers (FTP servers are analogous, but slightly different in the details):

   • If you do not expect your server to serve any policy files, choose a meta-policy of none.
   • If your server serves user-defined content, choose a meta-policy strategy that makes it impossible for users to create policy files. This basically means not choosing all, and if you choose by-content-type, this helps ensure that the criteria for assigning a Content-Type of text/x-cross-domain-policy are impossible for user-defined content to satisfy.
   • If you want it to be easy for anyone with upload privileges to your server to be able to create a policy file, choose a meta-policy of all.
   • If you want only a single, master policy file on your server, choose a meta-policy of master-only, and help ensure that only trusted personnel can alter the contents of the master policy file at /crossdomain.xml.

   • If you want to permit non-master policy files at individually approved locations, choose a meta-policy of by-content-type, and assign a Content-Type of text/x-cross-domain-policy for individually specified locations. Here is an example of an Apache configuration snippet to achieve this:

     <Location /crossdomain.xml>
       ForceType text/x-cross-domain-policy
     </Location>
     <Location /another/place/crossdomain.xml>
       ForceType text/x-cross-domain-policy
     </Location>

   • If you want to permit non-master policy files at a predetermined set of locations, for example any file with the name crossdomain.xml, choose a meta-policy of by-content-type, and assign a Content-Type of text/x-cross-domain-policy for any location that meets your criteria. Here is an example of an Apache configuration snippet to achieve this:

     <Files crossdomain.xml>
       ForceType text/x-cross-domain-policy
     </Files>

   • If your server hosts scripts that you do not want to permit to generate policy files, add the special meta-policy none-this-response to the output of any such scripts. Here is an example of an Apache configuration snippet to achieve this:

     <Location /cgi-bin>
       Header set X-Permitted-Cross-Domain-Policies none-this-response
     </Location>

3. Decide whether you will declare your meta-policy using the master policy file or an HTTP response header. (FTP servers must use the master policy file.) Read the section on how to specify meta-policies for advantages and disadvantages of each mechanism.

   1. If you are declaring your meta-policy in the master policy file, write a <site-control> tag into the master policy file at /crossdomain.xml. Here is an example:

      <cross-domain-policy>
        <site-control permitted-cross-domain-policies="by-content-type"/>
      </cross-domain-policy>

   2. If you are declaring your meta-policy in an HTTP response header, configure your server to return the appropriate X-Permitted-Cross-Domain-Policies header. Here is an example of an Apache configuration snippet to achieve this:

      <Location />
      Header set X-Permitted-Cross-Domain-Policies master-only
      </Location>

Special considerations for users of hosted services

If you operate a site on a hosted service, or a server that you otherwise don't entirely control, and you serve policy files:

• If anything stops working with Flash Player 9,0,115,0, follow the workflow for immediate issues. You should be able to correct most problems you find without your server administrator having to do anything.
• In the longer term, you will eventually need to establish a meta-policy, or your policy files will stop working. But you should have many months to get this done. You will probably need your server administrator to adopt a service-wide change that will solve the problem for you and any other customers of the service. It may help to contact your service provider and point them at this article so they can consider making changes.
• If you want to establish a meta-policy sooner (for example, in order to defend your site against rogue policy files), or if a Phase 2 version of Flash Player will soon be released and your service provider has not made any service-wide fixes, you can fix the problem yourself if you have access to the root directory of your site. Follow the workflow for configuring an URL meta-policy. Your options will probably be limited, since you probably won't be able to affect HTTP response headers. Reasonable options are:

Use the following if you only want to use a single policy file on your site:

<site-control permitted-cross-domain-policies="master-only"/>

Use the following if you don't want any restrictions on the creation of policy files on your site:

<site-control permitted-cross-domain-policies="all"/>

Configuring socket policy files

As described in the section on socket policy files, there are two reasons you may want to serve a socket master policy file from port 843 on your host:

• If you maintain any SWF files that make socket connections to your host, and they currently connect without a socket policy file (because they are connecting to their own domain, or because they rely on an HTTP policy file), such SWF files will stop being able to connect for users who install a Phase 2 version of Flash Player. Serving a socket master policy file helps ensure that socket connections to your host will smoothly transition for users of Phase 2 versions of Flash Player. (If you are not sure whether certain SWF content makes socket connections to your host without a socket policy file, test your content while using the policy file log, and look for warnings about deprecated socket configurations.)
• Whether or not your host deliberately serves socket policy files, or even any Flash Player compatible content at all, malicious parties may attempt to make unauthorized socket-level connections to your host using a DNS rebinding attack. Opting into the strict socket rules by serving a socket master policy file helps ensure that users of Phase 1 versions of Flash Player cannot be used as vectors for such an attack.

Serving a socket master policy file is not the only way to address these issues, but it is the easiest and most consistent way to address them. If you find for some reason that serving a master socket policy file from port 843 is impractical, you can address these issues on a port-by-port basis, serving non-master socket policy files from individual ports. But a socket master policy file should address an entire host at once.

To serve a socket master policy file:

1. Review the list of available socket meta-policies, and decide what socket meta-policy is appropriate for your host.

2. Write a socket master policy file, declaring your desired socket meta-policy and any permissions that you wish to grant. Here is an example:

   <cross-domain-policy>
     <site-control permitted-cross-domain-policies="master-only"/>
     <allow-access-from domain="mysite.com" to-ports="999,8080-8082"/>
   </cross-domain-policy>

   Note: Setting up a socket policy file server provides a brief background on the latest Flash Player socket functionality, as well as sample code for creating socket policy file servers in testing environments.

3. Run the socket policy file server on your host, providing it with the socket master policy file you have written.

Page 5 of 7

Previous Page

Next Page