5   Preference Basics

Administrators typically configure installers before deployment via preferences and properties so that all machines across their organization have the requisite settings. Since manipulation of client settings through the user interface is not scalable, Adobe provides the Customization Wizard so that changes can be made once. Manual and post-deployment configuration is also possible. All of the Acrobat family of products are built on a uniform platform, share a common set of preferences, and are similar in their configuration details.

Note

Adobe strongly recommends that you do not make changes to the registry unless you are knowledgeable about editing and troubleshooting application settings. Improper use of this feature can result in the corruption of critical system files Before modifying the registry, make sure you understand what product versions are supported, what the default settings are, and how to create new keys.

5.1   What you must know

Before continuing, you should know that:

• The tables and examples use the Windows registry. Naming conventions and paths are relatively similar on Macintosh, Unix, and Linux systems.

• There are two types of settings which reside in different locations: a per-user setting and a global setting which require administrative privileges to change.

• Some features can be locked via global settings so the end users can’t change them.

• Feature lockdown is available on Macintosh beginning with 11.0.

• Preferences are identical across the Acrobat product family.

• Know your feature before proceeding because some feature interact with others. For example, in Acrobat 9.x and later, internet access permissions can be set via the trust manager URL settings, certified documents, enhanced security, and privileged locations. Each of these can allow a PDF to access a networked file, and the most permissive setting generally applies.

• Just because you don’t see the preference doesn’t mean it’s not there and/or cannot be used:

  • Some preferences exist internally and are not visually apparent in the registry until after a feature is used. Subdirectories may also appear as the code is exercised.
  • Many features are not enabled by default and their related preferences must be manually created.
  • Many preferences cannot be set thought the UI and must be manually created.
  • The easiest way to configure the product is to exercise the UI and then manually massage the preferences which don’t have a corresponding UI.

5.2   Windows

5.2.1   Locations

Preferences may be configured per user or per machine (by an administrator). Windows uses the registry files to manage preferences.

User preferences

HKEY_CURRENT_USER (HKCU) stores settings for the currently logged-in user:

• HKEY_CURRENT_USER\Software\Adobe\(product name)\(version)\

Note

Some HKCU keys have a matching key in FeatureLockdown.

Administrator (machine level) preferences

Admin-only keys require administrator privileges to modify. HKEY_LOCAL_MACHINE (HKLM) stores global settings for the local computer.

• Lockable keys (32 bit): HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Adobe\(product name)\(version)\FeatureLockDown\
• Lockable keys (64 bit): HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Adobe\(product name)\(version)\FeatureLockdown
• Non lockable machine keys: HKEY_LOCAL_MACHINE\SOFTWARE\Adobe\(product name)\(version)\

Note

Preferences for all versions are stored in a version hive under the product name.

5.2.2   Data types

When adding new keys to the registry it is critical that you get the Value data and Name fields correct as shown below. Most preferences have a data type prefix. These need to be added in the format that the application can recognize.

Windows data types

Prefix	Data Type	Registry type	Description
a	atom	REG_SZ	The string may be UTF-8 and can therefore include Unicode. The Value Data field is typically entered as text. For example, a value for cHandlers:aPrivKey could be Adobe.PPKLite.
b	bool	REG_DWORD	0 (false) or 1 (true).
c	cab	N/A	Containers that hold keys are preceded by a “c” on Windows.
i	int	REG_DWORD	An integer.
s	string	REG_BINARY	ASCII only.
t	text	REG_SZ	The string may be UTF-8 and can include Unicode. The Value Data field is entered as text. For example, a value for cEDC:tLastServerURL could be https://aps.serv.com:123. Note: 7.x and earlier use REG_BINARY and tValue.
a, s, or t	ASPath	See a, s, and t above.	ASPath objects require three components: aFS: The file system for the path, such as DOS. sDI: A string of device independent path. tDIText: The device independent path again in Unicode.

5.2.3   Administrator locking

Many preferences may be locked so that end users cannot change them via the product’s user interface. To do so, set them in the location described above. Some preferences only reside in the lockdown location and do not have a counterpart in the user preference area. For details about specific preferences, refer to the Preference Reference.

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Adobe\Adobe Acrobat\10.0\FeatureLockDown]
"bUsageMeasurement"=dword:00000000
"bBrowserIntegration"=dword:00000000

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Adobe\Adobe Acrobat\10.0\FeatureLockDown\cDefaultExecMenuItems]
"tWhiteList"="Close|GeneralInfo|Quit|FirstPage|PrevPage|NextPage|LastPage|ActualSize|FitPage|FitWidth|FitHeight|SinglePage|OneColumn|TwoPages|TwoColumns|ZoomViewIn|ZoomViewOut|ShowHideBookmarks

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Adobe\Adobe Acrobat\10.0\FeatureLockDown\cDefaultLaunchAttachmentPerms]
"tBuiltInPermList"="version:1|.ade:3|.adp:3|.app:3|.arc:3|.arj:3|.asp:3|.bas:3|.bat:3|.bz:3|.bz2:3|.cab:3|.chm:3|.class:3|.cmd:3|.com:3|.command:3|.cpl:3|.crt:3|.csh:3|.desktop:3|.dll:3|.exe:3|.fxp:3|.gz:3|.hex:3

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Adobe\Adobe Acrobat\10.0\FeatureLockDown\cDefaultLaunchURLPerms]
"tFlashContentSchemeWhiteList"="http|https|ftp|rtmp|rtmpe|rtmpt|rtmpte|rtmps|mailto"
"tSponsoredContentSchemeWhiteList"="http|https"
"tSchemePerms"="version:2|shell:3|hcp:3|ms-help:3|ms-its:3|ms-itss:3|its:3|mk:3|mhtml:3

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Adobe\Adobe Acrobat\10.0\FeatureLockDown\cJavaScriptPerms]
"tBlackList"="Doc.exportXFAData|Util.CharToByte"

5.3   Macintosh

5.3.1   Locations

Preferences may be configured per user or per machine (by an administrator). Macintosh uses plist files to manage preferences.

User preferences

The name varies with the product version:

• 9.x: Users/<user name>/Library/Preferences/com.adobe.<product name>_x86_9.0.plist
• 10.x and later: Users/<user name>/Library/Preferences/com.adobe.<product name>.plist

Note

For 10.x and later, preferences for all versions are stored under a version hive. Thus, the <10> and <11> hives reside in the same file.

Administrator (machine level) preferences

Locking is not supported in versions prior to 11.0. For 11.0 and later, admin preferences can be set in <machine root>/Library/Preferences/com.adobe.(Acrobat.Pro | Reader).plist. Within this file the path to a specific lockable preference is identical to Windows.

Note

Preferences for all versions are stored under a version hive. Thus, the <11> and any future hives reside in the same file.

<dict>
  <key>11</key>
    <dict>
      <key>FeatureLockdown</key>
        <dict>
          <key>bUpdater</key>
          <false/>
        </dict>
    </dict>
</dict>

5.3.2   Data types

When adding new preferences the key name and data type must be correct. Every preference has a data type as indicated by the integer field under the key. These need to be added in the format that the application can recognize.

For example, to force a digest comparison with EnforceSecureChannel:

1. Open ~root/com.adobe.(product name)_(product version).plist.
2. Navigate to [Security\PubSec].
3. Under PubSec, add a new key EnforceSecureChannel.
4. Create an array element with an integer element specifying the data type and the boolean value.

<key>EnforceSecureChannel</key>
<array>
  <integer>0</integer>
  <false/>
</array>

Macintosh data types

Integer	Data Type	Description
0	boolean	true or false
1	int	An integer
2	atom	The string may be UTF-8 and can therefore include Unicode. The field typically contains text. For example, a value for Handlers:PrivKey could be Adobe.PPKLite.
3	number	Double
4	text	The string may be UTF-8 and can include Unicode. The Value Data field is entered as text. For example, a value for EDC:LastServerURL could be https://aps.serv.com:123.
5	string	ASCII only
6	data	A binary blob
7		Unused
8	dict	Containers that hold additional keys.

5.3.3   Administrator locking

Many preferences may be locked so that end users cannot change them via the produt’s user interface. To do so, set them in the location described above. Some preferences only reside in the lockdown location and do not have a counterpart in the user preference area. For details about specific preferences, refer to the Preference Reference.

The feature lockdown file is a system-level plist file in for a root account. These files do not exist by default. The permissions of the plist file should be –755.

To lock preferences:

1. Go to /Applications/(product name)/(product name).app/.
2. Right click and choose Show Package Contents.
3. Go to Contents/MacOS/Preferences.
4. Create or open the FeatureLockdown file.
5. Edit as needed.
6. Save and close the file.

Note

When using the Mac Wizard, keep in mind it creates an identical file in /Library/Preferences/. If a plist already exists on a client machine at that location, it is replaced at deployment time.

Feature lockdown file construction

The file format is an xml plist and many of its details parallel the way feature lockdown is implemented for Windows.

• Preferences always reside under the appropriate version hive (e.g. 10, 11).

• Not all preferences can be locked, but what can be locked is identical for Windows and Macintosh.

• The preference is prepended by the data type (version and section nodes do not have a data type). The following is supported:

  • b: boolean
  • t: string
  • c: dictionary

The xml structure/hierarchy mirrors the registry path. For example:

• Windows: [<version>\FeatureLockDown]"bUpdater"
• Mac: <version>/FeatureLockdown/bUpdater

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>11</key>
<dict>
  <key>FeatureLockdown</key>
    <dict>
       <key>bUpdater</key>
       <false/>
    </dict>
</dict>
</dict>

In the example above, the Updater preference is represented as a single boolean plist key named bUpdater and the initial letter ‘b’ signifies the type of preference. This value disables the Updater. It also removes UI items, including Help > Update Acrobat XI Pro and the Updater settings under Preferences.

Lockdown example

The example below selectively blacklists the JavaScript API App.alert for all PDFs.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>11</key>
      <dict>
        <key>FeatureLockdown</key>
          <dict>
          <key>cJavaScriptPerms</key>
            <dict>
              <key>tBlackList</key>
              <string>App.alert</string>
            </dict>
          </dict>
       </dict>
  </dict>
</plist>

5.4   Unix

Preferences may be configured per user or per machine (by an administrator). Unix uses prefs files to manage preferences.

5.4.1   Locations

User preferences

Preferences are stored in a preferences file in the users’ home directory. For example, .adobe/Acrobat/10.0/Preferences/reader_prefs.

/AVPrivate [/c << /ChooseLangAtStartup [/b false]
/EULAAcceptanceTime [/i 1169559777]
/ForceXFADirectRender [/b true]
/SplashDisplayedAtStartup [/b true]
/UnixLanguageStartup [/i 4542037]
/showEULA [/b false]
>>]

Administrator (machine level) preferences

5.4.2   Data types

Unix data types are represented by the same type prefix as Windows. Refer to the example above for implementation details.

5.4.3   Administrator locking

Many preferences may be locked so that end users cannot change them via the produt’s user interface. To do so, set them in the location described above. Some preferences only reside in the lockdown location and do not have a counterpart in the user preference area. For details about specific preferences, refer to the Preference Reference.

The path to lockable preferences is constructed as follows: [InstallationLocation]/Adobe/(product name + version)/(product name)/GlobalPrefs/(product name)_prefs. For example, for Adobe Reader 10.x:

[ReaderInstallationLocation]/Adobe/Reader10/Reader/GlobalPrefs/reader_prefs

5.5   Sample use case

Modifying existing or creating custom preferences requires some knowledge of the supported naming conventions and data types. In general:

• “Hives” are usually the top-level HKCU, HKLM, and other directories, but it’s also common to refer to subdirectories by the same name.
• Folders/directories that contain the actual preferences (keys), appear in the left-hand window, these often are the home for sub containers.
• Some keys are containers called “cabs” (Windows) or “dictionaries” (Mac). These names are always prepended by a “c” on Windows. For example, cAdobe_ChainBuilder and cAcceptablePolicyOIDs. The lowest level key container is an array. Item names are always “c” + <index number>. Thus, an array under cAcceptablePolicyOIDs could be c0, c1, c2, c3, and so on. The subkey structure has a dependency on the data type of the parent container. Cabs at the c0, c1, c2, etc. level use a subdirectory named cValue that contain the actual key data. For all other data types, store the value directly at the c0, c1, c2, etc. level
• The lowest key level defines the actual preference. It is always a name/value pair.

To create a new preference on Windows for example:

1. Open the registry editor.
2. Look up the preference you want to set in the Preference Reference or the pertinent document. You’ll need to know the path, name, and value.
3. Navigate to the required location.
4. Create any container keys you might need on the left-hand side of the editor.
5. Highlight that containing key and in the right hand side, right click and choose New > <some data value>.
6. Enter a name.
7. Right click on the preference name and enter a value.

5.6   APIs and the SDK

Many preferences are exposed in the API. The plugins use the cross platform ASCab preference mechanism supported by all Acrobat products. This mechanism uses calls such as AVAppGetPrefCab and AVAppSetPrefCab, that were introduced in Acrobat 5.0. Refer to the Acrobat and PDF Library API Reference for details on these calls.