JavaScript Controls

JavaScript support is one of Acrobat’s and Adobe Reader’s most powerful features, and Adobe provides several controls that enable tuning application behavior so that JavaScript (JS) executes within your desired level of security where unrestricted access to JS APIs is undesirable or workflows do not leverage this feature at all.

Permissions basics

There are a number of JavaScript controls that allow you to balance needed features with the level of security needed for your workflows. At a high level, these options include:

• Restrict JavaScript: Turn off JavaScript altogether or restrict JS by API.
• Trust JavaScript: Allow JavaScript globally, by API, or by trusting specific document for it.

Configuration is possible either through the user interface, the registry, or both as follows:

• User interface:

  • Application trust can be set by choosing Preferences > JavaScript.
  • Document trust can be assigned in some workflows via the Yellow Message Bar’s Options button.
  • High privileged API trust can be assigned via certificate trust in certified document workflows.

• Registry-level preferences (and plist): As described in subsequent sections, many settings are available to administrators.

JS Workflow: Simple view

Workflow diagrams

For a visual overview, see the JavaScript Quick Key

Changes across releases

Evolution of JavaScript execution

Version	Change
8.1.7 & 9.2	JavaScript blacklist introduced thereby allowing selective blocking of vulnerable APIs. Default lists are null. A non-intrusive Yellow Message Bar (YMB) that doesn’t block workflows replaces many of the modal dialogs. Depending on how the client is configured, the YMB appears at the top of the document and offers the user to trust the document “once” or “always.” cAlwaysTrustedForJavaScript can override the global JS off preference for specifically trusted documents. cJavaScript can override the high privileged JS restrictions for specifically trusted documents.
8.2 & 9.3	None.
9.3.4	cJavaScriptURL is introduced as part of enhanced security. An untrusted document that tries to invoke an URL via JS displays the YMB.
10.1.1	Changes to the global variable and user JavaScripts features are made more secure. These changes require action by IT as described in Migrating to 10.1.1+. JavaScript Blacklist Framework Tool is introduced which provides IT with a GUI for managing JS APIs.
11.0	bEnableCertificateBasedTrust provides a way to make certified documents trusted as a privileged location.

Disabling JavaScript

Global JS configuration may occur via the user interface or the registry/plist.

1. Go to Preferences > JavaScript (The exact path varies by product and platform).
2. In the JavaScript panel, uncheck Enable Acrobat JavaScript. This preference sets:

[HKCU\Software\Adobe\<product name>\<version>\JSPrefs]
"bEnableJS"=dword:00000000

Note

If JS is disabled, the user experience when a document tries to execute JavaScript varies by product version.

Trusted override

There are several ways to assign trust so that this feature works in a trusted context:

• Users can trust documents on-the-fly when the PDF opens: When the Yellow Message Bar appears, choose the Options button and then trust the document once or always.
• Create a privileged location via the UI for the file, folder, or host.
• Create a privileged location via the registry/plist by placing a tID at:

[HKCU\Software\Adobe\<product name>\<version>\TrustManager\(cTrustedSites or TrustedFolders)\cAlwaysTrustedForJavaScript]
"t8"="C:\\someTrustedPDF"

JS Workflow: Enabling-disabling JS

Blacklisting JS APIs

The Acrobat JavaScript Blacklist Framework introduced in versions 9.2 and 8.1.7 provides granular control over the execution of specific JavaScript APIs. This mechanism allows selective blocking of vulnerable APIs so that you do not have to resort to disabling JavaScript altogether. The blacklist is maintained in the Windows registry and the Macintosh OS X FeatureLockdown file. On Windows, there are two blacklists, one for enterprise administrators, and one for Adobe patches and updates.

Blacklist rules of operation

• Blacklist settings do not apply to 3D JavaScript.
• If a blacklisted script is encountered, all other scripts in the document are blocked. Only documents that don’t contain any blacklisted JavaScript will be given permission to run other JavaScripts.
• The two blacklists interact so that the more restrictive setting takes precedence; that is, if one blacklist blocks an API and the other does not, the API is blocked.

Blacklist locations

• Macintosh: Policy deployment is specific to Windows, so Macintosh, has only one update/path blacklist at Contents::MacOS::Preferences > FeatureLockDown/cJavaScriptPerm/tBlackList. This location is updated by Acrobat patch installers.

The JS API blacklist may reside in two locations on Windows.

• Windows: Enterprise list: This blacklist helps enterprises roll out policies that block exploitable API(s) from executing in their environment. Populating the blacklist in this location is the responsibility of the enterprise. Adobe patches never modify this registry location.

[HKLM\SOFTWARE\Policies\Adobe\<product>\<version>\FeatureLockDown\cJavaScriptPerms\]
"tBlackList"

• Windows: Adobe’s update/patch list: The Adobe blacklist is modified by Acrobat and Adobe Reader patches whenever an API is deemed vulnerable. APIs are also removed from the blacklist whenever a fix for a vulnerability is provided by the current patch.

[HKLM\SOFTWARE\Adobe\<product>\<version>\JavaScriptPerms\]
"tBlackList"

Note

On a 64 bit Windows system, the path is HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Adobe.

Blacklist configuration

The manual steps described below require administrator privileges on a machine and should only be undertaken by someone experienced in registry-level configuration. In most cases, configuration occurs via the Customization Wizard prior to client deployment or via a scripting mechanism post-deployment.

To manually configure a blacklist:

1. Open the registry editor.
2. Go to HKLM\SOFTWARE\Policies\Adobe\<product>\<version>\FeatureLockDown\cJavaScriptPerms\.
3. Create cJavaScriptPerms if it does not exist by right clicking and choosing New Key.
4. Create tBlackList: right click in the right hand panel and choose New > String value.
5. Enter tBlackList.
6. Right click on tBlackList and choose Modify.
7. Add the APIs to block as a pipe-separated list in for the format of <some Object Name>.<Some API Name>. For example:

Util.CharToByte|App.alert|Collab.getIcon

8. Exit and restart the application.

cJavaScriptPerms: Registry configuration

Trusted override

There are several ways to assign trust so that the APIs continue to function in a trusted context:

• Create a privileged location via the UI for the file, folder, or host.
• Create a privileged location via the registry/plist by placing a tID at:

[HKCU\Software\Adobe\<product name>\<version>\TrustManager\<cTrustedSites or TrustedFolders>\]
"cUnsafeJavaScript"

JS Workflow: Blacklisted APIs

JS blacklist tool

Adobe intends to periodically release beta and experimental tools, utilities, and scripts on LABS. This informal pre-release program provides a way to help customers while opening up channels for feedback that will help improve the product and related enterprise resources. Items posted on LABs should be tested by your organization in order to determine their compatibility with the particulars of your environment.

One such tool is the JavaScript Blacklist Framework Tool for Acrobat and Adobe Reader. The tool offers protections against an entire class of vulnerabilities that target JavaScript APIs.

Installation

To install the tool:

1. Go to LABS at http://labs.adobe.com/technologies/acrobat/.

2. Verify the following:

   • You have the Microsoft .NET 4.0 framework. If you don’t, the tool’s installer should prompt you to install it.
   • You are using it for Reader and Acrobat 9.2 and 8.1.7 and later versions as well as any 10.x version.

3. Agree to the Terms of Use and download the installer.
4. Unzip and run the installer.
5. Choose Next.
6. Choose an installation directory or accept the default (Under Program FilesAdobe).
7. Choose whether the blacklist will apply to everyone or just the current user.

Note

The Disk Cost button is just a default button. The disk size is very small.

8. Choose Next.
9. Choose Next again to confirm the installation.
10. Choose Close.

Usage

The tool presents a list of JavaScript APIs that have been attacked in the past. It retrieves a current list of APIs from an Adobe server but presents a default list if an Internet connection is unavailable.

To use the tool:

1. Choose Start > Programs > JS Blacklist Framework for Adobe Reader or Acrobat.
2. Check and uncheck multiple APIs to Add or Remove them to and from the blacklist.
3. Choose Add or Remove.
4. Choose View to see what’s currently blacklisted.

Note

The data is saved in a text file in the application’s installation directory. Simply check and uncheck multiple APIs to Add or Remove them to and from the blacklist.

Blacklist tool

Disabling menu-invoked JS

Beginning with Acrobat 7.0, execution of JavaScript through a menu event is no longer privileged. By default, this setting is off.

1. Go to Preferences > JavaScript (The exact path varies by product and platform).
2. In the JavaScript Security panel, set Enable menu items JavaScript execution privileges. This values sets:

[HKCU\Software\Adobe\<product name>\<version>\JSPrefs]
"bEnableMenuItems"

Note

Enables executing JS by clicking menu items. When off, privileged JS calls can be executed via the menu unless they have been wrapped in the app.trustFunction. Executing non-privileged JS calls via menu items is not blocked whether this box has been checked or not.

Trusted override

There are several ways to assign trust so that this feature works in a trusted context:

• Choose Preferences > JavaScript and check Enable menu items JavaScript execution privileges.
• Enabling via a trusted function: Trusted functions allow privileged code that normally requires a privileged context to execute to execute in a non-privileged context. For details and examples, see the app.trustedFunction in the JavaScript for Acrobat API Reference. This feature was introduced in Acrobat 7.0.
• Add the requisite function to:

HKLM\SOFTWARE\Policies\Adobe\<product name>\<version>\FeatureLockDown\cDefaultExecMenuItems\
"tWhiteList"

Disabling global object access

By default, global object access is not allowed.

1. Go to Preferences > JavaScript (The exact path varies by product and platform).
2. In the JavaScript Security panel, set Enable global object security policy as needed. This values sets:

[HKCU\Software\Adobe\<product name>\<version>\JSPrefs]
"bEnableGlobalSecurity"

Note

Toggles on and off the ability of a script to access objects outside of the current document sandbox. If enabled, JavaScript objects are globally accessible.

High privileged JavaScript

High privileged JavaScript is restricted by default.

High privilege JavaScripts are Acrobat methods with security restrictions. These are marked by an “S” in the third column of the quick bar in the JavaScript for Acrobat API Reference. These methods can be executed only in a privileged context, which includes the console, batch, menu (for versions prior to 7.x), and application initialization events. All other events (for example, page open and mouse-up events) are considered non-privileged. The description of each security-restricted method indicates the events during which the method can be executed.

Beginning with Acrobat 6.0, security-restricted methods can execute in a non-privileged context if the document is certified and the certifier’s certificate is trusted for executing embedded high privilege JavaScript. In Acrobat versions earlier than 7.0, menu events were considered privileged contexts.

JS Workflow: High privileged APIs

Trusted override

There are several ways to assign trust so that this feature works in a trusted context:

• Configure certificate trust for digital signature workflows as described below.
• Create a privileged location via the UI for the file, folder, or host.
• Create a privileged location via the registry/plist by placing a tID at either:
• Administrator list: This list requires administrator rights to modify and locks down the feature. It resides at:

HKLM\SOFTWARE\Policies\Adobe\<product name>\<version>\FeatureLockDown\(cTrustedSites or TrustedFolders)\cJavaScript

• User list: The user list is for the current user only and is editable via the user interface. It resides at:

HKCU\Software\Adobe\<product name>\<version>\TrustManager\(cTrustedSites or TrustedFolders)\cJavaScript

Certificate trust

You can control script behavior on a per-certificate basis or by using trust anchors. If a signer’s certifying certificate chains up to another certificate (a trust anchor) that allows high privileged JavaScript, then high privileged JavaScript will run in that document. For example, some enterprises may issue a MyCompany certificate that allows high privileged JavaScript. If all employee certificates use ExampleCompany as a trust anchor, then they can send and receive certified documents within the company that allow high privileged JavaScript execution.

Thus, certificate trust settings can override blacklist settings under the following conditions:

• The document must be certified.
• The certification signature must be valid.
• The signer’s certificate is trusted for or chains up to a trust anchor trusted for executing high privilege JavaScript.

Configure certificate trust as described in Per-certificate trust.

Certificate trust settings

Certified document trust

11.0 introduces a new setting that elevates certified documents to a privileged location. When enabled, certified documents with a valid certification signature whose certificate chains to a trusted root are trusted in the same way as privileged locations and can therefore override JavaScript restrictions. For details, see Certified document trust.

JavaScript invoked URLs

With 9.3.4, cJavaScriptURL is introduced as part of enhanced security. An untrusted document that tries to invoke an URL via JS displays the YMB by default. The user is given the option to trust the document for such actions via the Options button on the YMB.

An untrusted document that tries to invoke an URL via JS displays the YMB by default. The user is given the option to trust the document for such actions via the Options button on the YMB.

Trusted override

There are several ways to assign trust so that this feature works in a trusted context:

• Users can trust documents on-the-fly when the PDF opens: When the Yellow Message Bar appears, choose the Options button and then trust the document once or always.
• Create a privileged location via the UI for the file, folder, or host.
• Create a privileged location via the registry/plist by placing a tID at:

[HKCU\Software\Adobe\<product name>\<version>\TrustManager\(cTrustedSites or TrustedFolders)\cJavaScriptURL]
"t8"="C:\\someTrustedPDF"

JavaScript injection

You can block JS injection by enabling Enhanced Security.

Yellow message bar: JavaScript injection

Trusted override

There are several ways to assign trust so that this feature works in a trusted context:

• Users can trust documents on-the-fly when the PDF opens: When the Yellow Message Bar appears, choose the Options button and then trust the document once or always.
• Create a privileged location via the UI for the file, folder, or host.
• Create a privileged location via the registry/plist by placing a tID at:

[HKCU\Software\Adobe\<product name>\<version>\TrustManager\(cTrustedSites or TrustedFolders)\cScriptInjection]
"t8"="C:\\someTrustedPDF"

Workflow changes by version

Acrobat and Adobe Reader have always provided controls for managing JavaScript. Over time, these controls have become more rich in an effort to provide granular control over document behavior. The behavior across versions is as follows:

9.1 and 8.1.6 and earlier

• If the application has JavaScript enabled:

  • Non-high privileged JavaScript runs.
  • High privileged JS will run if permitted to do so by other controls.

• If the application has JavaScript disabled:

  • Non-high privileged JavaScript invokes a dialog stating that the document contains JavaScript. Users are asked whether they would like to enable JS from now on for all documents. If the user selects the Yes button, the JavaScript preference is enabled for the application from then on
  • High privileged JavaScript will not execute unless the user has established a prior trust relationship with the document via a trusted certificate or privileged location.

What happens when JS is off

9.2 and 8.1.7 and later

These versions will behave as follows:

• If the application has JavaScript enabled:

  • Non-high privileged JavaScript runs.
  • High privileged JS will run if permitted to do so by other controls.

• If the application has JavaScript disabled:

  • Any JavaScript invokes a Yellow Message Bar warning about the script. Users have two options:

    • Enable JavaScript for this document one time only
    • Enable JavaScript for this document always: This option stores a unique document ID in HKCU\Software\Adobe\<product name>\<version>\TrustManager\cTrustedFolders\cAlwaysTrustedForJavaScript

Yellow message bar: JS off warning (9.2 and 8.1.7 and later)

• High privileged JavaScript will not execute unless the user has established a prior trust relationship with the document via a trusted certificate or privileged location.
• If JavaScript is enabled and a blacklisted JavaScript is encountered, the Document Message Bar warns the user about the script and no script is executed even if they are not blacklisted. A NotAllowedError exception is thrown on the JavaScript console.

Yellow message bar: Blacklisted JS warning

9.3 and 8.2 and later

Encountering an attempt to inject JavaScript over cross domain communications results in a YMB.

Yellow message bar: Blacklisted JS warning

Migrating to 10.1.1+

Affected users

These changes for 10.1.1 impact existing workflows that use persistent global variables (Windows and Macintosh) or custom JavaScripts (Windows only). Enterprise IT should take action to preserve workflows that leverage these features.

Overview

Due to Adobe’s high interest in security, changes to existing Acrobat and Adobe Reader functionality are periodically released to further strengthen the product’s resistance to malicious attacks. As part of this effort, 10.1.1 introduces changes to the JavaScript feature that stores global variables and executes user-defined scripts.

Prior to 10.1.1, end users could place JavaScript files in %ApplicationData%\Adobe\<product name>\<version>\JavaScripts, and these files would execute automatically on application startup. For example, IT might place a JS file for modifying the product user interface by hiding or adding menu items on a Windows XP machine in C:\Documents and Settings\(username)\Application Data\Adobe\Acrobat\10.0\JavaScripts. Additionally, the folder contains glob.js and glob.settings.js, two files which the product can read and write to when storing global variables.

By design, Acrobat processes do not write to the %ApplicationData%\Acrobat\Privileged\10.0 folder. Additionally, sandboxed processes are specifically prohibited from writing to that folder. Thus, the most secure operation involves enabling Protected View in Acrobat and Protected Mode in Reader, thereby sandboxing all processes. Additionally, 10.1.1 introduces the following changes:

• New user JS location: The user JavaScript folder is moved from

  • Vista and Windows 7: Users\(username)\AppData\Roaming\Adobe\Acrobat\10.0\JavaScripts to Users\(username)\AppData\Roaming\Adobe\Acrobat\Privileged\10.0\JavaScripts. For example, the new path might be: C:\Users\JoeUser\AppData\Roaming\Adobe\Acrobat\Privileged\10.0\JavaScripts
  • XP: Documents and Settings\(username)\Application Data\Adobe\Acrobat\10.0\JavaScripts to Documents and Settings\(username)\Application Data\Adobe\Acrobat\Privileged\10.0\JavaScripts. For example, the new path might be: C:\Documents and Settings\JoeUser\Application Data\Adobe\Acrobat\Privileged\10.0\JavaScripts

Note

This is a Windows-only change. Also, the change does not impact the behavior of C:\Program Files\Adobe\(product name and version)\(product name)\JavaScripts.

• New format and location for persistent global variables: Variable settings stored in glob.settings.js and glob.js now reside in a new directory at %ApplicationData%\Adobe\Acrobat\10.0\JSCache. The key value pairs read from the ASCab are used to initialize the persistent global variables. No settings are saved as JavaScript files in this directory.

What you should do

If you have not stored variables as persistent global variables or placed custom JavaScripts in the affected directories, then you can ignore this change. However, if you have done either, maintain the integrity of your workflows by doing the following:

Global variable issues

• Verify glob.js and glob.settings.js do not store anything other than key value pairs and scalar values. Workflows that use these files to store other methods will break.
• Since any data residing in glob.js and glob.setting.js at the time of applying 10.1.1 will be lost, maintain the integrity of your workflows by doing the following:

1. For Acrobat, you can either:

   • Copy the JavaScript in the existing glob.js and glob.setting.js files from the old JavaScripts folder and execute it in the JavaScript console in a new Acrobat session. This will export the stored global variables to the new Acrobat session. Or,
   • Copy glob.js and glob.setting.js from the old JavaScripts folder to the %Program Files%/Adobe/Reader/JavaScript folder and then delete the original files. Restart the product to export the variables to the new format.

Note

For Adobe Reader, you can only use the latter method since the JavaScript console is not available unless you have enabled it as described at http://blogs.adobe.com/pdfdevjunkie/2008/10/how_to_use_the_javascript_debu.html.

2. Manually execute the JavaScript setPersistent method on all global variables to ensure they are correctly migrated to the new format. For example, run the following JavaScript in the console:

for (var name in global) global.setPersistent("global."+name, true);

User JavaScript issues (Windows only)

Copy all user-created JavaScript files from %APPDATA%\Adobe\Acrobat\10.0\JavaScripts to %APPDATA%\Adobe\Acrobat\Privileged\10.0\JavaScripts.