Update 4/30/2008:
NOTE: Flash Player 9.0.124 includes updates that affect the use of crossdomain policy files. For more information, see the Policy file changes in Flash Player 9 article in the Adobe Developer Connection.

Cross-domain RSLs can be used by applications in any domain or sub-domain. The benefits of cross-domain RSLs are the same as standard RSLs, but they are not restricted to being in the same domain as the application that loads them. This lets you use the same RSL in multiple applications that are in different domains.

To use a cross-domain RSL that is located on a remote server, the remote server must have a crossdomain.xml file that allows access from the application's domain. The easiest way to do this is to add a crossdomain.xml file to the server's root. To ensure that applications from any domain can access the RSL SWF file, you can use an open crossdomain.xml file such as the following:

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

This is not a best practice, however, because it allows requests from any domain to load the RSL, and other assets, from your server. You should instead restrict requests to only those domains that you trust by narrowing the entries in the domain attribute. For more information, see Using cross-domain policy files.

You can store the crossdomain.xml file anywhere on the target server. When you compile a cross-domain RSL, you can specify the location of the crossdomain.xml file, and the application will look to that location to get permission to load the RSL. If you do not specify the location of the crossdomain.xml file when you compile your application, the application looks in the server's root directory by default.

Cross-domain RSLs can fail to load into a Flex application under the following conditions:

• The server on which the RSL is located fails
• The network fails, so remote files cannot be loaded
• The digest of the RSL when the application was compiled does not match the digest of the RSL when it is loaded
• The crossdomain.xml file is absent from the RSL's server

Cross-domain RSLs support a backup mechanism where a failover RSL can be loaded in the case of a server failure. If the server on which the main RSL fails, Flash Player will try to load a failover RSL whose location you specify when you compile the application.

About RSL digests

To ensure that the cross-domain RSL is coming from the trusted party, Flash Player reads the bytes of the incoming RSL and computes a one-way hash, or digest. The digest must match the digest that was stored in the application at compile time when the application was linked to the cross-domain RSL. If the RSL's digest matches the known digest, then Flash Player loads the cross-domain RSL. If the digests do not match, Flash Player displays an error message and does not load the RSL.

You can also use digests for standard RSLs. This is useful if you update your RSLs frequently, and want to ensure that the application loads the latest RSL.

To create a digest while compiling a library, you set the compute-digest compiler option to true. You can set this value in the flex-config.xml file, as the following example shows:

<compute-digest>true</compute-digest>

The default value of the compute-digest option is true.

In Flex Builder, to disable digests, you must add the following to the Additional Compiler Arguments field in the Flex Library Compiler dialog box:

-compute-digest=false

The compiler writes the digest inside the swc/library/libraries/digests element of the RSL's catalog.xml file. The following example shows the structure of digest elements, which are optional children of the digests element in the catalog.xml file:

<digests>
    <digest type="SHA-256" signed="true"
        value="d604d909d8d6d358097cf2f4ebf4707faf330469ed6b41dcdc5aaf6f4dd3bea9"   />
    <digest type="SHA-256" signed="false"
        value="d604d909d8d6d358097cf2f4ebf4707faf330469ed6b41dcdc5aaf6f4dd3bea9"   />
</digests>

The following table describes the tag and its attributes:

When you compile your production application with an RSL that uses a digest for verification, set the verify-digests compiler option to true to indicate that the application must check the digest before using the RSL. The default value of this option is true.

If you have multiple RSLs, such as a main RSL plus a failover RSL, the compiler stores multiple digests inside the application.

The Flex compiler uses the SHA-256 digest algorithm from the java.security libraries to generate the digest.

About failover

The failover feature is used for two reasons:

• If the Flash Player is not at least version 9.0.115 and it tries to load a signed RSL, it will attempt to load the failover RSL
• If a network or server failure occurs while loading the main RSL, Flash Player will attempt to load the failover RSL

For framework RSLs, you typically specify a signed RSL as the main RSL, and an unsigned RSL as the failover RSL. When loading an application that uses signed framework RSLs, older versions of Flash Player skip the signed RSL and attempt to load the failover RSL, which is typically an unsigned RSL.

For all RSLs, the failover RSL provides a mechanism to load an RSL if the primary server is unavailable.

You can specify the location of the RSL and a failover RSL in your flex-config.xml file or on the command line as parameters to the runtime-shared-library-path option. The default failover RSL is framework_3.0.${build.number}.swf. In Flex Builder, you can add failover RSLs by adding them to the Deployment Paths in the Library Path Item Options dialog box.

Compiling applications with standard and cross-domain RSLs

Compiling your application with standard or cross-domain RSLs is easier to do in Flex Builder than it is on the command line. Flex Builder can automatically extract the RSL SWF file for you during the compilation process, and use that SWF to compile your application against. If you use the command-line compiler, then you must extract this file from the SWC file yourself prior to deployment. In either case, when you deploy the RSL SWF file, you should optimize it as described in Optimizing RSL SWF files.

Compile with standard or cross-domain RSLs in Flex Builder

1. Open your Flex application's project.
2. Select Project > Properties.
3. Select Flex Build Path in the option list. The Flex Build Path settings appear.
4. Select the Library Path tab:

   

5. Click the Add SWC button. The Add SWC dialog box appears.

   

6. Enter the path to the SWC file or click the Browse button to find the SWC file.
7. Click OK to add the SWC file to your project's library path. Flex Builder adds the new SWC file to the list of SWC files in the Library Path tree.
8. Expand the SWC file in the Build Path Libraries tree by clicking the + next to it. The following example shows an expanded SWC named MySWC:

   

9. Change the Link Type to "Runtime shared library (RSL)". You do this by selecting the Link Type and clicking the Edit button. When you change the Link Type to an RSL, Flex Builder displays additional options in the Library Path Item Options dialog box.

   

10. For Verification, select Digests if you are using a cross-domain RSL or if you are using a standard RSL that you want to verify at run time with a digest.

    Click the Add button to add the deployment path of the RSL SWF file. The Edit RSL Deployment Path dialog box appears.

    

    In the Deployment Path/URL field, enter the location that you will deploy the RSL's SWF file to. This path is relative to the main application's SWF file. The default is to deploy the RSL in the same directory as the main application.

    (Cross-domain RSLs only) Add a policy file URL if the application and the RSL will be on separate domains, and the crossdomain.xml file is not at the root of the RSL's server.

    You can have Flex Builder extract the RSL's SWF file from the SWC file automatically or you can do it manually. Deselect the Auto Extract swf to Deployment Path option if you want to extract the RSL's SWF file from the SWC file manually. Otherwise, Flex Builder will extract the SWF file for you. In general, you should manually extract the SWF file and optimize it before deploying it. Otherwise, the library.swf file will be larger than necessary. For more information on optimizing the RSL, see Optimizing RSL SWF files.

    Click OK to save your changes.

11. Select None for Verification if you are using a standard RSL that does not use a digest. In this case, the RSL is assumed to not be cross-domain, and you therefore cannot specify a policy file URL. This is because standard RSLs must be deployed in the same domain as the main application, so policy files are not necessary. The deployment path of the RSL can also only be a local path that is relative to the location of the main application's SWF file.
12. Click OK to save your Library Path Item Options.
13. If the RSL is a cross-domain RSL, ensure that the Verify RSL Digests option is selected in the Library Path tab. If the RSL is standard and you do not want to use a digest, deselect this option. This option is overridden by the Verification setting in the Library Path Item Options dialog box.
14. Click OK to save your changes to the Flex Build Path settings.

Compile with standard or cross-domain RSLs on the command line

To use standard or cross-domain RSLs in your application on the command line, you use the runtime-shared-library-path application compiler option. This option has the following syntax:

-runtime-shared-library-path=path-element,rsl-url[,policy-file-url,failover-url,...]

The following table describes the runtime-shared-library-path arguments:

The following example shows how to use the runtime-shared-library-path option when compiling your application on the command line:

mxmlc -runtime-shared-library-path=../lib/mylib.swc,../bin/library.swf Main.mxml

Do not include spaces between the comma-separated arguments of the runtime-shared-library-path option on the command line.

Your Flex application can use any number of RSLs. In Flex Builder, you add a list of RSLs on the Library Path tab. When using the command line, you add additional runtime-shared-library-path options. In both cases, the order of the RSLs is significant because base classes must be loaded before the classes that use them.

You can also use a configuration file to use RSLs, as the following example shows:

<runtime-shared-library-path>
    <path-element>../lib/mylib.swc</path-element>
    <rsl-url>../bin/library.swf</rsl-url>
</runtime-shared-library-path>

In the previous example, the file structure at compile time looks like this:

c:/Main.mxml
c:/lib/CustomDataGrid.swc

The deployed files are structured like this:

web_root/Main.swf
web_root/bin/library.swf

If you are using a cross-domain RSL, you can also specify the location of the crossdomain.xml file, and the location of one or more RSLs to be used as a failover RSL. The following example specifies a full URL for the location of the RSL, and the locations of a crossdomain.xml file and failover RSL on the command line:

mxmlc -runtime-shared-library-path=
    ../lib/mylib.swc,
    http://www.my-domain.com/rsls/library.swf,
    http://www.my-domain.com/rsls/crossdomain.xml,
    http://www.my-other-domain.com/rsls/library.swf,
    http://www.my-other-domain.com/rsls/crossdomain.xml
    Main.mxml

In the configuration file, this would be represented as follows:

<runtime-shared-library-path>
    <path-element>../lib/mylib.swc</path-element>
    <rsl-url>http://www.my-domain.com/rsls/library.swf</rsl-url>
    <policy-file-url>http://www.my-domain.com/rsls/crossdomain.xml</rsl-url>
    <rsl-url>http://www.my-other-domain.com/rsls/library.swf</rsl-url>
    <policy-file-url>http://www.my-other-domain.com/rsls/crossdomain.xml</rsl-url>
</runtime-shared-library-path>

Toggling RSLs on the command line

When compiling an application that uses RSLs, the command-line compiler options can be unwieldy and difficult to read. It is generally easier to define RSLs in your configuration files. However, when you do that, it is not very easy to enable or disable them as you develop your application because you have to edit the configuration file any time you want to change the way the RSLs are compiled.

To disable the use of RSLs without editing the configuration file, set the value of static-link-runtime-shared-libraries to false. By doing this, you can toggle the use of RSLs from the command line without having to edit the configuration file or enter long sets of command-line options. The default value of this option is true.

While you typically set the value of the static-link-runtime-shared-libraries option on the command line, you can also set it in the configuration file. If you set any RSL values on the command line, then the value of the static-link-runtime-shared-libraries option in the configuration file is ignored.