Managing Smart Cards with the Enterprise Security Client
Updated for Red Hat Certificate System 9.4
Abstract
Chapter 1. Introduction to the Enterprise Security Client
- Supports Global Platform-compliant smart cards like Gemalto 64K V2 and Safenet 300J Java smart cards.
- Enrolls security tokens so they are recognized by TPS.
- Maintains the security token, such as re-enrolling a token with TPS.
- Provides information about the current status of the token or tokens being managed.
- Supports server-side key generation through the TPS and DRM subsystems so that keys can be archived and recovered on a separate token if a token is lost.
1.1. Red Hat Enterprise Linux, Single Sign-On, and Authentication
- A user inserts a smart card into the card reader. This is detected by the pluggable authentication modules (PAM) on Red Hat Enterprise Linux.
- The system maps the certificate to the user entry and then compares the presented certificates on the smart card to the certificates stored in the user entry.
- If the certificate is successfully validated against the key distribution center (KDC), then the user is allowed to log in.
1.2. Red Hat Certificate System and the Enterprise Security Client
- The Token Processing System (TPS) interacts with smart cards to help them generate and store keys and certificates for a specific entity, such as a user or device. Smart card operations go through the TPS and are forwarded to the appropriate subsystem for action, such as the Certificate Authority to generate certificates or the Data Recovery Manager to archive and recover keys.
- The Token Key Service (TKS) generates, or derives, symmetric keys used for communication between the TPS and smart card. Each set of keys generated by the TKS is unique because they are based on the card's unique ID. The keys are formatted on the smart card and are used to encrypt communications, or provide authentication, between the smart card and TPS.
- The Certificate Authority (CA) creates and revokes user certificates stored on the smart card.
- Optionally, the Data Recovery Manager (DRM) archives and recovers keys for the smart card.

Figure 1.1. How Certificate System Manages Smart Cards
Chapter 2. Installing the Enterprise Security Client
2.1. Supported Platforms for the Client
2.2. Supported Smart Cards
2.3. Installing and Uninstalling the Enterprise Security Client on Red Hat Enterprise Linux
2.3.1. Installing the Client
- Downloading an ISO image from the Customer Portal.
- Using the Red Hat
yumutility
yum command-line utility, as follows:
# yum install esc
yum command completes successfully, all of the necessary Enterprise Security Client RPMs will be installed and ready for use.
Note
yum utility was used to install the Enterprise Security Client, there is no need for further installation; the client has already been installed. The following procedure is for installing from a CD image.
- As
root, install the Enterprise Security Client packages:yum install esc
/usr/lib/esc-1.1.0 on Red Hat Enterprise Linux 32-bit systems and /usr/lib64/esc-1.1.0 on Red Hat Enterprise Linux 64-bit system. The esc shell script is installed in /usr/bin/esc. The Enterprise Security Client can be launched by typing esc at a command prompt.
escd) which runs silently, waiting for a smart card to be inserted. When an unenrolled smart card is inserted, the daemon automatically launches the client UI, and the Enterprise Security Client guides the user through the enrollment process. The client can also be launched manually by selecting System Settings, then Smart Card Manager, from the menu.
2.3.2. Uninstalling on Red Hat Enterprise Linux
- Unplug all USB tokens.
- Stop the Enterprise Security Client.
- Log in as
root, and userpm -evto remove the Enterprise Security Client RPM:# yum remove esc
Note
Update the version numbers of the RPM files to match your version. - Remove any remaining files in the installation directory.
Chapter 3. Using the Enterprise Security Client
3.1. Tray Icons for the Enterprise Security Client

Figure 3.1. Example Token Tray Icon and Tool Tip
3.2. Launching Enterprise Security Client
3.2.1. Opening the Enterprise Security Client on Red Hat Enterprise Linux
escd) from the command line:
esc

3.3. Configuring Phone Home
Note
op.format.userKey.issuerinfo.enable=true op.format.userKey.issuerinfo.value=http://server.example.com
3.3.1. About Phone Home Profiles
esc-prefs.js file for the esc.global.phone.home.url parameter.

Figure 3.2. Prompt for Phone Home Information
3.3.2. Setting Global Phone Home Information
esc-prefs.js, has a parameter which allows a global Phone Home URL default to be set. This parameter is esc.global.phone.home.url and is not in the file by default.
- Remove any existing Enterprise Security Client user profile directory. Profile directories are created automatically when a smart card is inserted. On Red Hat Enterprise Linux, the profile directory is
~/.redhat/esc. - Open the
esc-prefs.jsfile. On Red Hat Enterprise Linux 5.6 (32-bit), the profile directory is/usr/lib/esc-1.1.0/defaults/preferences. On 64-bit systems, this is/usr/lib64/esc-1.1.0/defaults/preferences. - Add the global Phone Home parameter line to the
esc-prefs.jsfile. For example:pref("pref("esc.global.phone.home.url","https://localhost:8443/tps/phoneHome");");The URL can reference a machine name, a fully-qualified domain name, or an IPv4 or IPv6 address, depending on the DNS and network configuration.
3.3.3. Adding Phone Home Information to a Token Manually
- The preferred method is that the information is burned onto the token at the factory. When the tokens are ordered from the manufacturer, the company supplies detailed information on how the tokens should be configured when shipped.
- If tokens are blank, the company IT department can supply the information when formatting small groups of tokens.
~/.redhat/esc/alphanumeric_string.default/prefs.js file:
- The TPS server and port. For example:
"esc.key.token_ID.tps.url" = "http://server.example.com:7888/nk_service"
- The TPS enrollment interface URL. For example:
"esc.key.token_ID.tps.enrollment-ui.url" = "http://server.example.com:7888/cgi_bin/esc.cgi?"
- The issuing company name or ID. For example:
"esc.key.token_ID.issuer.name" = "Example Corp"
- The Phone Home URL. For example:
"esc.key.token_ID.phone.home.url" = "https://localhost:8443/tps/phoneHome"
- Optionally, a default browser URL to access when an enrolled smart card is inserted.
"esc.key.token_ID.EnrolledTokenBrowserURL" = "http://www.test.example.com"
prefs.js file are listed in Table 5.2, “prefs.js Parameters”.
Note
3.3.4. Configuring the TPS to Use Phone Home
index.cgi in the /var/lib/pki-tps/cgi-bin/home directory; this prints the Phone Home information to XML.
Example 3.1. TPS Phone Home Configuration File
<ServiceInfo><IssuerName>Example Corp</IssuerName>
<Services>
<Operation>http://server.example.com:7888/nk_service ## TPS server URL
</Operation>
<UI>http://server.example.com:7888/cgi_bin/esc.cgi ## Optional
Enrollment UI
</UI>
<EnrolledTokenBrowserURL>http://www.test.url.com ## Optional
enrolled token url
</EnrolledTokenBrowserURL>
</Services>
</ServiceInfo>https://localhost:8443/tps/phoneHome; the URL can reference the machine name, fully-qualified domain name, or an IPv4 or IPv6 address, as appropriate. When the TPS configuration URI is accessed, the TPS server is prompted to return all of the Phone Home information to the Enterprise Security Client.
3.4. Setting up Users to Be Enrolled
CS.cfg:
auth.instance.0.baseDN=dc=example,dc=comauth.instance.0.hostport=server.example.com:389
/usr/bin/ldapmodify -a -D "cn=Directory Manager" -w secret-p 389 -h server.example.comdn: uid=jsmith,ou=People,dc=example,dc=comobjectclass: person objectclass: inetorgperson objectclass: top uid: jsmith cn: John Smith email: jsmith@example.com userPassword: secret
3.5. Managing Smart Cards

Figure 3.3. Manage Smart Cards Page
3.5.1. Formatting the Smart Card
- Insert a supported smart card into the computer. Ensure that the card is listed in the Active Smart Cards table.
- In the Smart Card Functions section of the Manage Smart Cards screen, click .
- If the TPS has been configured for user authentication, enter the user credentials in the authentication dialog, and click .
- During the formatting process, the status of the card changes to BUSY and a progress bar is displayed. A success message is displayed when the formatting process is complete. Click to close the message box.
- When the formatting process is complete, the Active Smart Cards table shows the card status as UNINITIALIZED.
3.5.2. Resetting a Smart Card Password
- Insert a supported smart card into the computer. Ensure that the card is listed in the Active Smart Cards table.
- In the Smart Card Functions section of the Manage Smart Cards screen, click to display the Password dialog.
- Enter a new smart card password in the Enter new password field.
- Confirm the new smart card password in the Re-Enter password field, and then click .

- If the TPS has been configured for user authentication, enter the user credentials in the authentication dialog, and click .
- Wait for the password to finish being reset.
3.5.3. Viewing Certificates
- Insert a supported smart card into the computer. Ensure that the card is listed in the Active Smart Cards table.
- Select the card from the list, and click .
This displays basic information about the certificates stored on the card, including the serial number, certificate nickname, and validity dates. - To view more detailed information about a certificate, select the certificate from the list and click .

3.5.4. Importing CA Certificates
- Open the CA's end user pages in a web browser.
http
s://server.example.com:9444/ca/ee/ca/ - Click the Retrieval tab at the top.
- In the left menu, click the Import CA Certificate Chain link.
- Choose the radio button to download the chain as a file, and remember the location and name of the downloaded file.
- Open the Enterprise Security Client.

- Click the button.

- Click the Authorities tab.
- Click Import.

- Browse to the CA certificate chain file, and select it.
- When prompted, confirm that you want to trust the CA.
3.5.5. Adding Exceptions for Servers
- Open the Enterprise Security Client.

- Click the button.

- Click the Servers tab.
- Click Add Exception.

- Enter the URL, including any port numbers, for the site or service which the smart card will be used to access. Then click the button to download the server certificate for the site.

- Click to add the site to the list of allowed sites.
3.5.6. Enrolling Smart Cards
Note
- Insert a supported, unenrolled smart card into the computer. Ensure that the card is listed in the Active Smart Cards table.
- Click to display the Password dialog.
- Enter a new key password in the Enter a password field.Confirm the new password in the Re-Enter a password field.
- Click to begin the enrollment.
- If the TPS has been configured for user authentication, enter the user credentials in the authentication dialog, and click .If the TPS has been configured to archive keys to the DRM, the enrollment process will begin generating and archiving keys.

3.6. Diagnosing Problems
- Open the Enterprise Security Client.

- Select the smart card to check from the list.
- Click the button.

- This opens the window for the selected smart card.

- The Enterprise Security Client version number.
- The version information for the Xulrunner framework upon which the client is running.
- The number of cards detected by the Enterprise Security Client.
- The version of the applet running on the smart card.
- The alpha-numeric ID of the smart card.
- The card's status, which can be any of the three things:
- NO_APPLET No key was detected.
- UNINITIALIZED. The key was detected, but no certificates have been enrolled.
- ENROLLED. The detected card has been enrolled with certificate and card information.
- The card's Phone Home URL. This is the URL from which all Phone Home information is obtained.
- The card issuer name, such as
Example Corp. - The card's answer-to-reset (ATR) string. This is a unique value that can be used to identify different classes of smart cards. For example:
3BEC00FF8131FE45A0000000563333304A330600A1
- The TPS Phone Home URL.
- The TPS server URL. This is retrieved through Phone Home.
- The TPS enrollment form URL. This is retrieved through Phone Home.
- Detailed information about each certificate contained on the card.
- A running log of the most recent Enterprise Security Client errors and common events.
3.6.1. Errors
- The Enterprise Security Client does not recognize a card.
- Problems occur during a smart card operation, such as a certificate enrollment, password reset, or format operation.
- The Enterprise Security Client loses the connection to the smart card. This can happen when problems occur communicating with the
PCSCdaemon. - The connection between the Enterprise Security Client and TPS is lost.
tps-debug.log or tps-error.log files, depending on the cause for the message.
Table 3.1. Smart Card Error Codes
| Return Code | Description |
|---|---|
| General Error Codes | |
| 6400 | No specific diagnosis |
| 6700 | Wrong length in Lc |
| 6982 | Security status not satisfied |
| 6985 | Conditions of use not satisfied |
| 6a86 | Incorrect P1 P2 |
| 6d00 | Invalid instruction |
| 6e00 | Invalid class |
| Install Load Errors | |
| 6581 | Memory Failure |
| 6a80 | Incorrect parameters in data field |
| 6a84 | Not enough memory space |
| 6a88 | Referenced data not found |
| Delete Errors | |
| 6200 | Application has been logically deleted |
| 6581 | Memory failure |
| 6985 | Referenced data cannot be deleted |
| 6a88 | Referenced data not found |
| 6a82 | Application not found |
| 6a80 | Incorrect values in command data |
| Get Data Errors | |
| 6a88 | Referenced data not found |
| Get Status Errors | |
| 6310 | More data available |
| 6a88 | Referenced data not found |
| 6a80 | Incorrect values in command data |
| Load Errors | |
| 6581 | Memory failure |
| 6a84 | Not enough memory space |
| 6a86 | Incorrect P1/P2 |
| 6985 | Conditions of use not satisfied |
3.6.2. Events
- Simple events such as card insertions and removals, successfully completed operations, card operations that result in an error, and similar events.
- Errors are reported from the TPS to the Enterprise Security Client.
- The NSS crypto library is initialized.
- Other low-level smart card events are detected.
Chapter 4. Using Smart Cards for Web and Mail Clients
Table 4.1. PKCS #11 Module Locations
| Platform | Module Name | Location |
|---|---|---|
| Red Hat Enterprise Linux | onepin-opensc-pkcs11.so | /usr/lib64/ |
4.1. Setting up Browsers to Support SSL for Tokens
- Open the menu and select .If the menu bar is not visible in Firefox, press the Alt key to temporarily display it.
- In the entry, select the tab, and click the button.
- Add the PKCS #11 driver:
- Click the button.
- Enter a module name.
- Click , select the Enterprise Security Client PKCS #11 driver library, and click .

- If the CA is not yet trusted, download and import the CA certificate.
- Open the SSL End Entity page on the CA. For example:
http
s://server.example.com:9444/ca/ee/ca/ - Click the Retrieval tab, and then click Import CA Certificate Chain.
- Click Download the CA certificate chain in binary form and then click .
- Choose a suitable directory to save the certificate chain, and then click .
- Click , and select the Advanced tab.
- Click the button.
- Click , and import the CA certificate.
- Set the certificate trust relationships.
- Click , and select the Advanced tab.
- Click the button.
- Click , and set the trust for websites.
Chapter 5. Setting up Enterprise Security Client
Note
5.1. Overview of Enterprise Security Client Configuration
- 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
- 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.
5.1.1. About the Preferences Configuration Files
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.
- 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.
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);
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
#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");~/.redhat/esc/alphanumeric_string.default/prefs.js.
Note
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?"); |
5.2. Configuring SSL Connections with the TPS
- Download the CA certificate used by the TPS.
- Open the CA's end user pages in a web browser.
http
s://server.example.com:9444/ca/ee/ca/ - Click the Retrieval tab at the top.
- In the left menu, click the Import CA Certificate Chain link.
- Choose the radio button to download the chain as a file, and remember the location and name of the downloaded file.
- Open the Enterprise Security Client.

- Import the CA certificate.
- Click the button.

- Click the Authorities tab.
- Click Import.

- Browse to the CA certificate chain file, and select it.
- When prompted, confirm that you want to trust the CA.
- The Enterprise Security Client needs to be configured to communicate with the TPS over SSL; this is done by setting the Phone Home URL, which is the default URL the Enterprise Security Client uses to connect to the TPS.
- Insert a new, blank token into the machine.Blank tokens are unformatted, so they do not have an existing Phone Home URL, and the URL must be set manually. Formatted tokens (tokens can be formatted by the manufacturer or by your IT department) already have the URL set, and thus do not prompt to set the Phone Home URL.
- Fill in the new TPS URL with the SSL port information. For example:
http
s://server.example.com:7890/cgi-bin/home/index.cgi - Click the button to send a message to the TPS.If the request is successful, the client opens a dialog box saying that the Phone Home URL was successfully obtained.
5.4. Disabling LDAP Authentication for Token Operations
- Stop the TPS subsystem.
systemctl stop pki-tps
- Open the TPS configuration file.
vim /var/lib/pki-tps/conf/CS.cfg
- Set the authentication parameters to
false.op.operation_type.token_type.loginRequest.enable=false op.operation_type.token_type.auth.enable=false
The operation_type is the token operation for which LDAP authentication is being disabled, such asenroll,format, orpinreset. Disabling authentication for one operation type does not disable it for any other operation types.The token_type is the token profile. There are default profiles for regular users, security officers, and the users enrolled by security officers. There can also be custom token types for other kinds of users or certificates.For example:op.
enroll.userKey.loginRequest.enable=false op.enroll.userKey.pinReset.enable=false - Restart the TPS subsystem.
systemctl restart pki-tomcatd@pki-tomcat.service
Appendix A. Revision History
| Revision History | |||
|---|---|---|---|
| Revision 9.4-0 | Thu Oct 25 2018 | ||
| |||
| Revision 9.3-1 | Tue Apr 10 2018 | ||
| |||
| Revision 9.2-0 | Tue Aug 01 2017 | ||
| |||
| Revision 9.1-1 | Thu Mar 09 2017 | ||
| |||
| Revision 9.1-0 | Tue Nov 01 2016 | ||
| |||
| Revision 8.9-0 | Thu Jul 02 2015 | ||
| |||
