User-initiated action requirements in Flash Player 10

Note: The following article is for developers only. Customers who are experiencing Adobe Flash Player installation issues should begin troubleshooting in the Flash Player Support Center.

Among the changes implemented in Adobe Flash Player 10 is a number of user-initiated action (UIA) requirements to enhance overall security and also to cooperate with the emerging web security model as implemented by other web clients, such as browsers. This article aims to help you understand the new UIA requirements in Flash Player: what the restrictions are, why they exist, and how to create content that cooperates with them.

When an ActionScript API function has a UIA requirement, that function can be called only in response to a user action such as a mouse click or key press. Some previously available ActionScript 2.0 and ActionScript 3.0 APIs have had UIA restrictions added in Flash Player 10. In addition, some new features and APIs that are newly introduced in Flash Player 10 also are restricted.

In general, the UIA restrictions exist to make sure that potentially harmful operations such as downloading files to a user's computer, uploading files from a user's computer, entering full-screen mode, or writing to the user's Clipboard cannot take place without the user being aware of such actions, and explicitly initiating with a key press or mouse click.

User-initiated action restrictions

In terms of Flash Player 10, user-initiated actions consist of either keyboard or mouse events: for example, key presses or mouse button clicks. Several operations are subject to the UIA restrictions:

• FileReference operations: The FileReference object methods browse, download, and save and the FileReferenceList.browse method will succeed only when called from within an ActionScript function that is the result of a user-initiated action, such as an event handler for a key press or mouse click. This restriction avoids the problem of a web page making a call to upload or download files from the user's machine without the user explicitly agreeing to such an action. In particular, some potentially problematic areas where the UIA requirement on FileReference will be enforced are within a network-originated callback/event handler or through an ExternalInterface call. In previous versions of Flash Player, calls to FileReference from these locations would succeed. In Flash Player 10, an interactive step must be added to the application workflow, as calls from within these event handlers or via ExternalInterface will fail due to not being the result of a user-initiated action.
• POST APIs: When an HTTP post is used to perform the equivalent of a file upload to a target server, this action can succeed only as the result of a user-initiated action. The format for these uploads is called RFC1867. It consists of an HTTP(S) post with Content-Type of "multipart/form-data" with a section in the POST body that includes a "filename" attribute in a "Content-Disposition" header. The restriction on RFC1867 uploads via POSTs avoids the problem of a SWF silently posting data to the server hosting the SWF without the user explicitly agreeing to such an action. For the case where a SWF could upload a file via a POST to a server other than the server hosting the SWF, the server targeted to receive the upload also will need to opt-in to the cross-domain POST via providing the appropriate cross-domain policy (see Cross-domain policy file specification).
• Clipboard: The ActionScript 2.0 and ActionScript 3.0 API called System.setClipboard(), available in Flash Player 9 and earlier, now requires user interaction to write to the system Clipboard. In addition, the new Clipboard.generalClipboard object in Flash Player 10 can read and write the system Clipboard. Writing to the system Clipboard using either API requires the write to happen as the result of a user-initiated action. In addition, reading from the system Clipboard using the new ActionScript 3.0 API, Clipboard.generalClipboard.getData, can succeed only as the result of a paste event handler. Since a paste event handler can be triggered only by activating the context menu with the mouse (by right-click or Control-click, depending on operating system) or by using the appropriate keyboard shortcut for paste (Control+V or Command+V), APIs executing inside a paste handler are the de facto result of a user-initiated action. These restrictions avoid the problem of a SWF being able to set Clipboard contents unbeknownst to the user.
• Full-screen mode: The Stage.displayState API (in ActionScript 2.0 and ActionScript 3.0) is used to enable full-screen mode in Flash Player 9 and later. Enabling full-screen mode is restricted to when Stage.displayState is called from within a user event handler, such as a key press or mouse click. This restriction helps reduce the probability of a SWF being able to successfully spoof other content on the user's screen without the user being aware of entering full-screen mode.
• Pop-up windows: The following ActionScript APIs can be used to open a new window in the browser :
  • NavigateToURL (ActionScript 3.0)
  • GetURL (ActionScript 2.0)
  • TextField anchors
  • ExternalInterface
  • FSCommand

Using one of these APIs to open a new window is intended to only succeed when called within the handler for a user event, such a key press or mouse click. If these APIs are called from ActionScript code that is not within a user event handler, the browser, dependent on its settings, could decide to block the pop-up window. Since the result of trying to open a pop-up window depends on the particular browser hosting the Flash plug-in and how that browser is configured, behavior may vary across browsers. However, to attempt to ensure successfully opening a window across all browsers, only attempt to open new windows as the result of a user-initiated action. The restriction on opening pop-up windows is intended to make Flash Player co-operate with the browser's settings allowing or preventing pop-up windows from being opened.

Complying with UIA restrictions

There are several steps that a SWF author can (and in some cases must) take to comply with the UIA restrictions of Flash Player 10. The primary way of fulfilling the UIA requirements is to make sure that use of the functionality previously outlined always takes place within an event handler that will be called as a the result of a user pressing a key or clicking the mouse.

For example, writing to the Clipboard could be done from within the event handler for a common keyboard shortcut for Cut or Copy (such as Control+X/Command+X or Control+C/Command+C) or clicking a button marked "Copy to Clipboard." This makes it clear that the user is explicitly choosing to write text to the Clipboard and will pass the UIA requirement—and succeed. In many cases, additional user interface controls may need to be added to the SWF to enable things to be done as the result of user interaction. For example, adding a button to open a new window instead of opening a new window without input from the user.

In certain situations, additional design and code changes may be necessary to comply with the new UIA requirements. A sample scenario might be as follows: An application sends a command to a server, which performs some processing (such as transcoding an image), and then presents the processed data for download. Previously, the application was free to call the FileReference.download API noninteractively as soon as the server was ready. Now, when the server becomes ready, the app must present an additional interactive UI: "Your download is ready, click here to download." In general, adding more interactive steps to the user workflow may be necessary for your application.

There are two ways for a SWF developer to help debug whether the UIA restrictions are causing operations to be denied. Both mechanisms rely on the SWF developer installing the debug version of Flash Player. For SWFs authored using ActionScript 3.0, the debug version of Flash Player will catch and display ActionScript 3.0 exceptions that are thrown when an operation is denied because of a lack of user interaction. For SWFs authored using ActionScript 2.0, the Clipboard.setData API will log a message to flashlog.txt when writing to the Clipboard is denied because of a lack of user interaction. Please see the Flash Player TechNote, Configure the debugger version of Flash Player, for further information on enabling debug logging to flashlog.txt. It is intended to expand the ActionScript 2.0 logging and further refine the ActionScript 3.0 exceptions generated by violating UIA requirements in a future Flash Player release.

The UIA changes in Flash Player 10 apply to all versions of SWFs that are loaded into the player. This means, for example, that a SWF authored targeting SWF version 9 will have the Flash Player 10 UIA requirements applied to it. In many cases, the SWF code may need to be updated—to include additional UI controls or to change its workflow as suggested in this article—in order to comply with the UIA requirements and then republished.

Where to go from here

Developers should make sure that their SWFs comply with the new UIA rules. Be sure to update both your new content and pre-existing old content to do so.