Red Hat Certificate System 7.3 Managing Smart Cards with the Enterprise Security Client 7.
Red Hat Certificate System 7.3 This guide is for regular users of Certificate System subsystems. It explains how to manage personal certificates and keys using the Enterprise Security Client, a simple interface which formats and manages smart cards.
Red Hat Certificate System 7.3: Managing Smart Cards with the Enterprise Security Client Copyright © 2008 Red Hat, Inc. Copyright © 2008 Red Hat. This material may only be distributed subject to the terms and conditions set forth in the Open Publication License, V1.0 or later with the restrictions noted below (the latest version of the OPL is presently available at http://www.opencontent.org/openpub/).
Red Hat Certificate System 7.
About This Guide ...................................................................................................... vii 1. What Is in This Guide .................................................................................... vii 2. Additional Reading ........................................................................................ vii 3. Examples and Formatting ............................................................................. viii 4. Giving Feedback ..............................
Red Hat Certificate System 7.3 1. Configuration ................................................................................................49 2. Enterprise Security Client Mac TokenD ..........................................................51 3. Enterprise Security Client XUL and Javascript Functionality .............................51 4. Quick Javascript UI Guide .............................................................................52 5. Enterprise Security Client File Locations .............
About This Guide The Enterprise Security Client is a simple user interface which formats and manages smart cards. This guide is intended for everyday users of Certificate System, who will use the Enterprise Security Client to manage their smart cards. Certificate System agents should read the Certificate System Agent's Guide for information on how to perform agent tasks, such as handling certificate requests and revoking certificates.
About This Guide • Certificate System Administration Guide explains how to install, configure, and use Red Hat Certificate System. Additional Certificate System information is provided in the Certificate System SDK, an online reference to HTTP interfaces, javadocs, samples, and tutorials related to Certificate System. A downloadable zip file of this material is available for user interaction with the tutorials.
Giving Feedback NOTE A note provides additional information that can help illustrate the behavior of the system or provide more detail for a specific issue. TIP A tip is typically an alternative way of performing a task. IMPORTANT Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot. CAUTION and WARNING A caution indicates an act that would violate your support agreement.
About This Guide • Give a clear title for the bug. For example, "Incorrect command example for setup script options" is better than "Bad example". We appreciate receiving any feedback — requests for new sections, corrections, improvements, enhancements, even new ways of delivering the documentation or new styles of docs. You are welcome to contact Red Hat Content Services directly at mailto:docs@redhat.com. 5. Revision History Revision History Revision 7.3.
Chapter 1. Overview of the Enterprise Security Client The Enterprise Security Client is a tool for Red Hat Certificate System which simplifies managing smart cards. End users can use security tokens (smart cards) to store user certificates used for applications such as single sign-on access and client authentication. End users are issued the tokens containing certificates and keys required for signing, encryption, and other cryptographic functions.
Chapter 1. Overview of the Enterprise Security Client 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.
Features • The Enterprise Security Client user interface 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. XUL has the following advantages over HTML for applications: • XUL provides a wide UI widget set and greater control over the presentation. • XUL markup is local to the client machine, so it has a greater privilege level than HTML.
Chapter 1. Overview of the Enterprise Security Client • Windows. When right-clicked, the tray icon shows a simple menu with options to Manage Smart Card, which opens the Enterprise Security Client interface, and to Exit Smart Card Manager, which exits the Enterprise Security Client. The exit option in that menu is the only want to exist the Enterprise Security Client on Windows; clicking the X in the top right corner minimizes Enterprise Security Client to the tray.
Chapter 2. Installing the Enterprise Security Client The Enterprise Security Client is packaged as a set of installation executables or RPMs and other files that are part of the complete Red Hat Certificate System distribution. These are listed in the installation chapter of the Certificate System Administrator's Guide. 1.
Chapter 2. Installing the Enterprise Security Client The preferred method of obtaining RPMs is using the up2date command-line utility, as follows: # up2date esc If the up2date command completes successfully, all of the necessary Enterprise Security Client RPMs will be installed and ready for use. NOTE If the up2date utility was used to install the Enterprise Security Client, there is no need for further installation; the client has already been installed.
Installing and Uninstalling on Windows 1. Unplug all USB tokens. 2. Stop the Enterprise Security Client. 3. Log in as root, and use rpm -ev to remove the Enterprise Security Client RPMs in the following order: NOTE Update the version numbers of the RPM files to match your version. # # # # # # rpm rpm rpm rpm rpm rpm -ev -ev -ev -ev -ev -ev ccid pcsc-lite pcsc-lite-libs ifd-egate coolkey esc 4. Remove any remaining files in the installation directory. 4. Installing and Uninstalling on Windows 4.1.
Chapter 2. Installing the Enterprise Security Client Figure 2.1. Launching the Installation Wizard 3. The wizard displays the list of packages that will be installed.
Installing the Client Figure 2.2. Launching the Installation Wizard on Windows 4. The wizard prompts for the installation directory for the Enterprise Security Client. The default directory is C:\Program Files\Red Hat\ESC.
Chapter 2. Installing the Enterprise Security Client Figure 2.3. Specifying the Installation Directory 5. The wizard prompts for the Start Menu directory for the Enterprise Security Client. The default directory is Red Hat.
Installing the Client Figure 2.4. Specifying the Start Menu Directory 6. Proceed through the Enterprise Security Client installation wizard. Click Install to begin installing the Enterprise Security Client components. NOTE The installation process also installs the CoolKey PKCS #11 driver and e-gate drivers needed for Certificate System-supported keys and automatically installs the Certificate System PKCS #11 module in any Mozilla browsers it can locate.
Chapter 2. Installing the Enterprise Security Client Figure 2.5. Ready to Start the Installation 7. When the installation has completed, the Enterprise Security Client will prompt the user to insert a token, and can then be launched for immediate use.
Installing the Client Figure 2.6. Launching the Smart Card Manager 8. Click Finish to complete the installation.
Chapter 2. Installing the Enterprise Security Client Figure 2.7. Completing the Installation 4.2. Uninstalling the Client 1. Unplug all USB tokens. 2. Stop the Enterprise Security Client. 3. Open the Control Panel, and click the Add Remove Programs icon. 4. In the list of available programs, click Smart Card Manager, and click Change/Remove. 5. When the uninstallation is complete, remove any remaining files in the installation directory. 5.
Installing the Client The Mac Enterprise Security Client packages are available in the Downloads area of Red Hat Network. There are two channels for the packages; Mac clients are available in 32-bit. The Mac Smart Card Manager package is SmartCardManagerversion.dmg. To install the Enterprise Security Client on Mac OS X: 1. Download the SmartCardManager-1.0.1-X.OSX4.darwin.dmg file from the Red Hat Network channel. 2. Double-click the SmartCardManager-1.0.1-X.OSX4.darwin.
Chapter 2. Installing the Enterprise Security Client b. Read the Software License Agreement, and click Continue if you accept the terms. c. Select the installation destination. Figure 2.9. Specifying the installation destination d. Click Upgrade (or Install, if shown), to begin the installation.
Installing the Client Figure 2.10. Launch Installation e. Enter the administrator password, and click OK to start the installation. Figure 2.11.
Chapter 2. Installing the Enterprise Security Client f. When the installation is complete, click Close. Figure 2.12. Coolkey Software Package installation in progress When the process is complete, the e-gate token drivers, the PKCS11 module, and the TokenD software are all installed on the local system. 5.2. Uninstalling the Client 1. Unplug all USB tokens. 2. Stop the Enterprise Security Client. 3. Delete the ESC.app icon. NOTE There is no uninstallation program for the Mac.
Chapter 3. Using the Enterprise Security Client The following sections contain basic instructions on using the Enterprise Security Client for token enrollment, formating, and password reset operations. 1. Launching Enterprise Security Client Each of the supported operating systems requires a slightly different method of starting the Enterprise Security Client, as follows: Red Hat Enterprise Linux 4 Open a command shell and type esc.
Chapter 3. Using the Enterprise Security Client op.format.tokenKey.issuerinfo.enable=true op.format.tokenKey.issuerinfo.value=http://server.example.com 2.1. About Phone Home Profiles The Enterprise Security Client is based on Mozilla XULRunner. Consequently, each user has a profile similar to the user profiles used by Mozilla Firefox and Thunderbird. The Enterprise Security Client accesses the configuration preferences file.
Adding Phone Home Information to a Token /Applications/ESC.app/Contents/Resources/defaults/preferences. 3. Add the global Phone Home parameter line. For example: pref("esc.global.phone.home.url","http://tps.example.com:7888/cgi-bin/home.cgi"); When a smart card is inserted and Phone Home is launched, the Enterprise Security Client first checks the token for the Phone Home information. If no information is on the token, then the client checks the esc-prefs.js file for the esc.global.phone.home.
Chapter 3. Using the Enterprise Security Client • 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 should also supply detailed information on how the tokens should be configured when shipped. • If tokens are blank, the company IT department can supply the information when formating small groups of tokens.
Manually Example Corp http://tps.example.com:12443/nk_service ## TPS server URL http://tps.example.com:12443/cgi_bin/esc.cgi ## Optional Enrollment UI http://www.test.url.com ## Optional enrolled token url Example 3.1.
Chapter 3. Using the Enterprise Security Client controls the cryptographic keys belonging to the certificates. Certificate System CSP. The Certificate System CSP is designed to provide cryptographic functions on behalf of Windows using our supported smart cards. The Windows CSP performs its requested cryptographic functionality by calling the Certificate System PKCS #11 module.
Smart Card Auto Enrollment 1. Ensure that the Enterprise Security Client is running. 2. Insert an uninitialized smart card, pre-formatted with the Phone Home information for the TPS and the enrollment interface URL for the user's organization. The smart card can be added either by placing a USB form factor smart card into a free USB slot, or by inserting a standard, full-sized smart card into a smart card reader.
Chapter 3. Using the Enterprise Security Client Figure 3.2. Smart Card Enrollment Page The above illustration shows the default enrollment UI included with the TPS server. This UI is a standard HTML form, which you can customize to suit your own deployment requirements. This could include adding a company logo or adding and changing field text, etc. Refer to Section 5, “Customizing the Smart Card Enrollment User Interface” for information on how to customize the UI. 5.
Smart Card Auto Enrollment LDAP Password This is the password corresponding to the user ID entered; this can be a simple password or a customer number. NOTE The LDAP user ID and password refer to the fact that the TPS server is usually associated with a Directory Server, which stores user information and to which the TPS refers to authenticate users. Passwords must conform to the password policy configured in the directory server.
Chapter 3. Using the Enterprise Security Client Figure 3.3. Smart Card Enrollment Success Message 5. Customizing the Smart Card Enrollment User Interface Red Hat Certificate System (specifically the TPS subsystem) ships with a generic, external smart card enrollment user interface (UI). This UI consists of HTML and Javascript, and consequently can be customized to suit individual deployments. The default HTML file for the Enrollment UI is located at /var/lib/rhpki-tps/cgi-bin/home/Enroll.
Customizing the Smart Card Enrollment The following is an extract from the default UI HTML file, and it includes comments on how you might customize it to suit your requirements.
Enrollment
