An example application and security implications

Adobe AIR 1.0 and later

The following HTML code uses uses the filesystem APIs to list the files and directories in the user’s desktop directory.

View full size graphic

Here’s the HTML code for the application: 

<html> 
    <head> 
        <title>Sample application</title> 
        <script type="text/javascript" src="AIRAliases.js"></script> 
        <script> 
            function getDesktopFileList() 
            { 
                var log = document.getElementById("log"); 
                var files = air.File.desktopDirectory.getDirectoryListing(); 
                for (i = 0; i < files.length; i++) 
                { 
                    log.innerHTML += files[i].name + "<br/>"; 
                } 
            } 
        </script> 
    </head>     
    <body onload="getDesktopFileList();" style="padding: 10px"> 
        <h2>Files and folders on the desktop:</h2>             
        <div id="log" style="width: 450px; height: 200px; overflow-y: scroll;" /> 
    </body> 
</html>

You also must set up an application descriptor file and test the application using the AIR Debug Launcher (ADL) application.

You could use most of the sample code in a web browser. However, there are a few lines of code that are specific to the runtime.

The getDesktopFileList() method uses the File class, which is defined in the runtime APIs. The first script tag in the application loads the AIRAliases.js file (supplied with the AIR SDK), which lets you easily access the AIR APIs. (For example, the example code accesses the AIR File class using the syntax air.File .) For details, see Using the AIRAliases.js file .

The File.desktopDirectory property is a File object (a type of object defined by the runtime). A File object is a reference to a file or directory on the user’s computer. The File.desktopDirectory property is a reference to the user’s desktop directory. The getDirectoryListing() method is defined for any File object and returns an array of File objects. The File.desktopDirectory.getDirectoryListing() method returns an array of File objects representing files and directories on the user’s desktop.

Each File object has a name property, which is the filename as a string. The for loop in the getDesktopFileList() method iterates through the files and directories on the user’s desktop directory and appends their names to the innerHTML property of a div object in the application.

Important security rules when using HTML in AIR applications

The files you install with the AIR application have access to the AIR APIs. For security reasons, content from other sources do not. For example, this restriction prevents content from a remote domain (such as http://example.com) from reading the contents the user’s desktop directory (or worse).

Because there are security loopholes that can be exploited through calling the eval() function (and related APIs), content installed with the application, by default, is restricted from using these methods. However, some Ajax frameworks use the calling the eval() function and related APIs.

To properly structure content to work in an AIR application, you must take the rules for the security restrictions on content from different sources into account. Content from different sources is placed in separate security classifications, called sandboxes (see Security sandboxes ). By default, content installed with the application is installed in a sandbox known as the application sandbox, and this grants it access to the AIR APIs. The application sandbox is generally the most secure sandbox, with restrictions designed to prevent the execution of untrusted code.

The runtime allows you to load content installed with your application into a sandbox other than the application sandbox. Content in non-application sandboxes operates in a security environment similar to that of a typical web browser. For example, code in non-application sandboxes can use eval() and related methods (but at the same time is not allowed to access the AIR APIs). The runtime includes ways to have content in different sandboxes communicate securely (without exposing AIR APIs to non-application content, for example). For details, see Cross-scripting content in different security sandboxes .

If you call code that is restricted from use in a sandbox for security reasons, the runtime dispatches a JavaScript error: “Adobe AIR runtime security violation for JavaScript code in the application security sandbox.”

To avoid this error, follow the coding practices described in the next section, Avoiding security-related JavaScript errors .

For more information, see HTML security in Adobe AIR .

// Ethnio survey code removed