Using the Sandbox Script Bridge

The Sandbox Bridge sample application shows how to use the security sandbox bridge to load locally installed HTML content into a network domain, and have script in the application security sandbox communicate with a script in the remote domain, using the AIR sandbox bridge.

For more information on the AIR sandbox bridge, refer to the section Cross-scripting content in different security sandboxes in HTML Developer's Guide for Adobe AIR.

Note: This is a sample application provided, as is, for instructional purposes.

This sample application includes the following files:

• root.html: The main application content.
• ui.html: Content to be loaded into a non-application security sandbox.
• sample.css: A cascading style sheet file.
• AIRAliases.js: The AIR JavaScript aliases file
• application.xml: The AIR application descriptor file that you use to debug and build the application (using ADL and ADT).
• Sample AIR icon files

Testing the application

The Sandbox Bridge application loads HTML content into two frames. The top frame contains content in the application security sandbox, and the bottom frame contains content from the application resource directory that is loaded into a remote domain:

The application illustrates various features of the AIR sandbox bridge and related security details of the runtime, including:

• Content in the application security sandbox can access all the runtime APIs, whereas content in other sandboxes cannot directly call AIR APIs.
• Content in the application security sandbox can reveal a method to content in other sandboxes via a sandbox bridge. Similarly, content in the application security sandbox can reveal a method to content in the application sandbox via a sandbox bridge

Understanding the code

For more information about using AIR classes, see the Adobe AIR API Reference for HTML Developers.

Loading content from the application resource directory into different security domains

The application is built from two HTML files: root.html and ui.html. The root.html file is the root application file, defined in the initialWindow property of the application descriptor file (application.xml). This content is loaded into the AIR application security sandbox. This HTML file then loads the ui.html file into an iframe. The attribute settings of the iframe define the security sandbox to use for this content:

The documentRoot attribute specifies the source location for the file. In this case, it is set to "app:/", the URL scheme for the application resource directory, the directory where the AIR application files are installed. By default, content from this directory is placed in the application security sandbox. However, in this case, for content in this iframe the sandboxRoot attribute remaps the URLs from one sandbox, in this case the sandbox for the localhost domain, to the documentRoot ("app:/") sandbox. The application then reinterprets URLs in this iframe that begin with the sandBoxRoot path to return data from the documentRoot directory.

By placing this content into a non-application security sandbox, it has different privileges than if it was loaded into the application security sandbox, as described in the following sections.

Capabilities of content in the application security domain

The root.html page is loaded as the root content of the application’s initial window. As such, it is automatically placed in the application security sandbox. Content in the application security sandbox has access to AIR APIs that are content in other sandboxes are prevented from using. The first button in the application illustrates this. When the user clicks it, the application successfully executes a call to the following function:

The air.NativeApplication.nativeApplication.applicationDescriptor property, which returns the contents of the application descriptor file for the application, is one of the AIR APIs that is restricted to content in the application security sandbox. Another example of a restricted API is the FileStream class, which contains methods for reading and writing to the local file system. APIs that are restricted to content in the application security sandbox are indicated as such in the Adobe AIR Language Reference for HTML Developers by the AIR logo.

Content in the application security sandbox can only use APIs that can dynamically transform strings into code while code is loading from application resource URLs. This means that application content can only call the eval() function while code is loading from application resource URLs. After such code is loaded, it cannot call APIs such as the eval() function.

The second button in the application calls the eval() function from the application security sandbox, which results in the runtime throwing an exception:

Dynamically generated code, such as that which is made when calling the eval() function, would pose a security risk if allowed within the application sandbox. For example, an application may inadvertently execute a string loaded from a network sandbox, and that string may contain malicious code, such as code to delete or alter files on the user’s computer or to report back the contents of a local file to an untrusted network domain.

Ways to generate dynamic code are the following:

• Calling the eval() function.
• Setting innerHTML properties or calling DOM functions to insert script tags to load a script outside the resource directly.
• Setting innerHTML properties or calling DOM functions to insert script tags that have inline code (rather than loading a script via the src).
• Using the src for script tags for content in the application sandbox that is not from the application resource directory.
• Using the javascript URL scheme (as in href="javascript:alert('Test')").

Code in the application security sandbox can only use these methods while content is loading from application resource.

Capabilities of content in non-application security domains

The ui.html page is loaded into an iframe and placed in a non-application sandbox (see "Loading content from the application resource directory into different security domains").

Unlike content in the application security sandbox, content in a non-application security sandbox can call the eval() function to execute dynamically generated code at any time. The first button in the non-application iframe successfully calls the eval() function from the non-application security sandbox:

Content in a non-application security sandbox does not have access to AIR APIs that are restricted to content in the application security sandbox. The second button in the non-application iframe (the second frame on the page, outlined in red) illustrates this. When the user clicks it, the application throws a TypeError exception:

Code in a non-application sandbox does not have access to the window.runtime object, and as such this code cannot execute AIR APIs. For example, the window.runtime.flash.system.NativeApplication.nativeApplication.exit() method, which causes the application to quit, is one of the AIR APIs that is restricted to content in the application security sandbox. The sample application throws a runtime exception when the user clicks the second button in the second iframe, which tries to call the window.runtime.flash.system.NativeApplication.nativeApplication.exit() method:

The exception type is TypeError (undefined value), because content in the non-application sandbox does not recognize the window.runtime object, so it is seen as an undefined value.

Script communication between different sandboxes

There are times when you want to expose some restricted AIR application APIs to non-application content in a limited way. AIR provides a sandbox bridge for the application security sandbox to expose properties and methods to iframe content loaded into other sandboxes.

The window object contains a parentSandboxBridge property, which lets scripts in the application sandbox expose methods and properties to content loaded into other sandboxes. For example, the root.html file contains the following code, which exposes the air.trace() function as a trace() method of the parentSandBox property of the window object and which exposes the readApplicationDescriptorFile() function as a readApplicationDescriptorFile() method of the parentSandBox property of the window object:

The child iframe content (in a non-application security sandbox) can access these methods by calling the trace() and readApplicationDescriptorFile() methods of the parentSandBox property of the window object. The third button in the first iframe of the application (in the application security sandbox) illustrates this by calling parentSandboxBridge.readApplicationDescriptorFile() method:

The window object also contains a childSandboxBridge property, which lets scripts in non-application sandboxes expose methods and properties to parent application content that loads the non-application content via an iframe. For example, the ui.html file contains the following code that exposes the forApplicationSandbox() function as a callMe() method of the childSandBox property of the window object:

The parent application content can then access that function by calling the callMe() method of the childSandBox property of the window object. The third button in the first iframe of the application (in the application security sandbox) illustrates this by calling the callMe() function.

For more information, see the Adobe AIR HTML Security chapter of Developing AIR Applications with HTML and Ajax.