4.2. Overview of Enterprise Security Client Configuration

The Enterprise Security Client is an intermediary frontend that provides connections between users (and their tokens), the Token Processing System, and certificate authority. The Enterprise Security Client provides two slightly different interfaces:

A local interface, based on XUL and JavaScript
A web-hosted interface which can be used for remote access, based on CGIs, HTML, and JavaScript

The primary Enterprise Security Client user interface, which is accessed from the local server, incorporates Mozilla XULRunner technology. XULRunner is a runtime package which hosts standalone applications based on XUL, an XML markup language with a rich feature set for user interfaces and offers several advantages over HTML for applications:

A wide UI widget set and greater control over the presentation.
Local markup to the client machine, so it has a greater privilege level than HTML.
JavaScript as the scripting language for convenient program logic scripting and the ability to leverage XPCOM technology.

All of the files for the web-hosted interface can be customized and edited to change the behavior or appearance of the Enterprise Security Client, within reason.

The Enterprise Security Client, in conjunction with the Token Processing System, supports different user profiles so that different types of users have different token enrollment paths. Both the Enterprise Security Client and TPS also support different token profiles, so that the certificate settings can be custom-defined for different types of tokens. Both of these configurations are set in the TPS, and are described in the Certificate System Administrator's Guide.

4.2.1. Enterprise Security Client File Locations

This reference shows the different directories and file locations for the different client machines.

On Red Hat Enterprise Linux 32-bit, the Enterprise Security Client is installed by its binary RPM to the default location, /usr/lib/esc-1.1.0/esc. On Red Hat Enterprise Linux 64-bit systems, the installation directory is /usr/lib64/esc-1.1.0/esc.

NOTE

The Enterprise Security Client uses some specific XUL configuration files, but, overall, the Enterprise Security Client uses the system XULRunner packages on Red Hat Enterprise Linux.

Table 4.1. Enterprise Security Client File and Directory Locations

File or Directory	Purpose
application.ini	XULRunner application configuration file.
components/	XPCOM components.
chrome/	Directory for Chrome components and additional application files for Enterprise Security Client XUL and JavaScript.
defaults/	Enterprise Security Client default preferences.
esc	The script which launches the Enterprise Security Client.

4.2.2. About the Preferences Configuration Files

The Enterprise Security Client is configured similarly to Mozilla applications, using preferences files. The primary configuration file is esc-prefs.js, which is installed with Enterprise Security Client. The second one is prefs.js in the Mozilla profiles directory, which is created when the Enterprise Security Client is first launched.

The Enterprise Security Client uses the Mozilla configuration preferences for each of the supported platforms. The default configuration file on Red Hat Enterprise Linux 32-bit is in /usr/lib/esc-1.1.0/defaults/preferences/esc-prefs.js. On Red Hat Enterprise Linux 64-bit, this is in /usr/lib64/esc-1.1.0/defaults/preferences/esc-prefs.js.

The esc-prefs.js file specifies the default configuration to use when the Enterprise Security Client is first launched. This includes parameters to connect to the TPS subsystem, set the password prompt, and configure Phone Home information. Each setting is prefaced by the word pref, then the parameter and value are enclosed in parentheses. For example:

pref(parameter, value);

The esc-prefs.js file parameters are listed in Table 4.2, “esc-prefs.js Parameters”. The default esc-prefs.js file is shown in Example 4.1, “Default esc-prefs.js File”.

Table 4.2. esc-prefs.js Parameters

Parameter	Description	Notes and Defaults
toolkit.defaultChromeURI	Defines the URL for the Enterprise Security Client to use to contact the XUL Chrome page.	("toolkit.defaultChromeURI", "chrome://esc/content/settings.xul")
esc.tps.message.timeout	Sets a timeout period, in seconds, for connecting to the TPS.	("esc.tps.message.timeout","90");
esc.disable.password.prompt	Enables the password prompt, which means that a password is required to read the certificate information off the smart card. The password prompt is disabled by default, so anyone can use the Enterprise Security Client. However, in security contexts, like when a company uses security officers to manage token operations, then this should be enabled, to restrict access to the Enterprise Security Client.	("esc.disable.password.prompt","yes");
esc.global.phone.home.url	Sets the URL to use to contact the TPS server. Normally, the Phone Home information is set on the token already through its applet. If a token does not have Phone Home information, meaning it has no way to contact the TPS server, then the Enterprise Security Client checks for a global default Phone Home URL. This setting is only checked if it is explicitly set. This setting also applies to every token formatted through the client, so setting this parameter forces all tokens to point to the same TPS. Only use this parameter if that specific behavior is desired.	("esc.global.phone.home.url", "http://server.example.com:7888/cgi-bin/home/index.cgi");
esc.global.alt.nss.db	Points to a directory that contains a common security database that is used by all Enterprise Security Client users on the server. Phone Home URL. This setting is only checked if it is explicitly set. If this is not set, then each user accesses only each individual profile security database, rather than a shared database.	prefs("esc.global.alt.nss.db", "C:/Documents and Settings/All Users/shared-db");

Example 4.1. Default esc-prefs.js File

The comments in this file are not included in the example.

#pref("toolkit.defaultChromeURI", "chrome://esc/content/settings.xul");
pref("signed.applets.codebase_principal_support",true); for internal use only  

pref("capability.principal.codebase.p0.granted", "UniversalXPConnect"); for internal use only  
pref("capability.principal.codebase.p0.id", "file://"); for internal use only  

pref("esc.tps.message.timeout","90");

#Do we populate CAPI certs on windows?
pref("esc.windows.do.capi","yes");

#Sample Security Officer Enrollment UI
#pref("esc.security.url","http://test.host.com:7888/cgi-bin/so/enroll.cgi");

#Sample Security Officer Workstation UI
#pref("esc.security.url","https://dhcp-170.sjc.redhat.com:7889/cgi-bin/sow/welcome.cgi");

#Hide the format button or not.
pref("esc.hide.format","no");

#Use this if you absolutely want a global phone home url for all tokens
#Not recommended!
#pref("esc.global.phone.home.url","http:/test.host.com:7888/cgi-bin/home/index.cgi");

When the Enterprise Security Client is launched, it creates a separate, unique profile directory for each user on the system. These profiles are stored in ~/.redhat/esc/alphanumeric_string.default/prefs.js in Red Hat Enterprise Linux 6.0.

NOTE

When the Enterprise Security Client requires any changes to a user's configuration values, the updated values are written to the user's profile area, not to the default JavaScript file.

Table 4.3, “prefs.js Parameters” lists the most relevant parameters for the prefs.js file. Editing this file is tricky. The prefs.js file is generated and edited dynamically by the Enterprise Security Client, and manual changes to this file are overwritten when the Enterprise Security Client exits.

Table 4.3. prefs.js Parameters

Parameter	Description	Notes and Defaults
esc.tps.url	Sets a URL for the Enterprise Security Client to use to connect to the TPS. This is not set by default.
esc.key.`token_ID`.tps.url	Sets the hostname and port to use to contact a TPS. If this Phone Home information was not burned into the card at the factory, it can be manually added to the card by adding the TPS URL, an enrollment page URL, the issuer's name, and Phone Home URL.	("esc.key.token_ID.tps.url" = "http://server.example.com:7888/nk_service");
esc.key.token_ID.tps.enrollment-ui.url	Gives the URL to contact the enrollment page for enroll certificates on the token. If this Phone Home information was not burned into the card at the factory, it can be manually added to the card by adding the TPS URL, an enrollment page URL, the issuer's name, and Phone Home URL.	("esc.key.token_ID.tps.enrollment-ui.url" = "http://server.example.com:7888/cgi_bin/esc.cgi?");
esc.key.token_ID.issuer.name	Gives the name of the organization enrolling the token.	("esc.key.token_ID.issuer.name" = "Example Corp");
esc.key.token_ID.phone.home.url	Gives the URL to use to contact the Phone Home functionality for the TPS. The global Phone Home parameter sets a default to use with any token enrollment, if the token does not specify the Phone Home information. By setting this parameter to a specific token ID number, the specified Phone Home parameter applies only to that token.	("esc.key.token_ID.phone.home.url" = "http://server.example.com:7888/cgi-bin/home/index.cgi?");
esc.security.url	Points to the URL to use for security officer mode. If this is pointed to the security officer enrollment form, then the Enterprise Security Client opens the forms to enroll security officer tokens. If this is pointed to the security officer workstation URL, then it opens the workstation to enroll regular users with security officer approval.	("esc.security.url","http`s`://server.example.com:7888`/cgi-bin/so/enroll.cgi`");

4.2.3. About the XUL and JavaScript Files in the Enterprise Security Client

Smart Card Manager stores the XUL markup and JavaScript functionality in /usr/lib[64]/esc-1.1.0/chrome/content/esc/.

The primary Enterprise Security Client XUL files are listed in Table 4.4, “Main XUL Files”.

Table 4.4. Main XUL Files

Filename	Purpose
settings.xul	Contains the code for the Settings page.
esc.xul	Contains the code for the Enrollment page.
config.xul	Contains the code for the configuration UI.

The primary Smart Card Manager JavaScript files are listed in the following table.

Table 4.5. Main JavaScript Files

Filename	Purpose
ESC.js	Contains most of the Smart Card Manager JavaScript functionality.
TRAY.js	Contains the tray icon functionality.
AdvancedInfo.js	Contains the code for the Diagnostics feature.
GenericAuth.js	Contains the code for the authentication prompt. This prompt is configurable from the TPS server, which requires dynamic processing by the Smart Card Manager.