Chapter 5. Setting up Enterprise Security Client

The Enterprise Security Client is now based on Mozilla XULRunner, allowing the preferences facility built into Mozilla to be used for simple configuration of the Enterprise Security Client. A simple UI, discussed in Chapter 3, Using the Enterprise Security Client, manages most important configuration settings.

Note

The Enterprise Security Client can be launched without requiring extra configuration.

5.1. 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 Red Hat Certificate System  Planning, Installation, and Deployment Guide.

5.1.1. 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. A default configuration file is located in the following directories on each platform:
  • On Red Hat Enterprise Linux 32-bit, this 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, to 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 5.1, “esc-prefs.js Parameters”. The default esc-prefs.js file is shown in Example 5.1, “Default esc-prefs.js File”.

Table 5.1. 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 enable the password prompt 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.
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 5.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");

#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. On Red Hat Enterprise Linux, these profiles are stored in ~/.redhat/esc/alphanumeric_string.default/prefs.js.

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 5.2, “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 5.2. 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" = "https://test.host.com:8443/tps/tps");
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?");