Flash Debug Player and its Configuration

To work with Flex Builder Debugger, you need the Flash debug player. This is installed when you install Flex Builder. But, this may fail or you may upgrade Flash player independently. To determine if you have the debug player installed, you can navigate to: Version test for Adobe Flash Players. In ActionScript, you can use Capabilities.isDebugger property to test if you have the debug player installed.

Flash debug player is different from the standard Flash Player. It includes additional functionality that the standard player does not have such as:

• Logs trace() statements (logging in the Flash debug player is turned off by default)
  
• Works with Flex Builder Debugging Perspective
• Works with the Flex Builder 3 Profiler

Using Flash debug player's run time log file (i.e., flashlog.txt) alone, you can gain lots of valuable information for your debugging. Output strings from trace() method are appended to this log file. Furthermore, the debug player exposes quite a bit Run Time Errors (RTEs). The production player will actually ignore most RTEs and carry on. This can let the user continue on without a fatal crash. But, sometimes the error can stop the Flash application in its tracks.

The debug version of Flash Player can be configured by the mm.cfg text file in the system. You can use any text editor to create it. The following table lists the properties that you can set in the mm.cfg file:

Property	Description
ErrorReportingEnable	Enables the logging of error messages. Set the ErrorReportingEnable property to 1 to enable the debugger version of Flash Player to write error messages to the log file. To disable logging of error messages, set the ErrorReportingEnable property to 0. The default value is 0.
MaxWarnings	Sets the number of warnings to log before stopping. The default value of the MaxWarnings property is 100. After 100 messages, the debugger version of Flash Player writes a message to the file stating that further error messages will be suppressed. Set the MaxWarnings property to override the default message limit. For example, you can set it to 500 to capture 500 error messages. Set the MaxWarnings property to 0 to remove the limit so that all error messages are recorded.
TraceOutputFileEnable	Enables trace logging. Set TraceOutputFileEnable to 1 to enable the debugger version of Flash Player to write trace messages to the log file. Disable trace logging by setting the TraceOutputFileEnable property to 0. The default value is 0.
TraceOutputFileName	Note: Beginning with the Flash Player 9 Update, Flash Player ignores the TraceOutputFileName property. Sets the location of the log file. By default, the debugger version of Flash Player writes error messages to a file named flashlog.txt, located in the same directory in which the mm.cfg file is located. Set TraceOutputFileName to override the default name and location of the log file by specifying a new location and name in the following form: On Macintosh OS X, you should use colons to separate directories in the TraceOutputFileName path rather than slashes. TraceOutputFileName=<fully qualified path/filename>

For example, the following sample mm.cfg file enables error reporting and trace logging:

ErrorReportingEnable=1
TraceOutputFileEnable=1

The location of mm.cfg and its log file (i.e., flashlog.txt) is determined by OS. However, you can update the log file location and name through the TraceOutputFileName property.

The following table shows where to create mm.cfg for several operating systems.

Operating System	Create mm.cfg file in this directory
Macintosh OS X	MacHD:Library:Application Support:macromedia:
Microsoft Windows Vista	C:\Users\user_name\
Microsoft Windows 2000/XP	C:\Documents and Settings\user_name\
Microsoft Windows 95/98/ME	%HOMEDRIVE%\%HOMEPATH%\
Linux	/home/user_name

The following table shows the default flashlog.txt file location:

Operating System	Location of flashlog.txt
Macintosh OS X	MacHD:Users:user_name:Library:Preferences:Macromedia:Flash Player:Logs:flashlog.txt
Microsoft Windows Vista	C:\Users\user_name\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt
Windows 95/98/ME/2000/XP	C:\Documents and Settings\user_name\Application Data\Macromedia\Flash Player\Logs\flashlog.txt
Linux	/home/user_name/.macromedia/Flash_Player/Logs/flashlog.txt

Being a text file, there are several ways to read from the log file:

• Notepad or its equivalent
• Tail or some variant
• FlashTracer
• Using the tail view in Aptana
  

If you have trouble of generating flashlog.txt log file, check out this article--"Troubleshooting tips for .txt not being generated."

Security Models in Flash Player

To protect data from being transferred to unauthorized destinations without appropriate permission, Flash Player scrutinizes all requests to load or access external resources, or interact with other SWF files or HTML files.  Each request a SWF file makes for an external resource (i.e., a resource not compiled into the SWF file making the request) is rejected or approved based on the following factors:

• The external operation used to access the resource (i.e., Loader.load(), Sound.load(), etc.)
• The security domain (or security sandbox) of the SWF file performing the request
• The location of the resource
• The explicit access-permissions set for the resource as determined by either the resource's creator (i.e., the developer that compiles the SWF) or distributor (i.e., usually a web site administrator or socket server administrator)
• Creator permission means a SWF file contains the appropriate call to the Security class's static method allowDomain() or to allowInsecureDomain()
• Distributor permission means the resource distributor has made the appropriate cross-domain policy file available
• The explicit access-permissions granted by the user (e.g., permission to connect to the user's camera or microphone)
• The type of Flash Player running the SWF file (e.g., plug-in version, standalone version, Flash authoring tool test version)
• To simplify the testing of local content that is intended for web deployment, Adobe's Flex Builder automatically grants trust to projects under development.
• To test your application as your end user will see it, be sure to run it in its target environment.

What's Security Sandbox?

Much of Flash Player security is based on the region of origin from which the SWF file was opened or loaded. A SWF file from a specific Internet domain, such as www.example.com, can always access all data from that domain. These assets are put in the same security grouping, known as a security sandbox(or security domain). The following basic security rules always apply by default:

• Resources in the same security sandbox can always access each other.
• SWF files in a remote sandbox can never access local files and data.

Based on security restrictions, the following are four of the most-often blocked external operations:

• Loading content
• Loading content means retrieving any external resource to subsequently display or play it.
• Accessing content as data
• Accessing content as data means reading the internal information of a content resource. For example, reading the pixels of a bitmap.
• Cross-scripting
• Cross-scripting means accessing a loaded SWF file programmatically.
• Loading data
• The term "loading data" could be used to describe a wide variety of Flash Player load operations, including downloading files from a server via the FileReference class's instance method download(), loading binary data over a Socket object, and so on.

The specific method used to load the resource (not the file type of the resouorce) makes an external operation either a loading-data operation or a loading-content operation. For example, loading a SWF file using URLLoader's load() method is considered a loading-data operation; loading that same SWF file using Loader's load() method is considered a loading-content operation.

In the following table, it illustrates the approved and prohibited external operations in a remote sandbox.

Operation	Resources in Local Domain	Remote Domain Resources from SWF's Region of Origin	Remote Domain  Resources Outside SWF's Region of Origins
Loading Content	Prohibited	Allowed	Allowed
Accessing Content as Data	Prohibited	Allowed	Allowed by distributor permission only
Cross-scripting	Prohibited	Allowed	Allowed by creator permission only
Loading Data	Prohibited	Allowed	Allowed by distributor permission only

For similar restriction rules applied to other sandbox types, see "Chapter 19--Flash Player Security Restrictions" in the Book "Essential ActionScript 3.0."

Sandbox Types

Flex assigns a security status known as a secuirty-sandbox-type to every SWF file opened by or loaded into Flash Player.  To check a SWF file's security-sandbox-type at runtime, you can retrieve the value of the flash.system.Secuirty.sandboxType variable from within that SWF file (note that this property is only supported in Flash Player 8 or later).  There are five possbile security-sandbox-types:

• remote(i.e., Security.REMOTE)
• Remote means the loaded SWF is from an Internet URL.
• local-with-filesystem(i.e., Security.LOCAL_WITH_FILE)
• Local-with-filesystem means the loaded SWF file is from local file system and was compiled with -use-network compiler flag set to be false.
• local-with-networking(i.e., Security.LOCAL_WITH_NETWORK)
• Local-with-networking means the loaded SWF file is from local file system and was compiled with -use-network compiler flag set to be true.
• local-trusted(i.e., Security.LOCAL_TRUSTED)
• Local-trusted means SWF file was opened from a trusted local location
• To verify which locations are trusted on a given computer,consult
• the trust files in the User Flash Player Trust directory (e.g. C:\Documents and Settings\JohnD\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust on Windows XP)
• the Global Flash Player Trust directory(e.g., c:\WINNT\system32\Macromed\Flash\FlashPlayerTrust on Windows)
• the online Flash Player Settings Manager
• application(i.e., Security.APPLICATION)
• This SWF file is running in an AIR application, and it was installed with the package (AIR file) for that application.

Air Security Model

Being a desktop application runtime, the AIR security model is significantly different from the web browser security model. The application sandbox (i.e., assets that exist in the application directory ) in AIR provides direct access to privileged AIR specific system APIs. In return for access to these powerful APIs, some common dangerous APIs and patterns are restricted. For example, dynamic importing of remote content is generally prohibited and dynamic code generation techniques (e.g., using eval() and similar APIs to generate code at runtime) are heavily restricted. Only content loaded directly from the application home directory (via the app:/ URI scheme) can be placed in the application sandbox.

By default, files in the AIR application sandbox can cross-script any file from any domain (although files outside of the AIR application sandbox may not be permitted to cross-script the AIR file). By default, files in the AIR application sandbox can load content and data from any domain.

In the following table, it illustrates the approved and prohibited external operations in an application sandbox.

Operation	Resources in the Application Sandbox	Non-SWF Resources in the Non-Application Sandbox	SWF Resources in the Non-Application Sandbox
Content Loading	Allowed	Allowed	Allowed
Accessing Content as Data	Allowed	Allowed	Allowed
Cross-Scripting	Allowed	n/a	SWF files in the application sandbox can cross-script SWF files in the non-application sandbox although SWF files from the non-application sandbox may not be permitted to cross-script SWF files in the application sandbox.
Data Loading	Allowed	Allowed	Allowed

Air applications that write to the local file system are advised to write to app-storage:/. This directory exists separately from the application files on the user's computer, hence the files are not assigned to the application sandbox and present a reduced security risk. Developers are advised to consider the following:

• Include a file in an AIR file (in the installed application) only if it is necessary.
• Include a scripting file in an AIR file (in the installed application) only if its behavior is fully understood and trusted.
• Do not write to or modify content in the application directory. The AIR runtime prevents applications from writing or modifying files and directories using the app:/ URL scheme by throwing a SecurityError exception.
• Do not use data from a network source as parameters to methods of the AIR API that may lead to code execution. This includes use of the Loader.loadBytes() method and the JavaScript eval() function.

Besides application sandbox, non-application sandbox contains all other content that is not loaded directly into the application sandbox. This includes local and remote content. Content loaded from outside the application observes the same security rules as content loaded in a web browser. For example, such content cannot call AIR APIs that provide access to the local file system.

In many cases, frameworks and existing code will work with little or no modification in the application sandbox. However, in some cases the developer will have to perform high-risk operations (such as importing of remote JavaScript) in a non-application sandbox, then carefully expose the resulting code and data back to the application sandbox via the SandboxBridge API.