ESC Guide

Introduction

The Smart Card Manager is a simple client application designed manage security smart card within the context of the overall Dogtag Certificate System. Update!! Dogtag Certificate System is now live. More information on Dogtag can be found here: Dogtag. Specifically this component interacts with the Token Processing System component of Dogtag Certificate System providing the following functions:

More information on the Token Processing System portion of Dogtag can be found here: TPS

The Dogtag Certificate System creates, manages, renews, and deletes certificates and keys within an organization. There are five subsystems which govern the behavior of the public-key infrastructure (PKI) of the organization:

End users can use security tokens, which are also called 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. To use the tokens, the TPS must be able to recognize and communicate with them. The tokens have to be enrolled, the process of formatting tokens with keys and certificates and adding them to the Certificate System. Smart Card Manager provides the user interface for end entities to enroll tokens and to communicate with the TPS. Smart Card Manager provides the conduit through which TPS communicates with each token over a secure HTTP channel (HTTPS).

After a token is enrolled, applications such as Mozilla Firefox and Thunderbird can be configured to recognize the token and use it for security operations, like client authentication and S/MIME mail. Smart Card Manager provides the following capabilities:

Technologies

The Smart Card Manager makes heavy use of Mozilla browser technology in its operation:

Supporting Components

On each platform , Smart Card Manager, depends upon a variety of low level components for its operation. Following is a list of the low level components:

Platforms

Smart Card Manager runs on the following platforms:

Features

Smart Card Manager brings the following set of features:

How to Get ESC

The following pre-built binaries of ESC are available as follows:

Build Instructions

Being able to build Smart Card Manager on each platform at this point depends upon one’s ability to build a Mozilla browser. This is the case since Xulrunner is simply a build variation of the Mozilla browser base. The Linux and Windows platform build Xulrunner 1.8.0.4 while Mac builds Xulrunner 1.8.0.7 for Universal binary functionality. Building the browsers can be a lengthy process based on machine.

How to get the source

The code is available on CVS. To check out the code,simply do the following:

cvs -d :pserver:anonymous@cvs.fedora.redhat.com/cvs/dirsec co esc

The following build instructions are divided per platform:

Linux

Prerequisites

Building on Linux requires that one can build the Mozilla Lizard. Building has been tested on F6 and F7. Requirements for this can be found here: Linux Build Prerequisites

Inspection of the current spec file BuildRequires section also reveals what is needed:

BuildRequires: doxygen fontconfig-devel freetype-devel >= 2.1
BuildRequires: glib2-devel libIDL-devel atk-devel gtk2-devel libjpeg-devel
BuildRequires: pango-devel libpng-devel pkgconfig zlib-devel
BuildRequires: nspr-devel nss-devel
BuildRequires: autoconf213 libX11-devel libXt-devel

BuildRequires: pcsc-lite-devel coolkey-devel
BuildRequires: desktop-file-utils zip binutils libnotify-devel
BuildRequires: dbus-devel
Requires: pcsc-lite ifd-egate coolkey nss nspr
Requires: zip dbus >= 0.90 libnotify >= 0.4.2

Steps:

The above kicks off a simple script that will download the latest SRPM and build it under a buildroot under the current “rpm” directory.

Mac OS X

Smart Card Manager and supporting components are built as universal binary executables able to run on Intel or PPC hardware.

Prerequisites

here: OS X Mozilla Build Prerequisites

Steps:
Build TokenD

The current CoolKey TokenD is built with a recent (10.4.9) version of the Mac “darwinbuild” system. “Darwinbuild” refers to an open source set of scripts designed to easily build projects included as part of their open source offerings. Previously, the CoolKey TokenD was built with an early version of darwinbuild. This version of TokenD experienced binary compatibility issues with the upcoming revision of the OS, thus the need to upgrade the version of “darwinbuild” used to build the source. The build process creates a universal TokenD for both Intel and PPC. The following is how this build can be done:

Ex:

    cp /usr/bin/tar /Volumes/Builds/Build8P1237/usr/bin

Windows

Smart Card Manager and supporting components can be built on the Windows platform using the Cygwin platform.

Prerequisites

Once again, in order to build the application on Windows, the machine must be capable of building Xulrunner or Mozilla.

Inno Setup Script

The installer is assisted by the INNO setup compiler script called “setup.iss” Following are a few snippets containing settings for the registry that are optional:

[Registry]`
;The following lines register the CSP. Comment out if not available
Root: HKLM; Subkey: Software\Microsoft\Cryptography\Defaults\Provider\CoolKey PKCS#11 CSP; ValueType: string; ValueName:        PKCS11Module; ValueData: coolkeypk11.dll; Flags: uninsdeletekey
; The following lines set up Smart Card login if desired`
Root: HKLM; Subkey: Software\Microsoft\Cryptography\Calais\SmartCards\Axalto Developer; ValueType: binary; ValueName: ATRMask; ValueData: ff ff ff ff ff ff ff ff 00 00; Flags: uninsdeletekey`
Root: HKLM; Subkey: Software\Microsoft\Cryptography\Calais\SmartCards\Axalto Developer; ValueType: string; ValueName: Crypto   Provider; ValueData: CoolKey PKCS#11 CSP`
Root: HKLM; Subkey: Software\Microsoft\Cryptography\Calais\SmartCards\Axalto Developer; ValueType: binary; ValueName: ATR; ValueData: 3b 75 94 00 00 62 02 02 00 00`
;End CSP registration`
Root: HKLM; Subkey: Software\`
; Turn off the "pick a cert" dialog box`
Root: HKCU; Subkey: Software\Microsoft\Windows\CurrentVersion\Internet Settings\Zones\3; ValueType: dword; ValueName: 1A04; ValueData: 0`
; Enable TLS 1.0`
Root: HKCU; Subkey: Software\Microsoft\Windows\CurrentVersion\Internet Settings; ValueType: dword; ValueName: SecureProtocols; ValueData: 168`

Steps:

The build script does the following:

Build the CSP

Building the CSP requires that one satisfies most of the requirements needed to build CoolKey. Information on the Windows CSP along with build instructions are available here

General Build Information

Once the Smart Card Manager has been built, the following information should be useful if attempting to add any code and rebuild.

The application can be rebuilt fairly easily during development. There are just a few things to keep in mind:

Basic Smart Card Manager Usage

The following section contains basic instructions on using the Smart Card Manager for token enrollment, formating, and password reset operations.

Launching Smart Card Manager

Phone Home

The Smart Card Manager offers a feature called Phone Home that associates information within each smart card with information which points to distinct TPS servers and Smart Card Manager UI pages. Whenever the Smart Card Manager accesses a new smart card, it connects to the TPS server and retrieves the Phone Home information.

Phone Home quickly retrieves and then caches this information; because the information is cached locally, the TPS subsystem does not have to be contacted each time a formatted smart card is inserted.

The information can be different for every key or token, which means different TPS servers and enrollment URLs can be configured for different corporate or customer groups. Phone Home makes it possible to configure different TPS servers for different issuers or company units, without having to configure the Smart Card Manager manually to find the proper server and URL.

In order for the TPS subsystem to utilize the Phone Home feature, Phone Home must be enabled in the TPS configuration file:

op.format.tokenKey.issuerinfo.enable=true
op.format.tokenKey.issuerinfo.value=http://server.example.com

Since the Smart Card Manager is based on Mozilla XULRunner, each user has a profile similar to the user profiles used by Mozilla Firefox or Thunderbird. The Smart Card Manager accesses the configuration preferences file. When the Smart Card Manager caches information for each token, the information is stored in the user’s configuration file. The next time the Smart Card Manager is launched, it retrieves the information from the configuration file instead of contacting the server again.

The Phone Home information is put on the token in one of two ways:

The following information is used by the Phone Home feature for each smart card:

The Phone Home feature and the different type of information used by it only work when the TPS has been properly configured to use Phone Home. If the TPS is not configured for Phone Home, then this feature is ignored. The code below shows an example XML file used by the TPS subsystem to configure the Phone Home feature.

<ServiceInfo><IssuerName>`Example Corp`</IssuerName>
    `<Services>
        `<Operation>[`http://tps.example.com:12443/nk_service`](http://tps.example.com:12443/nk_service)` ## TPS server URL
        `</Operation>
        `<UI>[`http://tps.example.com:12443/cgi_bin/esc.cgi`](http://tps.example.com:12443/cgi_bin/esc.cgi)`   ## Optional
Enrollment UI
        `</UI>
        `<EnrolledTokenBrowserURL>[`http://www.test.url.com`](http://www.test.url.com)`   ## Optional
enrolled token url
        `</EnrolledTokenBrowserURL>;
     </Services>
</ServiceInfo>

Example TPS Phone Home Configuration File

Phone Home is triggered automatically when a security token is inserted into a machine. The system immediately attempts to read the Phone Home URL from the token and to contact the TPS server.

If no Phone Home information is stored on the token, the the user is prompted for the Phone Home URL, as shown below. The 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. The format process is not any different for the user.

Figure Prompt for Phone Home Information

The TPS configuration URI is the URL of the TPS server which returns the rest of the Phone Home information to the Smart Card Manager. An example of this URL is https://test.example.com:12443/cgi-bin/home/index.cgi. When the TPS configuration URI is accessed, the TPS server is prompted to return all of the Phone Home information to the Smart Card Manager.

The Test button can be used to test of the entered URL. If the server is successfully contacted, a message box indicates success. If the test connection fails, an error dialog appears. The Update Values button saves the new URLs.

Smart Card Auto Enrollment

Because the Smart Card Manager is configured through the Phone Home feature, simple enrollment of a smart card is extremely easy. Since the information needed to contact the backend TPS server is provided with each smart card, the enrollment process for the user is very simple.

Assuming that the smart card being enrolled is uninitialized and the appropriate Phone Home information has been configured, the user’s enrollment process is as follows:

  1. The Smart Card Manager is running.
  2. An uninitialized smart card, pre-formatted with the Phone Home information for the TPS and enrollment interface URL for the user’s organization, is inserted. The smart card can be added either by placing a USB form factor smart card into a free USB slot or by inserting a traditional full-sized smart card into a smart card reader.
  3. When the system recognizes the smart card, it displays a message indicating it has detected an uninitiated smart card.

Figure Smart Card Enrollment with a Card

This screen gives the option either to close the dialog or to proceed with enrolling the smart card. If the card be removed, a message appears that the smart card is no longer detected.

Figure . Smart Card Enrollment Message When the Card Is Removed

Reinserting the card brings the previous dialog back with the option to enroll the smart card. Click Enroll My Smart Card to continue with the enrollment process.

  1. Since the application now knows where the enrollment UI is located because of Phone Home, the enrollment form opens for the user to enter the required information. This UI can be customized.

Figure . Smart Card Enrollment Page

  1. This example is the default enrollment UI included with the TPS server. This UI is a standard HTML form, so simple modifications, such as setting the company logo or adding extra text or changing field text, is possible.
  2. The sample enrollment UI requires the following information for the TPS server to process the smart card enrollment operation:

LDAP User ID. This is the LDAP directory user ID of the user enrolling the smart card; this can also be a screen name or employee or customer ID number.

LDAP Password. This is the alpha-numeric password corresponding to the user ID entered; this can be a simple password or a customer number.

The LDAP user ID and password refer to the fact that the TPS server is usually associated with a Directory Server which stores user information and to which the TPS refers to authenticate users.

Password. This sets the smart card’s password, used to protect the card information.

Re-Enter Password. This confirms the smart card’s password.

  1. Once the form is filled out, click Enroll My Smartcard to submit the information and enroll the card.
  2. 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.

Figure . Smart Card Enrollment Success Message

Managing Smart Cards

The Manage Smart Cards page contains many of the operations that can be applied to one of the keys. This page allows users to format the token, set and reset the card’s password, and show the card information. Two other operations, enrolling tokens and viewing the diagnostic logging, are also accessed through the Manage Smart Cards page. These are addressed in other sections.

Figure . Manage Smart Cards Page

Formatting the Smart Card

Formatting the card brings the smart card to the uninitialized state, which removes all the user keypairs previously generated and erases the password set on the smart card during enrollment.

The TPS server can be configured to load newer versions of the applet and symmetric keys onto the card. Do the following to format the smart card:

  1. Place a supported smart card into the USB slot of the computer. Make sure the card shows up in the Active Smart Cards table.

For formatting the smart card, there is no need to enter the key password.

  1. Select Format from the Smart Card Functions section in the Manage Smart Cards screen.
  2. The TPS can be configured to authenticate smart card operations using credentials such as an LDAP user ID and password. If the TPS has been configured for user authentication, fill in the user credentials in the authentication prompt, and click OK.
  3. Wait for the token to finish being formatted. A success message will be displayed when the formatting operation is complete.
  4. When the formatting is complete, the Active Smart Cards table shows the key as uninitialized.

Reset 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 by doing the following:

  1. Place a supported smart card into the USB slot of the computer. Make sure the smart card shows up in the Active Smart Cards table.
  2. Click the Reset Password button in the Smart Card Functions window. A dialog for resetting the password on the card then opens.
  3. Enter a new smart card password value in the Enter new password field.
  4. Confirm the new smart card password value in the Re-Enter password field.

Figure . Changing Password Dialog

  1. The TPS can be configured to authenticate smart card operations using credentials such as an LDAP user ID and password. If the TPS has been configured for user authentication, fill in the user credentials in the authentication prompt.
  2. Wait for the token password to finish being reset.

Viewing Certificates

The View Certificates button shows basic information about the selected smart card, including the keys and certificates stored on it.

  1. Place a supported smart card into the USB slot of the computer. Make sure the card shows up in the Active Smart Cards table.
  2. Select the card from the list.
  3. Press the View Certificates button.
  4. Basic information about the certificates stored on the card is shown, including the serial number, certificate nickname, and validity dates. More detailed information about the certificate can be viewed by selecting a certificate from the list, and clicking View.

Enrolling Smart Cards

Although most smart cards will be enrolled using the automated enrollment,there is an alternative way of enrolling smart cards through the Manage Smart Cards page.

Figure. Manual Enrollment Form

Enrolling a token with the user key pairs means the token can be used for certificate-based operations such as SSL client authentication and S/MIME.

The TPS 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.

  1. Place a supported, unenrolled, smart card into the USB slot of the computer. Make sure the card shows up in the Active Smart Cards table at the top.
  2. Press the Enroll button. This button is active only if the inserted card is unenrolled.
  3. A dialog opens which is used to set the password on the smart card. Enter a new key password value in the Enter a password field.

Confirm the new card password value in the Re-Enter a password field.

  1. Click OK to begin the enrollment.
  2. The TPS server can be configured to authenticate the enrollment operation. If the TPS has been configured for authentication, enter the user credentials when the dialog box appears, and click OK.

Figure LDAP Authentication Prompt

  1. The enrollment process will begin generating and archiving keys, if the TPS is configured to archive keys to the DRM.
  2. When the enrollment is complete, the smart card will be listed as enrolled.

Diagnosing Problems

The Smart Card Manager 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. The diagnostic tools can identify and notify users about problems with the Smart Card Manager, smart cards, and TPS connections.

To open the diagnostics page, click on the Diagnostics button in the Manage Smart Cards screen.

The following problems or events are logged by the Smart Card Manager:

Figure Diagnostics Screen

The diagnostics screen displays the following information:

For each card detected, the following information is shown:

Smart Card Manager Configuration

Previously, Smart Card Manager relied on an application-specific configuration file. Smart Card Manager is now based on Mozilla XULRunner technology, which allows the preferences facility built into Mozilla to be used for simple configuration of the Smart Card Manager.

 The Smart Card Manager can be launched without requiring extra configuration.

Configuration

Smart Card Manager uses the Mozilla configuration preferences system on all three supported platforms. A default configuration file is located in the following directories on each platform:

This default configuration Javascript file contains the default Smart Card Manager configuration used when Smart Card Manager is first launched.

When Smart Card Manager is launched, a separate, unique profile directory for each user on the system is created; these profiles are stored in different, accessible locations on each platform, as shown:

 When the Smart Card Manager 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.

The esc-prefs.js file section below shows the Smart Card Manager-supported configuration values.

Example Configuration File ################################################################# #The entry below is the XUL chrome page where Smart Card Manager #proceeds on startup.  #  pref(“toolkit.defaultChromeURI”,   ”(chrome://esc/content/settings.xul)”); #The entry below is the URL Smart Card Manager consults #for back end TPS functionality.  #Note this is only a fallback setting. This information #is normally obtained through the ”Phone Home” functionality.  pref(“esc.tps.url”,”https://test.host.com:7888/nk_service)”); #The following three entries are for internal use  pref(“signed.applets.codebase_principal_support”,true);  pref(“capability.principal.codebase.p0.granted”,     ”UniversalXPConnect”);  pref(“capability.principal.codebase.p0.id”, ”file://”); #The entry below sets how many seconds Smart Card Manager #should wait while TPS is processing a message  pref(“esc.tps.message.timeout”,”90”); #The entry can be set allow Smart Card Manager to write #newly created certificates  #to the local CAPI store after an enrollment operation.  #Also, when a format is done, those same certs will be removed  #from the local CAPI store. pref(“esc.windows.do.capi”,”yes”);

Smart Card Manager Mac TokenD

The TokenD software installed on Mac 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 hold 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 TokenD allows a Certificate System key to show as a KeyChain.

Verifying the TokenD Is Working

  1. Make sure Smart Card Manager has been installed on the Mac computer.
  2. Use Smart Card Manager to enroll a token, enabling it with the proper certificates and key information.
  3. Put the enrolled token into a USB slot on the machine.
  4. If TokenD is working, the token blinks for a few seconds while the information is obtained from the token because the Mac CDSA layer is requesting data.
  5. Open the Mac Keychain Access utility in the Applications/Utilities folder.
  6. Find the new $Keychain entry in the list of valid chains. The chain has the the key’s UID in its name.
  7. Click on the CoolKey KeyChain. The certificates and keys on the token can easily be viewed.

Smart Card Manager File Locations

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

Windows

On Windows, Smart Card Manager uses the following directories and files:

Linux

On Linux, Smart Card Manager is installed by its binary RPM to the default location /usr/lib/esc-1.0.1/esc/.

Mac OS X

On Mac OS X, the XULRunner framework located in ESC.app as follows:

Smart Card Manager XUL, HTML, and Javascript Functionality

Smart Card Manager stores the XUL markup and Javascript functionality in the ESC_INSTALL_PATH /chrome/content/esc directory, where ESC_INSTALL_PATH is the Smart Card Manager installation directory.

The following are the primary Smart Card Manager XUL files:

The following are the primary Smart Card Manager Javascript files:

External Enrollment UI Customization Guide

Certificate System (specifically the TPS subsystem) comes out of the box with generic external smart card enrollment UI. Since this UI consists of HTML and Javascript, this UI can be customized for a specific deployment as desired.

Given a default TPS instance on a given machine, the enrollment UI can be located here:

/var/lib/rhpki-tps/cgi-bin/home/Enroll.html

The UI references resources such as images and Javascript files within its code. These resources are located here:

/var/lib/rhpki-tps/docroot/home

Below is a snippet of the default UI sprinkled with comments on how it might be customized:

  <html> 
   <head> 
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <link rel=stylesheet href="/home/style.css" type="text/css">

   <!-- Change the title if desired -->
   <title>Enrollment</title>

   </head>
   <script type="text/JavaScript" src="/home/util.js">
   </script>
   <body onload="InitializeBindingTable();" onunload=cleanup();>
   <progressmeter id="progress-id" hidden="true" align = "center"/>

   <table width="100%" class="logobar">
      <tr>
        <td>

           <!-- Use customized logo here... -->
           <img alt="" src="/home/logo.jpg">

        </td>
        <td>
          <p class="headerText">Smartcard Enrollment</p>
        </td>
        </tr>
      </table>
        <table id="BindingTable" width="200px"align="center">
       <tr id="HeaderRow">
       </tr>
     </table>
     
     <!-- Insert customized descriptive text here. -->
     <p class="bodyText">You have plugged in your smartcard! After answering a few easy questions, you will be able to use your smartcard.

     </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>
            <td> </td>
           <td><p>LDAP Password: </p></td>
            <td> </td>
           <td><input type="password" id="snamepwd" value=""></td>
         </tr>
         </table>
         <p class="bodyText"> Before you can use your smartcard, you will need a password to protect it.</p>
         <table>
         <tr>
           <td><p >Password:</p></td>
           <td><input type="password" id="pintf" name="pintf" value=""></td>
           <td><p >Re-Enter Password:</p></td>
           <td><input type="password" id="reenterpintf" name="reenterpintf" value=""></td>
       </table>
       <br>
       <table width="100%">
         <tr>
           <td align="right">
             <input type="button" id="enrollbtn" name="enrollbtn" value="Enroll My Smartcard"    onClick="DoEnrollCOOLKey();">
           </td>
         </tr>
       </table>
   </body></html>

Future Smart Card Manager Enhancements

Last modified on 29 November 2024