Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > security (System.security) > allowDomain (security.allowDomain method)

allowDomain (security.allowDomain method)

Lets SWF files and HTML files in the identified domains access objects and variables in the SWF file that contains the allowDomain() call.

If two SWF files are served from the same domain -- for example, http://mysite.com/movieA.swf and http://mysite.com/movieB.swf -- then movieA.swf can examine and modify variables, objects, properties, methods, and so on in movieB.swf, and movieB.swf can do the same for movieA.swf. This is called cross-movie scripting or simply cross-scripting.

If two SWF files are served from different domains -- for example, http://mysite.com/movieA.swf and http://othersite.com/movieB.swf -- then, by default, Flash Player does not allow movieA.swf to script movieB.swf, nor movieB.swf to script movieA.swf. A SWF file gives SWF files from other domains permission to script it by calling System.security.allowDomain(). This is called cross-domain scripting. By calling System.security.allowDomain("mysite.com"), movieB.swf gives movieA.swf permission to script movieB.swf.

In any cross-domain situation, two parties are involved, and it's important to be clear about which side is which. For the purposes of this discussion, the side performing the cross-scripting is called the accessing party (usually the accessing SWF), and the other side is called the party being accessed (usually the SWF being accessed). To continue the example, when movieA.swf scripts movieB.swf, movieA.swf is the accessing party, and movieB.swf is the party being accessed.

Cross-domain permissions that are established with System.security.allowDomain() are asymmetrical. In the previous example, movieA.swf can script movieB.swf, but movieB.swf cannot script movieA.swf, because movieA.swf has not called System.security.allowDomain() to give othersite.com permission to script movieA.swf. You can set up symmetrical permissions by having both SWF files call System.security.allowDomain().

In addition to protecting SWF files from cross-domain scripting originated by other SWF files, Flash Player protects SWF files from cross-domain scripting originated by HTML files. HTML-to-SWF scripting can be performed with older Flash browser functions such as SetVariable or callbacks established by using ExternalInterface.addCallback(). When HTML-to-SWF scripting crosses domain boundaries, the SWF file being accessed must call System.security.allowDomain(), just as when the accessing party is a SWF file, or the operation will fail.

Specifying an IP address as a parameter to System.security.allowDomain() does not permit access by all parties that originate at the specified IP address. Instead, it permits access only by parties that were loaded by explicitly specifying that IP address in their URLs, rather than by a domain name that maps to that IP address.

Version-specific differences Flash Player's cross-domain security rules have evolved from version to version. The following table summarizes the differences.

The versions that control the behavior of Flash Player are SWF versions (the published version of a SWF file), not the version of Flash Player itself. For example, when Flash Player 8 is playing a SWF file published for version 7, it applies behavior that is consistent with version 7. This practice ensures that player upgrades do not change the behavior of System.security.allowDomain() in deployed SWF files.

The version column in the previous table shows the latest SWF version involved in a cross-scripting operation. Flash Player determines its behavior according to either the accessing SWF file's version or the version of the SWF file that is being accessed, whichever is later.

The following paragraphs provide more detail about Flash Player security changes involving System.security.allowDomain().

Version 5. No cross-domain scripting restrictions.

Version 6. Cross-domain scripting security is introduced. By default, Flash Player forbids cross-domain scripting; System.security.allowDomain() can permit it. To determine whether two files are in the same domain, Flash Player uses each file's superdomain, which is the exact host name from the file's URL, minus the first segment, down to a minimum of two segments. For example, the superdomain of www.mysite.com is mysite.com. This example would permit SWF files from www.mysite.com and store.mysite.com to script each other without calling System.security.allowDomain().

Version 7. Superdomain matching is changed to exact domain matching. Two files are permitted to script each other only if the host names in their URLs are identical; otherwise, a call to System.security.allowDomain() is required. By default, files loaded from non-HTTPS URLs are no longer permitted to script files loaded from HTTPS URLs, even if the files are loaded from the exactly the same domain. This restriction helps protect HTTPS files, because a non-HTTPS file is vulnerable to modification during download, and a maliciously modified non-HTTPS file could corrupt an HTTPS file, which is otherwise immune to such tampering. System.security.allowInsecureDomain() is introduced to allow HTTPS SWF files that are being accessed to voluntarily disable this restriction, but Adobe recommends against using System.security.allowInsecureDomain().

Version 8. Two major areas of change:

• Calling System.security.allowDomain() now permits cross-scripting operations only if the SWF file being accessed is the SWF file that called System.security.allowDomain(). In other words, a SWF file that calls System.security.allowDomain() now permits access only to itself. In previous versions, calling System.security.allowDomain() permitted cross-scripting operations where the SWF file being accessed could be any SWF file in the same domain as the SWF file that called System.security.allowDomain(). Calling System.security.allowDomain() previously opened up the entire domain of the calling SWF file.
• Support has been added for wildcard values with System.security.allowDomain("*") and System.security.allowInsecureDomain("*"). The wildcard (*) value permits cross-scripting operations where the accessing file is any file at all, loaded from anywhere. Think of the wildcard as a global permission. Wildcard permissions can be useful in general, and in particular they are required to enable certain kinds of operations under the new local file security rules in Flash Player 8. Specifically, for a local SWF file with network-access permissions to script a SWF file on the Internet, the Internet SWF file being accessed must call System.security.allowDomain("*"), reflecting that the origin of a local SWF file is unknown. (If the Internet SWF file being accessed is loaded from an HTTPS URL, the Internet SWF file must instead call System.security.allowInsecureDomain("*").)

Occasionally, you may encounter the following situation: You load a child SWF file from a different domain and want to allow the child SWF file to script the parent SWF file, but you don't know the final domain from which the child SWF file will come. This can happen, for example, when you use load-balancing redirects or third-party servers.

In this situation, you can use the MovieClip._url property as a parameter to this method. For example, if you load a SWF file into the movie clip my_mc, you can call System.security.allowDomain(my_mc._url). If you do this, be sure to wait until the SWF file in my_mc begins loading, because the _url property does not have its final, correct value until this time. The best way to determine when a child SWF file has begun loading is to use MovieClipLoader.onLoadStart.

The opposite situation can also occur; that is, you might create a child SWF file that wants to allow its parent to script it, but doesn't know what the domain of its parent will be. In this situation, call System.security.allowDomain(_parent._url) from the child SWF. You don't have to wait for the parent SWF file to load; the parent will already be loaded by the time the child loads.

If you are publishing for Flash Player 8, you can also handle these situations by calling System.security.allowDomain("*"). However, this can sometimes be a dangerous shortcut, because it allows the calling SWF file to be accessed by any other SWF file from any domain. It is usually safer to use the _url property.

For more information, see the following:

• The Flash Player 9 Security white paper at http://www.adobe.com/go/fp9_0_security
• The Flash Player 8 Security-Related API white paper at http://www.adobe.com/go/fp8_security_apis

Availability: ActionScript 1.0; Flash Player 6 - Behavior changed in Flash Player 7; behavior changed in Flash Player 8.

Parameters

domain1:String - One or more strings that specify domains that can access objects and variables in the SWF file that contains the System.Security.allowDomain() call. The domains can be formatted in the following ways:

• "domain.com"
• "http://domain.com"
• "http://IPaddress"
• (Flash Player 8 only) "*" You can pass a wildcard ("*") to System.security.allowDomain() to allow all domains, including local hosts, access to the calling SWF file. Before using the wildcard, be sure that you want to provide such broad access to the calling SWF file. See the discussion in the main description of this method.

Example

The SWF file located at www.adobe.com/MovieA.swf contains the following lines:

System.security.allowDomain("www.shockwave.com");
loadMovie("http://www.shockwave.com/MovieB.swf", my_mc);

Because MovieA contains the allowDomain() call, MovieB can access the objects and variables in MovieA. If MovieA didn't contain this call, the Flash Player security implementation would prevent MovieB from accessing MovieA's objects and variables.

See also

addCallback (ExternalInterface.addCallback method), onLoadComplete (MovieClipLoader.onLoadComplete event listener), _parent (MovieClip._parent property), _url (MovieClip._url property), allowInsecureDomain (security.allowInsecureDomain method)

Flash CS3