Security Restrictions for LocalConnections

A LocalConnection object allows two Macromedia Flash movies to communicate with each other, even when they are not located in the same instance of Macromedia Flash Player—for example, when the two movies are in separate browser windows. LocalConnection objects have been available since Macromedia Flash Player 6.

A movie calls LocalConnection.send to initiate a remote procedure call over a LocalConnection. When a movie calls LocalConnection.send and there is a receiver for the specified channel, Macromedia Flash Player checks whether the domain of the sender matches the domain of the receiver. If so, the call proceeds.

A movie may also call LocalConnection.domain to determine its own domain.

Applying the New Rules

Macromedia Flash Player 7 requires that a LocalConnection sender must come from exactly the same domain as the receiver. In addition, movies that are served over nonsecure protocols, such as HTTP, may not make LocalConnection calls to movies that are served over HTTPS (conversely, HTTPS movies may make LocalConnection calls to HTTP movies).

These new rules apply only when any of the movies is made for Macromedia Flash Player 7 or later. If both movies are made for Macromedia Flash Player 6, Flash Player uses the old rules, even in Macromedia Flash Player 7. The older rules permit a movie to make a LocalConnection call to any movie from the same superdomain and permit HTTP movies to make LocalConnection calls to HTTPS movies.

In Macromedia Flash Player 7, when a movie made for Macromedia Flash Player 6 calls LocalConnection.domain, the return value is the movie’s superdomain. When a movie made for Macromedia Flash Player 7 or later calls LocalConnection.domain, the return value is the movie’s exact domain.

Note that there is one aspect of LocalConnections that continues to use superdomains, even for movies made for Macromedia Flash Player 7 and later: the domain in a channel name. A channel name is simply the name that a listener connects with and that a sender uses to identify a listener to send to. When a Macromedia Flash movie calls LocalConnection.connect with a channel name that begins with an underscore, Macromedia Flash Player uses the channel name exactly as provided, without regard to domain. However, for channel names that do not begin with an underscore, there is an implicit domain name added to the beginning of the channel name. For example, when a listener from www.mysite.com calls the following:

receiving_lc.connect( "myChannel" );

The channel name becomes mysite.com:myChannel. If a sender from www.mysite.com or store.mysite.com calls:

sending_lc.send( "myChannel", "methodName" );

Macromedia Flash Player sends the call to the channel, mysite.com:myChannel, which corresponds to the listener’s connect() call above. The only time when a movie must add a domain name to a channel name is when it sends to a listener outside its own superdomain. In that case, the sender must explicitly specify the domain and channel name. If a sender from www.anothersite.com were to send to the listener above, here is the syntax you would use:

sending_lc.send( "mysite.com:myChannel", "methodName" );

In this situation, be aware that you should use the listener’s superdomain, not the listener’s exact domain.

Granting LocalConnection Permissions

If you have movies that you will serve from different domains, and you want those movies to be able to make LocalConnection calls to each other, grant cross-domain LocalConnection permissions. Do this by implementing an event handler called allowDomain on your LocalConnection listener. The LocalConnection.allowDomain handler has existed since Macromedia Flash Player 6 but it behaves slightly differently in Macromedia Flash Player 7.

Say you have a movie at http://www.mysite.com/controller.swf that must make a LocalConnection call to another movie loaded from http://utility.flashutils.com/helper.swf. You would use the following ActionScript in helper.swf:

receiving_lc.allowDomain = function ( domain )
 { 
   if ( domain == "www.mysite.com" || domain == this.domain() )
    {
       return true;
    }
    else
    {
       return false;
    } 
}; 

Note that the domain expected by that code is the exact domain of the caller, www.mysite.com. It is typical for the allowDomain handler to work this way in Macromedia Flash Player 7. However, this is different from the way the allowDomain handler worked in Macromedia Flash Player 6. At that time, it used superdomains. To preserve backward compatibility in Macromedia Flash Player 7, if the LocalConnection caller and the LocalConnection listener are both version 6, the argument for LocalConnection.allowDomain is the caller’s superdomain:

receiving_lc.allowDomain = function ( domain )
 {
    if ( domain == "mysite.com" || domain == this.domain() )
    { 
      return true;
    } 
   else
    {
       return false; 
   } 
}; 

When a LocalConnection listener appears in a movie made for Macromedia Flash Player 6, Flash Player uses its allowDomain handler for all LocalConnection calls, even when the listener is in an HTTPS movie and the caller is not. However, when a listener appears in an HTTPS movie made for Macromedia Flash Player 7 or later, and a caller makes a LocalConnection call in a non-HTTPS movie, the listener must implement a new handler called LocalConnection.allowInsecureDomain or else Flash Player will not permit the call. This is similar to adding System.security.allowInsecureDomain in Macromedia Flash Player 7 (see the section Granting Cross-Movie Scripting Permissions earlier).

Here is an example:

receiving_lc.allowInsecureDomain = function ( domain )
 {
    if ( domain == "mysite.com" || domain == this.domain() )
    {
       return true;
    }
    else
    {
       return false;
    }
 }; 

Macromedia does not recommend implementing LocalConnection.allowInsecureDomain because allowing non-HTTPS documents to access HTTPS documents can compromise the security offered by HTTPS. It is preferable that you serve over HTTPS all Flash movies that make LocalConnection calls to HTTPS movies. However, if using HTTPS for all your movies is prohibitively expensive or impractical, LocalConnection.allowInsecureDomain will override the Macromedia Flash Player default HTTPS protection.