Red Hat Certificate System 8.0 Managing Smart Cards with the

Red Hat Certificate System 8.0 Managing Smart Cards with the
Red Hat Certificate System 8.0
Managing Smart Cards with the
Enterprise Security Client
Managing personal certificates with the Enterprise Security Client for
Red Hat Certificate System 7.3
Edition 8.0.7
Landmann
Red Hat Certificate System 8.0 Managing Smart Cards with the
Enterprise Security Client
Managing personal certificates with the Enterprise Security Client for
Red Hat Certificate System 7.3
Edition 8.0.7
Landmann
[email protected] m
Legal Notice
Copyright © 2009 Red Hat, Inc..
T his document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported
License. If you distribute this document, or a modified version of it, you must provide attribution to Red
Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be
removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section
4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo,
and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux ® is the registered trademark of Linus T orvalds in the United States and other countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and other
countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or
endorsed by the official Joyent Node.js open source or commercial project.
T he OpenStack ® Word Mark and OpenStack Logo are either registered trademarks/service marks or
trademarks/service marks of the OpenStack Foundation, in the United States and other countries and
are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
T his 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.
Table of Contents
Table of Contents
.About
. . . . . . T. .his
. . . Guide
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . .
1. What Is in T his Guide
4
2. Additional Reading
4
3. Examples and Formatting
5
3.1. Formatting for Examples and Commands
5
3.2. T ool Locations
5
3.3. Guide Formatting
5
4. Giving Feedback
6
5. Document History
6
.Chapter
. . . . . . . . 1.
. . .Introduction
. . . . . . . . . . . . .to
. . .the
. . . .Enterprise
. . . . . . . . . . . Security
. . . . . . . . . Client
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. . . . . . . . . .
1.1. Red Hat Enterprise Linux, Single Sign-On, and Authentication
8
1.2. Red Hat Certificate System and the Enterprise Security Client
9
1.3. T he Enterprise Security Client and the Windows Cryptographic Service Provider
10
1.4. About the Mac T okenD Component
11
.Chapter
. . . . . . . . 2.
. . .Installing
. . . . . . . . . .the
. . . .Enterprise
. . . . . . . . . . . Security
. . . . . . . . . Client
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
............
2.1. Supported Platforms for the Client
12
2.2. Supported Smart Cards
12
2.3. Installing and Uninstalling the Enterprise Security Client on Red Hat Enterprise Linux
12
2.3.1. Installing the Client
12
2.3.2. Uninstalling on Red Hat Enterprise Linux
13
2.4. Installing and Uninstalling on Windows
14
2.4.1. Installing the Client
14
2.4.2. Uninstalling the Client
18
2.5. Installing and Uninstalling the Enterprise Security Client on Mac OS X
19
2.5.1. Installing the Client
19
2.5.2. Uninstalling the Client
21
.Chapter
. . . . . . . . 3.
. . .Using
. . . . . .the
. . . .Enterprise
. . . . . . . . . . . Security
. . . . . . . . . .Client
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
...........
3.1. T ray Icons for the Enterprise Security Client
23
3.2. Launching Enterprise Security Client
23
3.2.1. Opening the Enterprise Security Client on Red Hat Enterprise Linux
24
3.2.2. Opening the Enterprise Security Client on Microsoft Windows
24
3.2.3. Opening the Enterprise Security Client on Mac OS X
24
3.3. Configuring Phone Home
24
3.3.1. About Phone Home Profiles
25
3.3.2. Setting Global Phone Home Information
25
3.3.3. Adding Phone Home Information to a T oken Manually
26
3.3.4. Configuring the T PS to Use Phone Home
27
3.4. Setting up Users to Be Enrolled
28
3.5. Enrolling a Smart Card Automatically
28
3.6. Managing Smart Cards
31
3.6.1. Formatting the Smart Card
32
3.6.2. Resetting a Smart Card Password
32
3.6.3. Viewing Certificates
33
3.6.4. Importing CA Certificates
34
3.6.5. Adding Exceptions for Servers
36
3.6.6. Enrolling Smart Cards
38
3.6.7. Re-Enrolling T okens
39
3.7. Verifying T hat the Mac T okenD Is Working Properly
39
3.8. Diagnosing Problems
40
1
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
3.8.1. Errors
3.8.2. Events
42
43
.Chapter
........4
. ...Using
. . . . . . Security
. . . . . . . . . Officer
. . . . . . . .Mode
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. .4. . . . . . . . . .
4.1. Enabling Security Officer Mode
44
4.2. Enrolling a New Security Officer
46
4.3. Using Security Officers to Manage Users
48
4.3.1. Enrolling a New User
48
4.3.2. Performing Other Security Officer T asks
50
4.3.3. Formatting an Existing Security Officer Smart Card
51
.Chapter
. . . . . . . . 5.
. . .Using
. . . . . . Keys
. . . . . .on
. . .Smart
. . . . . . .Cards
. . . . . . for
. . . .Web
. . . . .and
. . . . Mail
. . . . .Clients
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
...........
5.1. Setting up Browsers to Support SSL for T okens
53
5.2. Using the Certificates on T okens for Mail Clients
54
5.3. Setting up Mail and Browser Clients on Mac OS X
55
.Chapter
. . . . . . . . 6.
. . .Configuring
. . . . . . . . . . . . the
. . . . Enterprise
. . . . . . . . . . . .Security
. . . . . . . . .Client
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
............
6.1. Overview of Enterprise Security Client Configuration
57
6.1.1. About the Preferences Configuration Files
57
6.1.2. About the XUL and JavaScript Files in the Enterprise Security Client
63
6.1.3. Enterprise Security Client File Locations
63
6.2. Configuring SSL Connections with the T PS
65
6.3. Using Shared Security Databases
66
6.4. Customizing the Smart Card Enrollment User Interface
66
6.5. Disabling LDAP Authentication for T oken Operations
71
2
Table of Contents
3
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
About This Guide
T he Enterprise Security Client is a simple user interface which formats and manages smart cards. T his
guide is intended for everyday users of Certificate System, who 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.
Before reading this guide, be familiar with the following concepts:
Public-key cryptography and the Secure Sockets Layer (SSL) protocol
Intranet, extranet, Internet security, and the role of digital certificates in a secure enterprise
LDAP and Red Hat Directory Server
1. What Is in This Guide
T his guide contains the following chapters:
Chapter 1, Introduction to the Enterprise Security Client provides an introduction to the Certificate
System.
Section 2.1, “Supported Platforms for the Client” provides information about supported platforms for
the Enterprise Security Client.
Chapter 2, Installing the Enterprise Security Client provides information on how to install and uninstall
the Enterprise Security Client on the supported platforms.
Chapter 3, Using the Enterprise Security Client provides instructions on using the Enterprise Security
Client for token enrollment, formatting, and password reset operations.
Chapter 5, Using Keys on Smart Cards for Web and Mail Clients describes how to use the Enterprise
Security Client keys for SSL and S/MIME authentication.
Chapter 6, Configuring the Enterprise Security Client provides information on configuring the
Enterprise Security Client.
2. Additional Reading
T his paper covers information on managing smart cards in Certificate System, as well as the
functionality for the Enterprise Security Client, which handles smart cards.
Some very basic information on using other end user web services for the Certificate System CA and RA
systems is covered in the Using End User Services. For basic certificate management, that's all many
users need to know. Managing Smart Cards with the Enterprise Security Client and the End User's
Guide, together, are both for end users of Red Hat Certificate System.
For more information on the basic concepts of certificates, public key infrastructure, and Certificate
System itself, see the Certificate System Deployment Guide.
More detailed information about the concepts behind public key cryptography, as well as a more detailed
overview of the Certificate System subsystems and how Certificate System manages certificates and
smart cards, is available in the Certificate System Administrator's Guide. T his is also the guide for
administrators to manage the Certificate System server. Installation is covered in the Certificate System
Installation Guide.
T he Certificate System Agent's Guide covers how agents can approve and reject certificate requests
and manage user certificates through other Certificate System subsystems, such as the Online
Certificate Status Responder (which checks the revocation status) and the Data Recovery Manager
4
About This Guide
(which recovers the certificate information if a token or a certificate is lost).
T he latest information about Red Hat Certificate System, including current release notes and other
updates, is always available at the Certificate System documentation page,
http://www.redhat.com/docs/manuals/cert-system/.
3. Examples and Formatting
3.1. Formatting for Examples and Commands
All of the examples for Red Hat Certificate System commands, file locations, and other usage are given
for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands and files
for your platform.
Example 1. Example Command
T o start the Red Hat Certificate System:
service pki-ca start
3.2. Tool Locations
All of the tools for Red Hat Certificate System are located in the /usr/bin directory. T hese tools can be
run from any location without specifying the tool location.
3.3. Guide Formatting
Certain words are represented in different fonts, styles, and weights. Different character formatting is
used to indicate the function or purpose of the phrase being highlighted.
Formatting Style
Purpose
Monospace font
Monospace is used for commands, package names, files and
directory paths, and any text displayed in a prompt.
Monospace
with a
background
T his type of formatting is used for anything entered or
returned in a command prompt.
Italicized text
Any text which is italicized is a variable, such as
instance_name or hostname. Occasionally, this is also used
to emphasize a new term or other phrase.
Bolded text
Most phrases which are in bold are application names, such
as Cygwin, or are fields or options in a user interface, such
as a User Nam e Here: field or Save button.
Other formatting styles draw attention to important text.
5
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
NOTE
A note provides additional information that can help illustrate the behavior of the system or
provide more detail for a specific issue.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a configuration change that
will not persist after a reboot.
WARNING
A warning indicates potential data loss, as may happen when tuning hardware for maximum
performance.
4. Giving Feedback
If there is any error in this Enterprise Security Client Guide or there is any way to improve the
documentation, please let us know. Bugs can be filed against the documentation for Red Hat Certificate
System through Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as specific as possible,
so we can be more effective in correcting any issues:
Select the Red Hat Certificate System product.
Set the component to Doc - enterprise-security-guide.
Set the version number to 8.0.
For errors, give the page number (for the PDF) or URL (for the HT ML), and give a succinct
description of the problem, such as incorrect procedure or typo.
For enhancements, put in what information needs to be added and why.
Give a clear title for the bug. For example, "Incorrect com m and exam ple for setup
script options" is better than "Bad exam ple".
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 [email protected]
5. Document History
Revision 8.0.7
June 1, 2010
Ella Deon Lackey
Adding back Mac support, on a new platform (10.5.8), per Errata RHBA-2010:0448.
Revision 8.0.6
January 23, 2010
Ella Deon Lackey
Correcting Windows Enterprise Security Client process for proper 64-bit Windows packages, per Errata
RHBA-2009:1687.
Revision 8.0.5
December 21, 2009
Ella Deon Lackey
Updating platform support to include 64-bit Windows platforms, per Errata RHBA-2009:1687.
6
About This Guide
Adding note on escaping characters in passwords for LDAP auth, per Bugzilla #523568.
Adding new configuration parameter and section on configuring shared terminals, per Errata RHBA2009:1687.
Adding note on new error message if connection to T PS format screen times out, per Errata RHBA2009:1665.
Revision 8.0.4
September 4 , 2009
Ella Deon Lackey
Rearranging introduction and adding information on single sign-on.
Fixing directory path to esc-prefs.js file, per Bugzilla #459511.
Revision 8.0.3
August 20, 2009
Ella Deon Lackey
Changing screenshot in Windows installation, per Bugzilla #518314.
Revision 8.0.2
August 13, 2009
Ella Deon Lackey
Correcting missed or updated edits for Bugzilla #459511 and #510569.
Revision 8.0.1
July 29, 2009
Ella Deon Lackey
T ech reviews for each chapter, per Bugzilla #510564, #510566, #510567, #510569, #510571, and
#510572.
Edits to the parameters listed for the esc-pref.js file, per Bugzilla #459511.
Revision 8.0.0
July 22, 2009
Ella Deon Lackey
Initial draft for Certificate System 8.0 Enterprise Security Client Guide.
7
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
Chapter 1. Introduction to the Enterprise Security Client
T he 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.
T he Enterprise Security Client is the third part of Certificate System's complete token management
system. T wo subsystems — the T oken Key Service (T KS) and T oken Processing System (T PS) — are
used to process token-related operations. T he Enterprise Security Client is the interface which allows
the smart card and user to access the token management system.
After a token is enrolled, applications such as Mozilla Firefox and T hunderbird can be configured to
recognize the token and use it for security operations, like client authentication and S/MIME mail. T he
Enterprise Security Client provides the following capabilities:
Supports Global Platform-compliant smart cards like Gemalto 64K V2 and Safenet 300J Java smart
cards.
Enrolls security tokens so they are recognized by T PS.
Maintains the security token, such as re-enrolling a token with T PS.
Provides information about the current status of the token or tokens being managed.
Supports server-side key generation through the T PS 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
Network users frequently have to submit multiple passwords for the various services they use, such as
email, web browsing and intranets, and servers on the network. Maintaining multiple passwords, and
constantly being prompted to enter them, is a hassle for users and administrators. Single sign-on is a
configuration which allows administrators to create a single password store so that users can log in
once, using a single password, and be authenticated to all network resources.
Red Hat Enterprise Linux 5.3 supports single sign-on for several resources, including logging into
workstations and unlocking screensavers, accessing encrypted web pages using Mozilla Firefox, and
sending encrypted email using Mozilla T hunderbird.
Single sign-on is both a convenience to users and another layer of security for the server and the
network. Single sign-on hinges on secure and effective authentication, and the Enterprise Security Client
ties into the public-key infrastructure implemented by Red Hat Certificate System.
One of the cornerstones of establishing a secure network environment is making sure that access is
restricted to people who have the right to access the network. If access is allowed, users can
authenticate to the system, meaning they can verify their identities. One method of verifying an identity is
presenting a certificate. A certificate is an electronic document which identifies the entity which presents
it.
T hese certificates can be stored on a smart card. When a user inserts a smart card, the smart card
presents the certificates to the system and identifies the user so the user can be authenticated. One of
the two authentication methods for Red Hat Enterprise Linux's single sign-on is smart card
authentication. (T he other is Kerberos-based authentication.)
Single sign-on on Red Hat Enterprise Linux using smart cards goes through three steps:
1. A user inserts a smart card into the card reader. T his is detected by the pluggable authentication
8
Chapter 1. Introduction to the Enterprise Security Client
modules (PAM) on Red Hat Enterprise Linux.
2. T he 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.
3. If the certificate is successfully validated against the key distribution center (KDC), then the user is
allowed to log in.
T he Enterprise Security Client manages the smart cards, which is part of administering single sign-on.
1.2. Red Hat Certificate System and the Enterprise Security Client
Red Hat Certificate System creates, manages, renews, and revokes certificates and keys. For managing
smart cards, the Certificate System has a token management system to generate keys, create certificate
requests, and receive certificates.
T wo subsystems — the T oken Key Service (T KS) and T oken Processing System (T PS) — are used to
process token-related operations. T he Enterprise Security Client is the interface which allows the smart
card and user to access the token management system.
Figure 1.1. How Certificate System Manages Smart Cards
A total of four Certificate System subsystems are involved with managing tokens, two for managing the
tokens (T KS and T PS) and two for managing the keys and certificates within the public-key
infrastructure (CA and DRM).
T he T oken Processing System (T PS) 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 T PS 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.
T he T oken Key Service (T KS) generates, or derives, symmetric keys used for communication
between the T PS and smart card. Each set of keys generated by the T KS is unique because they
are based on the card's unique ID. T he keys are formatted on the smart card and are used to
encrypt communications, or provide authentication, between the smart card and T PS.
T he 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.
9
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T he Enterprise Security Client is the conduit through which T PS communicates with each token over a
secure HT T P channel (HT T PS), and, through the T PS, with the Certificate System.
T o use the tokens, the T oken Processing System must be able to recognize and communicate with
them. T he tokens must first be enrolled to populate the tokens with required keys and certificates and
add the tokens to the Certificate System. T he Enterprise Security Client provides the user interface for
end entities to enroll tokens.
1.3. The Enterprise Security Client and the Windows
Cryptographic Service Provider
T he Microsoft Windows version of the Enterprise Security Client installs a Windows Cryptographic
Service Provider (CSP) that is compatible with the Certificate System-supported smart cards.
Microsoft Windows supports a software library designed to implement the Microsoft Cryptographic
Application Programming Interface (CAPI or CryptoAPI). CAPI allows Windows-based applications, such
as the Microsoft Outlook or Internet Explorer, to be developed to perform secure, cryptographic
operations. T his API provides a layer between these crypto-enabled applications and the details of the
cryptographic services provided by the API.
T he CAPI interface can be used to create custom CSP libraries. Custom CSP libraries in Certificate
System support using smart cards on Windows (enrolled through the Enterprise Security Client) to
perform the cryptographic functions requested by Windows applications which access the CAPI
interface.
T he CAPI store is a repository controlled by Windows, and which houses a collection of digital
certificates associated with a given CSP. CAPI oversees the certificates, while each CSP controls the
cryptographic keys belonging to the certificates.
T he Certificate System CSP is designed to provide cryptographic functions on behalf of Windows using
our supported smart cards. T he Windows CSP performs its requested cryptographic functionality by
calling the CoolKey PKCS #11 module.
T he Certificate System CSP, which has been signed by Microsoft, enables users to be able to perform
common tasks securely:
Send and receive encrypted and signed emails with Microsoft Outlook.
Visit SSL-protected websites with Microsoft Internet Explorer.
Access certain VPN clients using the smart card, which provides secure access to protected
networks.
Log into a Windows server or domain using the smart card, as long as the infrastructure required for
smart card login has been properly set up.
T he required CSP libraries are automatically installed with the Enterprise Security Client. T here are
several common situations when a Windows user interacts directly with the CSP.
When a smart card is enrolled with the Enterprise Security Client, the newly created certificates are
automatically inserted into the user's CAPI store.
When a smart card is formatted, the certificates associated with that card are removed from the CAPI
store.
When a user inserts a properly enrolled card, the certificates on that card are automatically written to
the CAPI store. T he certificates are then removed when the card is removed from the computer.
When using applications such as Microsoft Outlook or Microsoft Internet Explorer, the user may be
10
Chapter 1. Introduction to the Enterprise Security Client
prompted to enter the smart card's password. T his is required when the smart card is asked to
perform protected cryptographic operations such as creating digital signatures.
1.4. About the Mac TokenD Component
T he Mac Enterprise Security Client ships with a smart card-specific T okenD component which bridges
the gap between Certificate System-supported tokens and the Mac CDSA security layer, allowing current
OS X applications like Apple Mail and Safari to take advantage of the capabilities of Certificate System
tokens:
T he Mac Keychain Access utility can be used to view the certificates and keys on Certificate System
tokens.
T he Apple Mail client can be used to send and view signed and encrypted emails using Certificate
System tokens.
T he Apple Safari browser can use Certificate System tokens to log onto secure SSL web sites.
11
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
Chapter 2. Installing the Enterprise Security Client
T he 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. T hese are listed in the installation
chapter of the Certificate System Administrator's Guide.
2.1. Supported Platforms for the Client
T he Enterprise Security Client interface is supported on the following platforms:
Red Hat Enterprise Linux 5.3 (x86)
Red Hat Enterprise Linux 5.3 (x86_64)
Microsoft Windows Vista 32-bit
Microsoft Windows Vista 64-bit
Microsoft Windows XP 32-bit
Microsoft Windows XP 64-bit
Apple Mac OS X 10.5.8 and higher (Leopard)
2.2. Supported Smart Cards
Enterprise Security Client supports smart cards which are JavaCard 2.1 or higher and Global Platform
2.01-compliant. Certificate System was tested using the following cards:
Safenet 330J Java smart cards
Gemalto 64K V2 tokens, both as a smart card and GemPCKey USB form factor key
Smart card testing was conducted using the SCM SCR331 CCID reader.
T he only card manager applet supported with Certificate System is the CoolKey applet, one of the
packages included and installed with Red Hat Certificate System 8.0.
2.3. Installing and Uninstalling the Enterprise Security Client on
Red Hat Enterprise Linux
2.3.1. Installing the Client
T he first step in installing the Enterprise Security Client is to download the required packages. T he
Certificate System Administrator's Guide explains how to retrieve these RPMs and other files through the
Red Hat Certificate System 8.0 (AS v.4 for x86) or Red Hat Certificate System
8.0 (ES v.4 for x86) Red Hat Network channels. T here are two ways to obtain the packages:
Downloading an ISO image or packages through the Red Hat Network channel
Using the Red Hat yum utility
T he preferred method of obtaining RPMs is using the yum command-line utility, as follows:
# yum install esc
If the yum command completes successfully, all of the necessary Enterprise Security Client RPMs will be
installed and ready for use.
12
Chapter 2. Installing the Enterprise Security Client
NOTE
If the yum utility was used to install the Enterprise Security Client, there is no need for further
installation; the client has already been installed. T he following procedure is for installing from a
CD image.
1. As root, install the Enterprise Security Client packages. On Red Hat Enterprise Linux 5 (32-bit),
these packages are already installed, and can be updated using yum . For example:
yum install esc coolkey
Setting up Install Process
Parsing package install arguments
Resolving Dependencies
--> Running transaction check
---> Package esc.x86_64 0:1.1.0-9.el5 set to be updated
---> Package coolkey.x86_64 0:1.1.0-9.el5 set to be updated
--> Finished Dependency Resolution
Dependencies Resolved
==========================================================================
===
Package
Arch
Version
Repository
Size
==========================================================================
===
Installing:
esc
x86_64
1.1.0-9.el5
base
522 k
Installing for dependencies:
coolkey
x86_64
1.1.0-9.el5
base
90
k
Transaction Summary
==========================================================================
===
Install
2 Package(s)
Update
0 Package(s)
Remove
0 Package(s)
Total download size: 612 k
Is this ok [y/N]: y
T he Enterprise Security Client is located in /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. T he esc shell
script is installed in /usr/bin/esc. T he Enterprise Security Client can be launched by typing esc at a
command prompt.
T he Enterprise Security Client for Linux implements a daemon (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. T he client can also be launched manually by selecting System Settings, then Sm art Card
Manager, from the System menu.
2.3.2. Uninstalling on Red Hat Enterprise Linux
1. Unplug all USB tokens.
13
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
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 -ev coolkey
# rpm -ev esc
4. Remove any remaining files in the installation directory.
2.4. Installing and Uninstalling on Windows
2.4.1. Installing the Client
T he Windows Enterprise Security Client packages are available in the Downloads area of Red Hat
Network.
For both 32-bit and 64-bit Windows systems, the Windows Enterprise Security Client package is
available in the 32-bit channel. T his package is Sm artCardManagerSetup-1.0.1X.win32.i386.exe.
For 64-bit systems, there is an additional package which must be installed, CoolKeySetupversion.win64 .x64 .exe, to use the Enterprise Security Client to manage certificates for email and
browser clients.
T o install the Enterprise Security Client on Windows:
NOTE
You may need administrator privileges to install the Enterprise Security Client on the Windows
system.
1. In the Red Hat Network page for Certificate System, select the 32-bit or 64-bit channel.
2. Click the Downloads tab in the channel.
3. Download the Enterprise Security Client installer and (for 64-bit systems) CoolKey libraries.
14
Chapter 2. Installing the Enterprise Security Client
4. Next, double-click the Sm artCardManagerSetup-1.0.1-X.win32.i386.exe file to launch
the Enterprise Security Client installation program.
5. Click Next to being going through the installer, and then accept the license agreement.
6. T he wizard displays the list of packages that will be installed.
15
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
7. T he wizard prompts for the installation directory for the Enterprise Security Client. T he default
directory is C:\Program Files\Red Hat\ESC.
8. T he wizard prompts for the Start Menu directory for the Enterprise Security Client. T he default
directory is Red Hat.
16
Chapter 2. Installing the Enterprise Security Client
9. Proceed through the Enterprise Security Client installation wizard. Click Install to begin
installing the Enterprise Security Client components.
NOTE
T he installation process also installs the CoolKey PKCS #11 driver needed for Certificate
System-supported keys and automatically installs the Certificate System PKCS #11 module
in any Mozilla browsers it can locate. T he installer places the Certificate System
Cryptographic Service Provider (CSP) on the user's system to allow users to use their
smart cards with Microsoft products such as Outlook and Internet Explorer.
10. 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.
17
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
11. Click Finish to complete the installation. T he machine has to be restarted after installing the
Enterprise Security Client, so, if possible, select the Yes radio button to restart the machine
immediately.
12. For 64-bit systems only. Last, double-click the CoolKeySetup-version.win64 .x64 .exe file
to install the required 64-bit CoolKey libraries.
2.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 Rem ove Program s icon.
4. In the list of available programs, click Sm art Card Manager, and click Change/Rem ove.
5. When the uninstallation is complete, remove any remaining files in the installation directory.
18
Chapter 2. Installing the Enterprise Security Client
2.5. Installing and Uninstalling the Enterprise Security Client on
Mac OS X
2.5.1. Installing the Client
T he Mac Enterprise Security Client packages are available in the Downloads area of Red Hat Network.
T here are two channels for the packages; Mac clients are available in 32-bit. T he Mac Smart Card
Manager package is Sm artCardManagerversion.dm g.
T o install the Enterprise Security Client on Mac OS X:
1. Download the Sm artCardManager-1.0.1-X.OSX4 .darwin.dm g file from the Red Hat
Network channel.
2. Double-click the Sm artCardManager-1.0.1-X.OSX4 .darwin.dm g file to display the
Enterprise Security Client Volume.
Inside the Volume are two directories, ESC.app and Coolkey1.14 .pkg. ESC.app is the
Enterprise Security Client application, and Coolkey1.14 .pkg is the installer for the token
support software, including the T okenD system.
3. Drag the ESC.app file to an accessible location (for example, the desktop), to install the
Enterprise Security Client.
4. Install the CoolKey package, as follows:
a. Double-click the Coolkey1.14 .pkg file to launch the CoolKey installer, and follow the
directions to complete the installation.
Figure 2.1. Mac Installation Program
b. Read the Software License Agreement, and click Continue if you accept the terms.
c. Select the installation destination.
19
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
Figure 2.2. Specifying the installation destination
d. Click Upgrade (or Install, if shown), to begin the installation.
Figure 2.3. Launch Installation
e. Enter the administrator password, and click OK to start the installation.
20
Chapter 2. Installing the Enterprise Security Client
Figure 2.4 . Entering the Administrator Password
f. When the installation is complete, click Close.
Figure 2.5. Coolkey Software Package installation in progress
When the process is complete, the e-gate token drivers, the PKCS11 module, and the T okenD software
are all installed on the local system.
2.5.2. Uninstalling the Client
1. Unplug all USB tokens.
2. Stop the Enterprise Security Client.
3. Delete the ESC.app icon.
21
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
NOTE
T here is no uninstallation program for the Mac. T he ESC.app directory can be manually
removed to remove the Enterprise Security Client.
22
Chapter 3. Using the Enterprise Security Client
Chapter 3. Using the Enterprise Security Client
T he following sections contain basic instructions on using the Enterprise Security Client for token
enrollment, formatting, and password reset operations.
3.1. Tray Icons for the Enterprise Security Client
Many programs maintain an icon in the tray or notification area which can be used to control the
operation of the program, usually through context menus when the icon is right-clicked. T he Enterprise
Security Client provides tray icons, including tool tips for errors and actions such as inserting or
removing a smart card.
Figure 3.1. Example T oken T ray Icon and T ool T ip
In its default configuration, the Enterprise Security Client launches and automatically minimizes to the
tray. On Red Hat Enterprise Linux, the tray icon appears only if the notification area in Gnome has been
enabled.
T his tray functionality behaves differently on the different operating systems:
Windows. When right-clicked, the tray icon shows a simple menu with options to Manage Sm art
Card, which opens the Enterprise Security Client interface, and to Exit Sm art Card Manager,
which stops the Enterprise Security Client process. Clicking the X in the top right corner minimizes
Enterprise Security Client to the tray. Double-clicking the tray icon brings Enterprise Security Client to
the front. T here are also notification messages, shown as standard balloon tool tips, on events like
inserting or removing a card.
Linux. T he tray icon appears only if the notification area in Gnome has been enabled. T he tray icon
options are identical to the Windows options. Clicking the X in the top left corner closes the current
window and minimizes Enterprise Security Client to the tray.
Mac. On Mac, the tray is called the dock. Since Enterprise Security Client is based on Mozilla, rightclicking on the Enterprise Security Client dock icon reveals all the standard Mozilla Firefox menu
options, including options to hide, show, and quit the client. T he Enterprise Security Client also has a
menu item called Manage Sm art Cards in the dock menu, which opens the card management UI.
T he top level application menu has a menu under Go, Manage Sm art Card, which also opens the
card management window.
3.2. Launching Enterprise Security Client
T here are two concepts for launching the Enterprise Security Client. T he Enterprise Security Client
process must be started and it runs silently, waiting to detect any inserted smart card or token. T he user
interface for the Enterprise Security Client opens automatically when smart cards are inserted or can be
opened manually.
23
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
3.2.1. Opening the Enterprise Security Client on Red Hat Enterprise Linux
Initiate the Enterprise Security Client daemon (escd) from the command line:
esc
T his daemon listens silently for smart cards and opens the GUI as soon as a smart card is inserted.
T o open the Enterprise Security Client GUI manually, click Applications, System Settings, and then
Smart Card Manager.
3.2.2. Opening the Enterprise Security Client on Microsoft Windows
Double-click the Enterprise Security Client icon on the desktop, or from the Start menu. T he Enterprise
Security Client is also configured to start on reboot.
3.2.3. Opening the Enterprise Security Client on Mac OS X
Double-click the Enterprise Security Client icon wherever the application was installed.
3.3. Configuring Phone Home
T he Phone Home feature in the Enterprise Security Client associates information within each smart card
with information that points to distinct T PS servers and Enterprise Security Client UI pages. Whenever
the Enterprise Security Client accesses a new smart card, it can connect to the T PS instance and
retrieve the Phone Home information.
Phone Home retrieves and then caches this information; because the information is cached locally, the
T PS subsystem does not have to be contacted each time a formatted smart card is inserted.
T he information can be different for every key or token, which means that different T PS servers and
enrollment URLs can be configured for different corporate or customer groups. Phone Home makes it
possible to configure different T PS servers for different issuers or company units, without having to
configure the Enterprise Security Client manually to locate the correct server and URL.
24
Chapter 3. Using the Enterprise Security Client
NOTE
In order for the T PS subsystem to utilize the Phone Home feature, Phone Home must be enabled
in the T PS configuration file, as follows:
op.format.userKey.issuerinfo.enable=true
op.format.userKey.issuerinfo.value=http://server.example.com
3.3.1. About Phone Home Profiles
T he Enterprise Security Client is based on Mozilla XULRunner. Consequently, each user has a profile
similar to the user profiles used by Mozilla Firefox and T hunderbird. T he Enterprise Security Client
accesses the configuration preferences file. When the Enterprise Security Client caches information for
each token, the information is stored in the user's configuration file. T he next time the Enterprise
Security Client is launched, it retrieves the information from the configuration file instead of contacting the
server again.
3.3.2. Setting Global Phone Home Information
Phone Home is triggered automatically when a security token is inserted into a machine. T he system
immediately attempts to read the Phone Home URL from the token and to contact the T PS server. For
new tokens or for previously formatted tokens, the Phone Home information may not be available to the
card.
T he Enterprise Security Client configuration file, esc-prefs.js, has a parameter which allows a global
Phone Home URL default to be set. T his parameter is esc.global.phone.home.url and is not in the
file by default.
T o define the global Phone Home URL:
1. 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.
On Windows, the profile directory is C:/Docum ents and
Settings/user_name/Application Data/RedHat/ESC.
On Mac, the profile directory is ~/Library/Application Support/ESC.
2. Open the esc-prefs.js file.
On Red Hat Enterprise Linux 5 (32-bit), the profile directory is /usr/lib/esc1.1.0/defaults/preferences. On 64-bit systems, this is /usr/lib64 /esc1.1.0/defaults/preferences.
On Windows, the profile directory is C:/Program Files/Red
Hat/ESC/defaults/preferences.
On Mac, the profile directory is
/Applications/ESC.app/Contents/Resources/defaults/preferences.
3. Add the global Phone Home parameter line to the esc-prefs.js file. For example:
pref("esc.global.phone.home.url","http://server.example.com:7888/cgibin/home/index.cgi");
T he URL can reference a machine name, a fully-qualified domain name, or an IPv4 or IPv6
25
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
address, depending on the DNS and network configuration.
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.url parameter.
If no Phone Home information is stored on the token and there is no global Phone Home parameter, the
user is prompted for the Phone Home URL when a smart card is inserted, as shown in Figure 3.2,
“Prompt for Phone Home Information”. T he other information is supplied and stored when the token is
formatted. In this case, the company supplies the specific Phone Home URL for the user. After the user
submits the URL, the format process adds the rest of the information to the Phone Home profile. T he
format process is not any different for the user.
Figure 3.2. Prompt for Phone Home Information
3.3.3. Adding Phone Home Information to a Token Manually
T he Phone Home information can be manually put on a token in one of two ways:
T he 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 formatting small
groups of tokens.
T he following information is used by the Phone Home feature for each smart card in the
~/.redhat/esc/alphanumeric_string.default/prefs.js file:
T he T PS server and port. For example:
"esc.key.token_ID.tps.url" = "http://server.example.com:7888/nk_service"
T he T PS enrollment interface URL. For example:
"esc.key.token_ID.tps.enrollment-ui.url" =
"http://server.example.com:7888/cgi_bin/esc.cgi?"
26
Chapter 3. Using the Enterprise Security Client
T he issuing company name or ID. For example:
"esc.key.token_ID.issuer.name" = "Example Corp"
T he Phone Home URL. For example:
"esc.key.token_ID.phone.home.url" = "http://server.example.com:7888/cgibin/home/index.cgi?"
Optionally, a default browser URL to access when an enrolled smart card is inserted.
"esc.key.token_ID.EnrolledTokenBrowserURL" = "http://www.test.example.com"
More of the parameters used by the prefs.js file are listed in T able 6.2, “prefs.js Parameters”.
NOTE
T he URLs for these parameters 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.4. Configuring the TPS to Use Phone Home
T he Phone Home feature and the different type of information used by it only work when the T PS has
been properly configured to use Phone Home. If the T PS is not configured for Phone Home, then this
feature is ignored. Phone Home is configured in the index.cgi in the /var/lib/pki-tps/cgibin/hom e directory; this prints the Phone Home information to XML.
Example 3.1, “T PS Phone Home Configuration File” shows an example XML file used by the T PS
subsystem to configure the Phone Home feature.
Example 3.1. T PS 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>
T he T PS configuration URI is the URL of the T PS server which returns the rest of the Phone Home
information to the Enterprise Security Client. An example of this URL is
http://server.exam ple.com :7888/cgi-bin/hom e/index.cgi; the URL can reference the
machine name, fully-qualified domain name, or an IPv4 or IPv6 address, as appropriate. When the T PS
configuration URI is accessed, the T PS server is prompted to return all of the Phone Home information
to the Enterprise Security Client.
27
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T o test the URL of the Smart Card server, enter the address in the T PS Config URI field, and click
T est URL.
If the server is successfully contacted, a message box indicates success. If the test connection fails, an
error dialog appears.
3.4. Setting up Users to Be Enrolled
When the T oken Processing System is installed, one of its configuration settings is the LDAP directory
which contains the users who are allowed to enroll a token. Only users who are stored within this
authentication directory are allowed to enroll, format, or have a token. Before attempting to enroll a token
or smart card, make sure that the person requesting the operation has an entry in the LDAP directory.
T he T PS is configured to look at a specific base DN in the LDAP directory. T his is configured in the
T PS's CS.cfg:
auth.instance.0.baseDN=dc=example,dc=com
auth.instance.0.hostport=server.example.com:389
For a user to be allowed to enroll a token, the user must be somewhere below the base DN.
If the user does not already have an entry, then the administrator must add the user to the specified
LDAP directory in the specified base DN before any tokens can be enrolled for the user.
/usr/bin/ldapmodify -a -D "cn=Directory Manager" -w secret -p 389 -h
server.example.com
dn: uid=jsmith,ou=People, dc=example,dc=com
objectclass: person
objectclass: inetorgperson
objectclass: top
uid: jsmith
cn: John Smith
email: [email protected]
userPassword: secret
3.5. Enrolling a Smart Card Automatically
Because the Enterprise Security Client is configured using the Phone Home feature, enrolling a smart
card is extremely easy. Because the information needed to contact the backend T PS server is provided
with each smart card, the user is guided quickly and easily through the procedure.
T o enroll an uninitialized smart card:
NOTE
T his procedure assumes that the smart card is uninitialized and the appropriate Phone Home
information has been configured.
1. Ensure that the Enterprise Security Client is running.
2. Insert an uninitialized smart card, pre-formatted with the Phone Home information for the T PS and
the enrollment interface URL for the user's organization.
28
Chapter 3. Using the Enterprise Security Client
T he 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.
When the system recognizes the smart card, it displays a message indicating it has detected an
uninitialized smart card.
3. Click Enroll My Sm art Card Now to display the smart card enrollment form.
NOTE
If you remove the card at this point, a message displays stating that the smart card can no
longer be detected. Reinsert the card to continue with the enrollment process.
T he enrollment files are accessed remotely; they reside on the T PS instance. If the network
connection is bad or broken, then, an error may come up saying Check the Network Connection
and Try Again. It is also possible that the enrollment window appears to open but the enrollment
process doesn't proceed. T he enrollment pages can be cached if the Enterprise Security Client
previously connect to them successfully, so the enrollment UI opens even if the network is offline.
T ry restarting Enterprise Security Client and check the network connection.
4. Because the Smart Card Manager now knows where the enrollment UI is located (it is included in
the Phone Home information), the enrollment form is displayed for the user to enter the required
information.
29
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T his illustration shows the default enrollment UI included with the T PS server. T his UI is a
standard HT ML form, which you can customize to suit your own deployment requirements. T his
could include adding a company logo or adding and changing field text.
See Section 6.4, “Customizing the Smart Card Enrollment User Interface” for information on
customizing the UI.
5. T he sample enrollment UI requires the following information for the T PS server to process the
smart card enrollment operation:
LDAP User ID. T his is the LDAP user ID of the user enrolling the smart card; this can also be a
screen name or employee or customer ID number.
LDAP Password. T his is the password corresponding to the user ID entered; this can be a
simple password or a customer number.
NOTE
T he LDAP user ID and password are related to the Directory Server user. T he T PS
server is usually associated with a Directory Server, which stores user information and
through which the T PS authenticates users.
Passwords must conform to the password policy configured in the Directory Server.
30
Chapter 3. Using the Enterprise Security Client
NOTE
If the password is stored using the SSHA hash, then any exclamation point (!) and dollar
sign ($) characters in the password must be properly escaped for a user to bind
successfully to the Enterprise Security Client on Windows XP and Vista systems.
For the dollar sign ($) character, escape the dollar sign when the password is
created:
\$
T hen, enter only the dollar sign ($) character when logging into the Enterprise
Security Client.
For the exclamation point (!) character, escape the character when the password is
created and when the password is entered to log into the Enterprise Security Client.
\!
Password and Re-Enter Password. T hese fields set and confirm the smart card's password,
used to protect the card information.
6. After you have entered all required information, click Enroll My Sm art Card to submit the
information and enroll the card.
7. When the enrollment process is complete, a message page opens which shows that the card was
successfully enrolled and can offer custom instructions on using the newly-enrolled smart card.
3.6. Managing Smart Cards
You can use the Manage Sm art Cards page to perform many of the operations that can be applied to
one of the cryptographic keys stored on the token.
You can use this page to format the token, set and reset the card's password, and to display card
information. T wo other operations, enrolling tokens and viewing the diagnostic logs, are also accessed
through the Manage Sm art Cards page. T hese operations are addressed in other sections.
31
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
Figure 3.3. Manage Smart Cards Page
3.6.1. Formatting the Smart Card
When you format a smart card, it is reset to the uninitialized state. T his removes all previously generated
user key pairs and erases the password set on the smart card during enrollment.
T he T PS server can be configured to load newer versions of the applet and symmetric keys onto the
card. T he T PS supports the CoolKey applet which is shipped with Red Hat Enterprise Linux 5.3.
NOTE
An e-gate token cannot be formatted on a Windows machine using the Enterprise Security Client.
T o format an e-gate card, perform the operation on Red Hat Enterprise Linux or Mac.
T o format a smart card:
1. Insert a supported smart card into the computer. Ensure that the card is listed in the Active
Sm art Cards table.
2. In the Sm art Card Functions section of the Manage Sm art Cards screen, click Form at.
3. If the T PS has been configured for user authentication, enter the user credentials in the
authentication dialog, and click Subm it.
4. 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 OK to
close the message box.
5. When the formatting process is complete, the Active Sm art Cards table shows the card
status as UNINIT IALIZ ED.
3.6.2. Resetting a Smart Card Password
If a user forgets the password for a smart card after the card is enrolled, it is possible to reset the
password. T o reset the password on a smart card:
32
Chapter 3. Using the Enterprise Security Client
1. Insert a supported smart card into the computer. Ensure that the card is listed in the Active
Sm art Cards table.
2. In the Sm art Card Functions section of the Manage Smart Cards screen, click Reset
Password to display the Password dialog.
3. Enter a new smart card password in the Enter new password field.
4. Confirm the new smart card password in the Re-Enter password field, and then click OK.
5. If the T PS has been configured for user authentication, enter the user credentials in the
authentication dialog, and click Subm it.
6. Wait for the password to finish being reset.
3.6.3. Viewing Certificates
T he Sm art Card Manager can display basic information about a selected smart card, including
stored keys and certificates. T o view certificate information:
1. Insert a supported smart card into the computer. Ensure that the card is listed in the Active
Sm art Cards table.
2. Select the card from the list, and click View Certificates.
T his displays basic information about the certificates stored on the card, including the serial
33
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T his displays basic information about the certificates stored on the card, including the serial
number, certificate nickname, and validity dates.
3. T o view more detailed information about a certificate, select the certificate from the list and click
View.
3.6.4. Importing CA Certificates
T he Xulrunner Gecko engine implements stringent controls over which SSL-based URLs can be visited
by client like a browser or the Enterprise Security Client. If the Enterprise Security Client (through the
Xulrunner framework) does not trust a URL, the URL can not be visited.
One way to trust an SSL-based URL is to import and trust the CA certificate chain of the CA which
issued the certificates for the site. (T he other is to create a trust security exception for the site, as in
Section 3.6.5, “Adding Exceptions for Servers”.)
Any CA which issues certificates for smart cards must be trusted by the Enterprise Security Client
application, which means that its CA certificate must be imported into the Enterprise Security Client.
1. Open the CA's end user pages in a web browser.
https://server.example.com:9444/ca/ee/ca/
2. Click the Retrieval tab at the top.
3. In the left menu, click the Im port CA Certificate Chain link.
4. Choose the radio button to download the chain as a file, and remember the location and name of
the downloaded file.
5. Open the Enterprise Security Client.
34
Chapter 3. Using the Enterprise Security Client
6. Click the View Certificates button.
7. Click the Authorities tab.
8. Click Im port.
35
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
9. Browse to the CA certificate chain file, and select it.
10. When prompted, confirm that you want to trust the CA.
3.6.5. Adding Exceptions for Servers
T he Xulrunner Gecko engine implements stringent controls over which SSL-based URLs can be visited
by client like a browser or the Enterprise Security Client. If the Enterprise Security Client (through the
Xulrunner framework) does not trust a URL, the URL can not be visited.
One way to trust an SSL-based URL is to create a trust security exception for the site, which imports the
certificate for the site and forces the Enterprise Security Client to recognize it. (T he other option is to
import the CA certificate chain for the site and automatically trust it, as in Section 3.6.4, “Importing CA
Certificates”.)
T he smart card may be used to access services or websites over SSL that require special security
exceptions; these exceptions can be configured through the Enterprise Security Client, similar to
configuring exceptions for websites in a browser like Mozilla Firefox.
1. Open the Enterprise Security Client.
36
Chapter 3. Using the Enterprise Security Client
2. Click the View Certificates button.
3. Click the Servers tab.
4. Click Add Exception.
5. Enter the URL, including any port numbers, for the site or service which the smart card will be
used to access. T hen click the Get Certificates button to download the server certificate for
the site.
37
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
6. Click Confirm Security Exception to add the site to the list of allowed sites.
3.6.6. Enrolling Smart Cards
Most smart cards will be automatically enrolled using the automated enrollment procedure, described in
Section 3.5, “Enrolling a Smart Card Automatically”. You can also use the Manage Sm art Cards
facility to manually enroll a smart card.
If you enroll a token with the user key pairs, then the token can be used for certificate-based operations
such as SSL client authentication and S/MIME.
NOTE
T he T PS server can be configured to generate the user key pairs on the server and then
archived in the DRM subsystem for recovery if the token is lost.
T o enroll a smart card manually:
1. Insert a supported, unenrolled smart card into the computer. Ensure that the card is listed in the
Active Sm art Cards table.
2. Click Enroll to display the Password dialog.
3. Enter a new key password in the Enter a password field.
Confirm the new password in the Re-Enter a password field.
4. Click OK to begin the enrollment.
5. If the T PS has been configured for user authentication, enter the user credentials in the
authentication dialog, and click Subm it.
If the T PS has been configured to archive keys to the DRM, the enrollment process will begin
generating and archiving keys.
38
Chapter 3. Using the Enterprise Security Client
When the enrollment is complete, the status of the smart card is displayed as ENROLLED.
3.6.7. Re-Enrolling Tokens
Commonly, a smart card will need to be re-enrolled while the certificates on it are still active. T he smart
card may be reused for a new user, or the certificates may be nearing their expiration date so the
original user is having the smart card re-enrolled during the grace period.
T he enrollment process does not automatically revoke active certificates, so enrolling a token without
removing its active certificates will leave the old certificates active.
Before re-enrolling a token, the agent or officer must either manually revoke the certificates on the token
or format the card again to return it to an unintialized state. Formatting a token automatically removes
and revokes its old certificates.
Formatting a token is described in Section 3.6.1, “Formatting the Smart Card”.
3.7. Verifying That the Mac TokenD Is Working Properly
T he T okenD software installed on a Macintosh computer provides a link between the Certificate System
CoolKeys and the Mac CDSA security API, which provides a wide variety of security functionality.
For example, the Apple Mail application can use a KeyChain to perform security-related tasks. A
KeyChain can store entities such as certificates, passwords, and private and public keys. Although most
KeyChains are stored in software, the CDSA API allows KeyChains to be stored on smart cards or keys.
CoolKey T okenD allows a Certificate System key to be displayed as a KeyChain.
T o verify that the T okenD software is working correctly:
1. Ensure that the Enterprise Security Client has been installed on the Mac computer.
2. Use the Enterprise Security Client to enroll a token, enabling it with the correct certificates and key
information.
3. Insert the enrolled token into a USB slot.
4. If T okenD is working, the token blinks for a few seconds while the information is obtained from the
token. T his is because the Mac CDSA layer is making a request for data.
5. Open the Mac Keychain Access utility in Applications/Utilities/
39
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
6. Find the new $Keychain entry in the list of valid chains. T he chain has the key's UID in its name.
7. Click the CoolKey KeyChain to view the certificates and keys on the token.
3.8. Diagnosing Problems
T he Enterprise Security Client includes basic diagnostic tools and a simple interface to log errors and
common events, such as inserting and removing a smart card or changing the card's password. T he
diagnostic tools can identify and notify users about problems with the Enterprise Security Client, smart
cards, and T PS connections.
T o open the Diagnostics Inform ation window:
1. Open the Enterprise Security Client.
2. Select the smart card to check from the list.
3. Click the Diagnostics button.
4. T his opens the Diagnostic Inform ation window for the selected smart card.
40
Chapter 3. Using the Enterprise Security Client
T he Diagnostics Inform ation screen displays the following information:
T he Enterprise Security Client version number.
T he version information for the Xulrunner framework upon which the client is running.
T he number of cards detected by the Enterprise Security Client.
For each card detected, the following information is displayed:
T he version of the applet running on the smart card.
T he alpha-numeric ID of the smart card.
T he card's status, which can be any of the three things:
NO_APPLET No key was detected.
UNINITIALIZED. T he key was detected, but no certificates have been enrolled.
ENROLLED. T he detected card has been enrolled with certificate and card information.
T he card's Phone Home URL. T his is the URL from which all Phone Home information is obtained.
T he card issuer name, such as Exam ple Corp.
T he card's answer-to-reset (AT R) string. T his is a unique value that can be used to identify different
classes of smart cards. For example:
3BEC00FF8131FE45A0000000563333304A330600A1
T he T PS Phone Home URL.
T he T PS server URL. T his is retrieved through Phone Home.
41
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T he T PS enrollment form URL. T his 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.
T he Enterprise Security Client records two types of diagnostic information. It records errors that are
returned by the smart card, and it records events that have occurred through the Enterprise Security
Client. It also returns basic information about the smart card configuration.
3.8.1. Errors
T he 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.
T he Enterprise Security Client loses the connection to the smart card. T his can happen when
problems occur communicating with the PCSC daemon.
T he connection between the Enterprise Security Client and T PS is lost.
Smart cards can report certain error codes to the T PS; these are recorded in the T PS's tpsdebug.log or tps-error.log files, depending on the cause for the message.
42
Chapter 3. Using the Enterprise Security Client
T able 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.8.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 T PS to the Enterprise Security Client.
T he NSS crypto library is initialized.
Other low-level smart card events are detected.
43
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
Chapter 4. Using Security Officer Mode
T he Enterprise Security Client, together with the T PS subsystem, supports a special security officer
mode of operation. T his mode allows a supervisory individual, a security officer, the ability to oversee the
face to face enrollment of regular users in a given organization.
Security officer mode provides the ability to enroll individuals under the supervision of a security officer,
a designated user-type who can manage other user's smart cards in face-to-face and very secure
operations. Security officer mode overlaps with some regular user operations, with additional security
features:
T he ability to search for an individual within an organization.
An interface that displays a photo and other pertinent information about an individual.
T he ability to enroll approved individuals.
Formatting or resetting a user's card.
Formatting or resetting a security officer's card.
Enrolling a temporary card for a user that has misplaced their primary card.
Storing T PS server information on a card. T his Phone Home information is used by the Enterprise
Security Client to contact a given T PS server installation.
Working in the security officer mode falls into two distinct areas:
Creating and managing security officers.
Managing regular users by security officers.
When security officer mode is enabled, the Enterprise Security Client uses an external user interface
provided by the server. T his interface takes control of smart card operations in place of the local XUL
code that the Enterprise Security Client normally uses.
T he external interface maintains control until security officer mode is disabled.
TIP
It is a good idea to run security officer clients over SSL, so make sure that the T PS is configured
to run in SSL, and then point the Enterprise Security Client to the T PS's SSL agent port.
4.1. Enabling Security Officer Mode
T here are two areas where the security officer mode must be configured, both in the T PS and in the
Enterprise Security Client's esc-prefs.js file.
In the T PS:
1. Add the security officer user entry to the T PS database as a member of the T US Officers group.
TIP
It can be simpler to add and copy user entries in the LDAP database using the Red Hat
Directory Server Console. Using the Directory Server Console is described more in the Red
Hat Directory Server Administrators Guide in section 3.1.2, "Creating Directory Entries."
44
Chapter 4. Using Security Officer Mode
T here are two subtrees associated with the T PS. One is for external users, which has a
distinguished name (DN) like dc=server,dc=exam ple,dc=com ; this directory is used to
authenticate any user attempting to enroll a smart card. T he other database is used for internal
T PS instance entries, including T PS agents, administrators, and security officers. T his subtree
has a DN like dc=server.exam ple.com -pki-tps. T he T US Officers group entry is under the
dc=server.exam ple.com -pki-tps suffix.
Any security officer entry has to be a child entry of the T US Officers group entry. T his means that
the group entry is the main entry, and the user entry is directly beneath it in the directory tree.
T he T US Officers group entry is cn=T US
Officers,ou=Groups,dc=server.exam ple.com -pki-tps.
For example, to add the security officer entry using ldapm odify:
/usr/lib/mozldap/ldapmodify -a -D "cn=Directory Manager" -w secret -p 389 -h
server.example.com
dn: uid=jsmith,cn=TUS Officers,ou=Groups, dc=server.example.com-pki-tps
objectclass: inetorgperson
objectclass: organizationalPerson
objectclass: person
objectclass: top
sn: smith
uid: jsmith
cn: John Smith
mail: [email protected]
userPassword: secret
Press the Enter key twice to send the entry, or use Ctrl+D.
2. Check the T PS's security officer workstation to make sure it is pointing to the external user
subtree DN to authenticate users who will enroll smart cards.
vim /var/lib/pki-tps/cgi-bin/sow/cfg.pl
#
# Feel free to modify the following parameters:
#
my $ldapHost = "localhost";
my $ldapPort = "389";
my $basedn = "ou=People,dc=server, dc=example,dc=com";
my $port = "7888";
my $secure_port = "7889";
my $host = "localhost";
T hen, configure the Enterprise Security Client.
1. First, trust the CA certificate chain.
a. Open the CA's end-entities page.
https://server.example.com:9444/ca/ee/ca/
b. Click the Retrieval tab, and download the CA certificate chain.
c. Open the Enterprise Security Client.
esc
45
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
d. Click the View Certificates button.
e. Click the Authorities tab.
f. Click the Im port button, and import the CA certificate chain.
g. Set the trust settings for the CA certificate chain.
2. T hen, format and enroll the security officer's token. T his token is used to access the security
officer Enterprise Security Client UI.
a. Insert a blank token.
b. When the prompt for the Phone Home information opens, enter the security officer URL.
/var/lib/pki-tps/cgi-bin/so/index.cgi
c. Click the Form at button to format the security officer's token.
d. Close the interface and stop the Enterprise Security Client.
e. Add two parameters in the esc-prefs.js file. T he first,
esc.disable.password.prom pt, sets security officer mode. T he second,
esc.security.url, points to the security officer enrollment page. Just the presence of
the esc.security.url parameter instructs the Enterprise Security Client to open in
security officer mode next time it opens.
pref("esc.disable.password.prompt","no");
pref("esc.security.url","https://server.example.com:7888/cgibin/so/enroll.cgi");
f. Start the Enterprise Security Client again, and open the UI.
esc
g. T he Enterprise Security Client is configured to connect to the security officer enrollment
form in order to enroll the new security officer's token. Enroll the token as described in
Section 4.2, “Enrolling a New Security Officer”.
h. Close the interface and stop the Enterprise Security Client.
i. Edit the esc-prefs.js file again, and this time change the esc.security.url
parameter to point to the security officer workstation page.
pref("esc.security.url","https://server.example.com:7889/cgibin/sow/welcome.cgi");
j. Restart the Enterprise Security Client again. T he UI now points to the security officer
workstation to allow security officers to enroll tokens for regular users.
T o disable security officer mode, close the Enterprise Security Client GUI, stop the escd process, and
comment out the esc.securty.url and esc.disable.password.prom pt lines in the escprefs.js file. When the esc process is restarted, it starts in normal mode.
4.2. Enrolling a New Security Officer
Security officers are set up using a separate, unique interface than the one for regular enrollments or
the one used for security officer-managed enrollments.
1. Make sure the esc process is running.
46
Chapter 4. Using Security Officer Mode
esc
T hen open the Enterprise Security Client UI.
With security officer mode enabled in the esc-pref.js file (Section 4.1, “Enabling Security
Officer Mode”) the security officer enrollment page opens.
2. In the Security Officer Enrollm ent window, enter the LDAP user name and password of
the new security officer and a password that will be used with the security officer's smart card.
47
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
NOTE
If the password is stored using the SSHA hash, then any exclamation point (!) and dollar
sign ($) characters in the password must be properly escaped for a user to bind
successfully to the Enterprise Security Client on Windows XP and Vista systems.
For the dollar sign ($) character, escape the dollar sign when the password is created:
\$
T hen, enter only the dollar sign ($) character when logging into the Enterprise Security
Client.
For the exclamation point (!) character, escape the character when the password is
created and when the password is entered to log into the Enterprise Security Client.
\!
3. Click Enroll My Sm artcard.
T his produces a smart card which contains the certificates needed by the security officer to access the
Enterprise Security Client security officer, so that regular users can be enrolled and managed within the
system.
4.3. Using Security Officers to Manage Users
T he security officer Station page manages regular users through operations such as enrolling new or
temporary cards, formatting cards, and setting the Phone Home URL.
4.3.1. Enrolling a New User
T here is one significant difference between enrolling a user's smart card in security officer mode and the
process in Section 3.5, “Enrolling a Smart Card Automatically” and Section 3.6.6, “Enrolling Smart Cards”.
All processes require logging into an LDAP database to verify the user's identity, but the security officer
mode has an extra step to compare some credentials presented by the user against some information in
the database (such as a photograph).
1. Make sure the esc process is running. If necessary, start the process.
esc
Also, make sure that security officer mode is enabled, as described in Section 4.1, “Enabling
Security Officer Mode”.
2. T hen open the Enterprise Security Client UI.
NOTE
Ensure that there is a valid and enrolled security officer card plugged into the computer. A
security officer's credentials are required to access the following pages.
48
Chapter 4. Using Security Officer Mode
3. Click Continue to display the security officer Station page. T he client may prompt for the
password for the security officer's card (which is required for SSL client authentication) or to
select the security officer's signing certificate from the drop-down menu.
4. Click the Enroll New Card link to display the Security Officer Select User page.
5. Enter the LDAP name of the user who is to receive a new smart card.
6. Click Continue. If the user exists, the Security Officer Confirm User page opens.
7. Compare the information returned in the Enterprise Security Client UI to the person or credentials
that are present.
8. If all the details are correct, click Continue to display the Security Officer Enroll User
49
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
page. T his page prompts the officer to insert a new smart card into the computer.
9. If the smart card is properly recognized, enter the new password for this card and click Start
Enrollm ent.
A successful enrollment produces a smart card that a user can use to access the secured network and
services for which the smart card was made.
4.3.2. Performing Other Security Officer Tasks
All of the other operations that can be performed for regular users by a security officer — issuing
temporary tokens, re-enrolling tokens, or setting a Phone Home URL — are performed as described in
Chapter 3, Using the Enterprise Security Client, after opening the security officer UI.
1. Make sure the esc process is running. If necessary, start the process.
esc
Also, make sure that security officer mode is enabled, as described in Section 4.1, “Enabling
Security Officer Mode”.
2. T hen open the Enterprise Security Client UI.
NOTE
Ensure that there is a valid and enrolled security officer card plugged into the computer. A
security officer's credentials are required to access the following pages.
3. Click Continue to display the security officer Station page. You may be prompted to enter the
password for the security officer's card. T his is required for SSL client authentication.
4. Select the operation from the menu (enrolling a temporary token, formatting the card, or setting the
Phone Home URL).
50
Chapter 4. Using Security Officer Mode
5. Continue the operation as described in Chapter 3, Using the Enterprise Security Client.
4.3.3. Formatting an Existing Security Officer Smart Card
NOTE
An e-gate token cannot be formatted on a Windows machine using the Enterprise Security Client.
T o format an e-gate card, perform the operation on Red Hat Enterprise Linux or Mac.
IMPORTANT
Reformatting a token is a destructive operation to the security officer's token and should only be
done if absolutely needed.
1. Click Form at SO Card. Because the security officer card is already inserted, the following
screen displays:
51
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
2. Click Form at to begin the operation.
When the card is successfully formatted, the security officer's card values are reset. Another security
officer's card must be used to enter security officer mode and perform any further operations.
52
Chapter 5. Using Keys on Smart Cards for Web and Mail Clients
Chapter 5. Using Keys on Smart Cards for Web and Mail Clients
After a token is enrolled, the token can be used for SSL client authentication and S/MIME email
applications. T he PKCS #11 module has different names and is located in different directories
depending on the operating system.
T able 5.1. PKCS #11 Module Locations
Platform
Module Name
Location
Red Hat Enterprise Linux
libcoolkeypk11.so
/usr/lib/
Windows
coolkeypk11.dll
C:\Windows\System32\
Mac OS X 10.5.8 and higher
libcoolkeypk11.dylib
/Library/Application
Support/CoolKey/PKCS11
5.1. Setting up Browsers to Support SSL for Tokens
T his is the procedure for Mozilla Firefox. T he procedure for setting up certificates for browsers varies
for each browser.
1. In Mozilla Firefox, open the T ools menu, choose Options, and then click Advanced.
2. Add a PKCS #11 driver.
NOTE
Windows and Mac systems automatically attempt to load the PKCS #11 module to any
Mozilla browsers they find. Only load the PKCS#11 modules manually if there is a problem
detecting the module automatically or if a browser is installed after Enterprise Security
Client is installed.
a. Click Manage Security Devices to open the Device Manager window, and then click
the Load button.
b. Enter a module name, such as token key pk11 driver.
c. Click Browse, find the Enterprise Security Client PKCS #11 driver, and click OK.
53
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
3. If the CA is not yet trusted, download and import the CA certificate.
a. Open the SSL End Entity page on the CA. For example:
https://server.example.com:9444/ca/ee/ca/
b. Click the Retrieval tab, and then click Im port CA Certificate Chain.
c. Click Download the CA certificate chain in binary form and then click
Subm it.
d. Choose a suitable directory to save the certificate chain, and then click OK.
e. Click Edit > Preferences, and select the Advanced tab.
f. Click the View Certificates button.
g. Click Authorities, and import the CA certificate.
4. Set the certificate trust relationships.
a. Click Edit > Preferences, and select the Advanced tab.
b. Click the View Certificates button.
c. Click Edit, and set the trust for websites.
T he certificates can be used for SSL.
5.2. Using the Certificates on Tokens for Mail Clients
T his is the procedure for Mozilla T hunderbird. T he procedure for setting up certificates for mail clients
varies for each client.
1. In Mozilla T hunderbird, open the Edit menu, and select Account Settings.
2. Select Security on the left.
3. Add a PKCS #11 driver.
a. Click Manage Security Devices to open the Device Manager window.
b. Click the Load button.
c. Enter the module name, such as token keypk11 driver.
d. Click Browse, find the Enterprise Security Client PKCS #11 driver, and click OK.
54
Chapter 5. Using Keys on Smart Cards for Web and Mail Clients
4. If the CA is not yet trusted, download and import the CA certificate.
a. Open the SSL End Entity page on the CA. For example:
https://server.example.com:9444/ca/ee/ca/
b. Click the Retrieval tab, and then click Im port CA Certificate Chain.
c. Click Download the CA certificate chain in binary form and then click
Subm it.
d. Choose a suitable directory to save the certificate chain, and then click OK.
e. In T hunderbird, open the Edit menu, and select Account Settings.
f. Select Security on the left, and click the Manage Certificates button.
g. Click the Authorities tab, and import the CA certificate.
5. Set up the certificate trust relationships.
a. In T hunderbird, open the Edit menu, and select Account Settings.
b. Select Security on the left, and click the Manage Certificates button.
c. In the Authorities tab, select the CA, and click the Edit button.
d. Set the trust settings for identifying websites and mail users.
e. In the Digital Signing section of the Security panel, click Select to choose a
certificate to use for signing messages.
6. In the Encryption of the Security panel, click Select to choose the certificate to encrypt and
decrypt messages.
5.3. Setting up Mail and Browser Clients on Mac OS X
On Mac, both Safari and Apple Mail are configured to use a smart card for authentication by adding the
certificates to the Apple keystore.
1. Enroll a smart card that contains your email address in the certificate, such as Section 3.5,
“Enrolling a Smart Card Automatically”.
For convenience, the T PS server cand be configured to use an LDAP directory for user and email
information. T his is covered in Section 3.4, “Setting up Users to Be Enrolled”.
2. Download the CA certificate.
a. Open the SSL End Entity page on the CA. For example:
https://server.example.com:9444/ca/ee/ca/
b. Click the Retrieval tab, and then click Im port CA Certificate Chain.
c. Select the Display certificates in the CA certificate chain for
im porting individually into a server radio button.
d. T he browser displays a list of certificates in base-64 format. Pick the first blob displayed,
and create and save a text file, with a name like ca.cer.
3. Import the CA certificate text file using the Apple KeyChain utility, and set the trust options.
a. Click on the System keyhchain.
b. In the main menu, click File|Import Items.
c. Browse to the location where the CA certificate file, ca.cer, is saved.
d. During the import operation, agree to trust the certificate always.
4. Insert the enrolled CoolKey token.
55
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
5. When the KeyChain access utility opens, the new keychain, with your name, is displayed.
6. Locate the certificates under the smart card's keychain.
7. Drag and drop the smart card certificates into the login keychain.
56
Chapter 6. Configuring the Enterprise Security Client
Chapter 6. Configuring the Enterprise Security Client
T he 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
T he Enterprise Security Client can be launched without requiring extra configuration.
6.1. Overview of Enterprise Security Client Configuration
T he Enterprise Security Client is an intermediary frontend that provides connections between users
(and their tokens), the T oken Processing System, and certificate authority. T he 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, HT ML, and JavaScript
T he 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 HT ML 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 HT ML.
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.
T he Enterprise Security Client, in conjunction with the T oken Processing System, supports different user
profiles so that different types of users have different token enrollment paths. Both the Enterprise
Security Client and T PS 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 T PS, and are
described in the Certificate System Administrator's Guide.
6.1.1. About the Preferences Configuration Files
T he Enterprise Security Client is configured similarly to Mozilla applications, using preferences files. T he
primary configuration file is esc-prefs.js, which is installed with Enterprise Security Client. T he
second one is prefs.js in the Mozilla profiles directory, which is created when the Enterprise Security
Client is first launched.
T he 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 Windows, this is in C:\Program Files\Red Hat\ESC\defaults\preferences\escprefs.js.
On Red Hat Enterprise Linux 32-bit, this is in /usr/lib/esc1.1.0/defaults/preferences/esc-prefs.js.
57
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
On Red Hat Enterprise Linux 64-bit, this is in /usr/lib64 /esc1.1.0/defaults/preferences/esc-prefs.js.
On Mac, this is in ~/Desktop/ESC.app/defaults/preferences/esc-prefs.js.
T he esc-prefs.js file specifies the default configuration to use when the Enterprise Security Client is
first launched. T his includes parameters to connect to the T PS subsystem, to use CAPI on Windows, 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);
T he esc-prefs.js file parameters are listed in T able 6.1, “esc-prefs.js Parameters”. T he default escprefs.js file is shown in Example 6.1, “Default esc-prefs.js File”.
58
Chapter 6. Configuring the Enterprise Security Client
T able 6.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.defaultChrom
eURI",
"chrome://esc/content
/settings.xul")
esc.tps.message.timeout
Sets a timeout period, in seconds, for
connecting to the T PS.
("esc.tps.message.ti
meout","90");
esc.windows.do.capi
Enables the client to connect to
Windows CAPI. T his writes newlycreated certificates to the local CAPI
store after an enrollment operation
and removes those certificates when
the formatting operation is complete.
("esc.windows.do.cap
i","yes");
esc.disable.password.prompt
Enables the password prompt, which
means that a password is required to
read the certificate information off the
smart card. T he 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.passwo
rd.prompt","yes");
esc.global.phone.home.url
Sets the URL to use to contact the
T PS server.
("esc.global.phone.ho
me.url",
"http://server.example
.com:7888/cgibin/home/index.cgi");
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 T PS server, then the
Enterprise Security Client checks for
a global default Phone Home URL.
T his setting is only checked if it is
explicitly set. T his setting also applies
to every token formatted through the
client, so setting this parameter
forces all tokens to point to the same
T PS. Only use this parameter if that
specific behavior is desired.
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.
prefs("esc.global.alt.n
ss.db",
"C:/Documents and
Settings/All
Users/shared-db");
59
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T his 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.
Example 6.1. Default esc-prefs.js File
T he 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/cgibin/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/cgibin/home/index.cgi");
When the Enterprise Security Client is launched, it creates a separate, unique profile directory for each
user on the system. T hese profiles are stored in different locations on each platform:
On Windows, this is in C:\Docum ents and Settings\$USER\Application
Data\RedHat\ESC\Profiles\alphanumeric_string.default/prefs.js.
On Red Hat Enterprise Linux, this is in
~/.redhat/esc/alphanumeric_string.default/prefs.js.
On Mac, this is in ~/Library/Application Support/ESC/Profiles.
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.
T able 6.2, “prefs.js Parameters” lists the most relevant parameters for the prefs.js file. Editing this file
60
Chapter 6. Configuring the Enterprise Security Client
is tricky. T he 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.
61
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T able 6.2. prefs.js Parameters
Parameter
Description
esc.tps.url
Sets a URL for the Enterprise
Security Client to use to connect to
the T PS. T his is not set by default.
esc.key.token_ID.tps.url
Sets the hostname and port to use to
contact a T PS.
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 T PS URL, an
enrollment page URL, the issuer's
name, and Phone Home URL.
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 T PS URL, an
enrollment page URL, the issuer's
name, and Phone Home URL.
Notes and Defaults
("esc.key.token_ID.tp
s.url" =
"http://server.example
.com:7888/nk_service
");
("esc.key.token_ID.tp
s.enrollment-ui.url" =
"http://server.example
.com:7888/cgi_bin/es
c.cgi?");
esc.key.token_ID.issuer.name
Gives the name of the organization
enrolling the token.
("esc.key.token_ID.is
suer.name" =
"Example Corp");
esc.key.token_ID.phone.home.url
Gives the URL to use to contact the
("esc.key.token_ID.ph
Phone Home functionality for the T PS. one.home.url" =
"http://server.example
T he global Phone Home parameter
.com:7888/cgisets a default to use with any token
bin/home/index.cgi?");
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.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.
62
("esc.security.url","htt
ps://server.example.c
om:7888/cgibin/so/enroll.c
gi");
Chapter 6. Configuring the Enterprise Security Client
6.1.2. 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 ]/esc1.1.0/chrom e/content/esc/.
T he primary Enterprise Security Client XUL files are listed in T able 6.3, “Main XUL Files”.
T able 6.3. Main XUL Files
Filename
Purpose
settings.xul
Contains the code for the Settings page.
esc.xul
Contains the code for the Enrollm ent page.
config.xul
Contains the code for the configuration UI.
T he primary Smart Card Manager JavaScript files are listed in the following table.
T able 6.4 . Main JavaScript Files
Filename
Purpose
ESC.js
Contains most of the Smart Card Manager
JavaScript functionality.
T RAY.js
Contains the tray icon functionality.
AdvancedInfo.js
Contains the code for the Diagnostics feature.
GenericAuth.js
Contains the code for the authentication prompt.
T his prompt is configurable from the T PS server,
which requires dynamic processing by the Smart
Card Manager.
6.1.3. Enterprise Security Client File Locations
T his reference shows the different directories and file locations for the different client machines.
T he location of the Enterprise Security Client main directory on the different client platforms is as follows:
T able 6.5. Main Directories for the Enterprise Security Client
Platform
Location
Windows
C:\Program Files\Red Hat\ESC
Red Hat Enterprise Linux
/usr/lib/esc-1.1.0/esc
/usr/lib64/esc-1.1.0/esc
Mac
/Applications, but users can drag the ESC.app
directory anywhere
On Windows, Enterprise Security Client uses the following directories and files:
63
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
T able 6.6. Enterprise Security Client File and Directory Locations on Windows
File or Directory
Purpose
C:\Program Files\Red Hat\ESC
Main directory.
application.ini
XULRunner application configuration file
components\
XPCOM components directory.
chrome\
Directory for Chrome components and additional
application files for Enterprise Security Client XUL
and JavaScript.
defaults\
Enterprise Security Client default preferences.
esc.exe
T he executable which launches Enterprise
Security Client in XULRunner.
xulrunner\
Privately-deployed XULRunner bundle.
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
Unlike Windows and Mac versions of Enterprise Security Client, the Enterprise Security Client on
Red Hat Enterprise Linux uses the system XULRunner packages rather than a privately-deployed
XULRunner bundle.
T able 6.7. Enterprise Security Client File and Directory Locations on Red Hat Enterprise
Linux
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
T he script which launches the Enterprise Security
Client.
On Mac OS X, the XULRunner framework located in ESC.app.
64
Chapter 6. Configuring the Enterprise Security Client
T able 6.8. Enterprise Security Client File and Directory Locations on Mac
File or Directory
Purpose
Contents/
Privately deployed XUL framework
Info.plist
Frameworks/
XUL.framework/
Resources
application.ini
Enterprise Security Client XULRunner application
configuration file.
components/
Enterprise Security Client XPCOM components.
chrome/
Directory for Chrome components and additional
application files for Enterprise Security Client XUL
and Javascript.
defaults/
Enterprise Security Client default preferences.
xulrunner
T he script which launches Enterprise Security
Client.
6.2. Configuring SSL Connections with the TPS
By default, the T PS communicates with the Enterprise Security Client over standard HT T P. It may be
desirable to secure the T PS-client communications by using HT T P over SSL (HT T PS).
1. T he Enterprise Security Client has to have the CA certificate for the CA which issued the T PS's
certificates in order to trust the T PS connection. Import the CA certificate as described in
Section 3.6.4, “Importing CA Certificates”.
2. T he Enterprise Security Client needs to be configured to communicate with the T PS 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 T PS.
3. Open the Enterprise Security Client.
65
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
4. 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.
5. Fill in the new T PS URL with the SSL port information. For example:
https://server.example.com:7890/cgi-bin/home/index.cgi
6. Click the T est button to send a message to the T PS.
7. If the request is successful, the client opens a dialog box saying that the Phone Home URL was
successfully obtained.
6.3. Using Shared Security Databases
T he Enterprise Security Client usually creates a new NSS security database for keys and certificates for
each user profile associated with the Enterprise Security Client. Whenever a user imports or trusts a
certificate for the Enterprise Security Client to use, it is imported into that NSS database for that profile.
(T his is similar to the way that web browsers have different user profiles with different security
databases, password stores, and bookmarks for each profile.)
T here may be instances when there are multiple Enterprise Security Client users who all use the client
on a single machine. In that case, it makes sense to have a common, shared security database that is
trusted by the Enterprise Security Client in addition to the user profile databases. T hat shared security
database contains certificates that are held in common by all users, such as the CA signing certificate
used by the T PS.
Using a shared security database is not configured by default.
1. Stop the Enterprise Security Client.
2. Create the security database directory and the databases that will be shared. Before configuring
the Enterprise Security Client, the databases must exist, be readable by the client, and contain the
certificates that will be used by the client.
NSS databases can be created using the certutil command. See the certutil
documentation, such as http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html, for more
information.
3. Open the esc-prefs.js file.
vim /usr/lib/esc-1.1.0/defaults/preferences/esc-prefs.js
4. Add the esc.global.alt.nss.db parameter, pointing to the directory which contains the
shared database.
prefs("esc.global.alt.nss.db", "C:/Documents and Settings/All
Users/common_db");
5. When the Enterprise Security Client is restarted, the configuration changes will be applied.
6.4. Customizing the Smart Card Enrollment User Interface
T he T PS subsystem displays a generically-formatted smart card enrollment screen which is opened
automatically when an uninitialized smart card is inserted. T his is actually comprised of three pages,
depending on the mode in which the client is running:
66
Chapter 6. Configuring the Enterprise Security Client
/var/lib/pki-tps/cgi-bin/hom e/Enroll.htm l for regular enrollments
/var/lib/pki-tps/cgi-bin/so/Enroll.htm l for security officer enrollments
/var/lib/pki-tps/cgi-bin/sow/Enroll.htm l for security officer workstation enrollments
(users enrolled through the security officer UI)
NOTE
T he security officer workstation directory contains other HT ML files for other token operations,
such as formats and PIN resets.
T here may be even more enrollment pages if there are custom user profiles.
T hese enrollment pages are basic HT ML and JavaScript, which allows them to be easily customized for
both their appearance and functionality. T he resources, such as images and JavaScript files, referenced
by the enrollment file are located in the corresponding docroot/ directory, such as /var/lib/pkitps/docroot/esc/sow for the security officer enrollment file in /var/lib/pki-tps/cgi-bin/sow.
T here are several ways that the smart card enrollment pages can be customized. T he first, and
simplest, is changing the text on the page. T he page title, section headings, field names, and
descriptions can all be changed by editing the HT ML file, as shown in the extracts in Example 6.2,
“Changing Page T ext”.
Example 6.2. Changing Page T ext
<!-- Change the title if desired -->
<title>Enrollment</title>
...
<p class="headerText">Smartcard Enrollment</p>
...
<!-- Insert customized descriptive text here. -->
<p class="bodyText">You have plugged in your smart card!
After answering a few easy questions, you will be able to use your
smart card.
</p>
<p class="bodyText">
Now we would like you to identify yourself.
</p>
...
<table>
<tr>
<td><p >LDAP User ID: </p></td>
<td> </td>
<td><input type="text" id="snametf" value=""></td>
</tr>
</table>
T he styles of the page can be changed through two files: the style.css CSS style sheet and the logo
image, logo.png.
67
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
Example 6.3. Changing Page Styles
<link rel=stylesheet href="/esc/home/style.css" type="text/css">
...
<table width="100%" class="logobar">
<tr>
<td>
<img alt="" src="/home/logo.jpg">
</td>
<td>
<p class="headerText">Smartcard Enrollment</p>
</td>
</tr>
</table>
T he style.css file is a standard CSS file, so all of the tags and classes can be defined as follows:
body {
background-color: grey;
font-family: arial;
font-size: 7p
}
More information on CSS is available at http://www.w3.org/Style/CSS/learning.
T he last way to customize the Enroll.htm l files is through the JavaScript file which sets the page
functionality. T his file controls features like the progress meter, as well as processing the inputs which
are used to authenticate the user to the user directory.
Example 6.4 . Changing Page Script
<progressmeter id="progress-id" hidden="true" align = "center"/>
...
<table>
<tr>
<td><p >LDAP User ID: </p></td>
<td> </td>
<td><input type="text" id="snametf" value=""></td>
</tr>
</table>
WARNING
Be very cautious about changing the util.js file. If this file is improperly edited, it can break the
Enterprise Security Client UI and prevent tokens from being enrolled.
T he complete /var/lib/pki-tps/cgi-bin/hom e/Enroll.htm l file is in Example 6.5, “Complete
Enroll.html File”.
68
Chapter 6. Configuring the Enterprise Security Client
Example 6.5. Complete Enroll.html File
69
Red Hat Certificate System 8.0 Managing Smart Cards with the Enterprise Security Client
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel=stylesheet href="/esc/home/style.css" type="text/css">
<title>Enrollment</title>
</head>
<script type="text/JavaScript" src="/esc/home/util.js">
</script>
<body onload="InitializeBindingTable();" onunload=cleanup()>
<progressmeter id="progress-id" hidden="true" align = "center"/>
<table width="100%" class="logobar">
<tr>
<td>
<img alt="" src="/home/logo.jpg">
</td>
<td>
<p class="headerText">Smartcard Enrollment</p>p
</td>
</tr>
</table>
<table id="BindingTable" width="200px"align="center">
<tr id="HeaderRow">
</tr>
</table>
<p class="bodyText">You have plugged in your smart card! After answering a few
easy questions, you will be able to use your smart card.
</p>p
<p class="bodyText">
Now we would like you to identify yourself.
</p>p
<table>
<tr>
<td><p >LDAP User ID: </p>p</td>
<td> </td>
<td><input type="text" id="snametf" value=""></td>
<td> </td>
<td><p>LDAP Password: </p>p</td>
<td> </td>
<td><input type="password" id="snamepwd" value=""></td>
</tr>
</table>
<p class="bodyText"> Before you can use your smart card, you will need a
password to protect it.</p>p
<table>
<tr>
<td><p >Password:</p>p</td>
<td><input type="password" id="pintf" name="pintf" value=""></td>
<td><p >Re-Enter Password:</p>p</td>
<td><input type="password" id="reenterpintf" name="reenterpintf"
value=""></td>
</table>
<br>
<table width="100%">
<tr>
<td align="right">
70
Chapter 6. Configuring the Enterprise Security Client
<input type="button" id="enrollbtn" name="enrollbtn" value="Enroll My
Smartcard" onClick="DoEnrollCOOLKey();">
</td>
</tr>
</table>
</body></html>
6.5. Disabling LDAP Authentication for Token Operations
By default, each user who requests a token operation is authenticated against an LDAP directory. If the
user has an entry, then the operation is allowed; if the user does not have an entry, then the operation is
rejected.
For testing or for certain types of users, then it may be simpler or preferable to disable LDAP
authentication. T his is not configured in the Enterprise Security Client configuration, but in the T oken
Processing System configuration, and must be done by a T PS administrator.
1. Stop the T PS subsystem.
service pki-tps stop
2. Set the authentication parameters to false.
op.operation_type.token_type.loginRequest.enable=false
op.operation_type.token_type.auth.enable=false
T he operation_type is the token operation for which LDAP authentication is being disabled, such
as enroll, form at, or pinreset. Disabling authentication for one operation type does not
disable it for any other operation types.
T he token_type is the token profile. T here are default profiles for regular users, security officers,
and the users enrolled by security officers. T here 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
3. Restart the T PS subsystem.
service pki-tps start
Editing the T PS configuration is covered in the Certificate System Administrator's Guide.
71
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement