From Fedora Directory Server

Contents 1 Introduction 1.1 Technologies 1.1.1 Supporting Components 2 Platforms 3 Features 4 How to Get ESC 5 Build Instructions 5.1 How to get the source 5.2 Linux 5.2.1 Prerequisites 5.2.2 Steps: 5.3 Mac OS X 5.3.1 Prerequisites 5.3.1.1 Steps: 5.3.1.2 Build TokenD 5.4 Windows 5.4.1 Prerequisites 5.4.1.1 Inno Setup Script 5.5 Steps: 5.6 Build the CSP 5.7 General Build Information 6 Basic Smart Card Manager Usage 7 Launching Smart Card Manager 8 Phone Home 9 Smart Card Auto Enrollment 10 Managing Smart Cards 10.1 Formatting the Smart Card 10.2 Reset Smart Card Password 10.3 Viewing Certificates 10.4 Enrolling Smart Cards 11 Diagnosing Problems 12 Smart Card Manager Configuration 13 Configuration 14 Smart Card Manager Mac TokenD 14.1 Verifying the TokenD Is Working 15 Smart Card Manager File Locations 15.1 Windows 15.2 Linux 15.3 Mac OS X 16 Smart Card Manager XUL, HTML, and Javascript Functionality 17 External Enrollment UI Customization Guide 18 Future Smart Card Manager Enhancements

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:

• The enrollment of supported smart cards supervised by TPS.
• The subsequent management of the cards:
  • Reformat the card back to its original state.
  • Reset the card's password or "PIN" to a new value.
  • Re-enroll the card if appropriate.
  • Display information about the card itself including any embedded digital certificates.

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:

• The Certificate Authority (CA), which creates, renews, and revokes certificates.
• The Data Recovery Manager (DRM), which archives and recovers keys.
• The Online Certificate Status Manager, which stores lists of revoked certificates for client applications to use to check if a certificate is valid.
• The Token Processing System (TPS), which interacts with smart cards to generate and store keys and certificates for a specific user.
• The Token Key Service (TKS), which generates and stores master keys used by the TPS.

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:

• Supports Visa Open Platform-compliant smart cards like Axalto Cyberflex egate 32k tokens.
• Enrolls security tokens so they are recognized by TPS.
• Maintains the security token, such as re-enrolling a token with TPS.
• Provides information about the current status of the token or tokens being managed.
• Supports server-side key generation so that keys can be archived and recovered on a separate token if a token is lost.

Technologies

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

• Smart Card Manager is a Xulrunner application with the majority of the UI coded in the XUL language. There is also support for externally served HTML UI deployed for the function of enrolling a smart card.
• Smart Card Manager currently relies upon a privately deployed Xulrunner framework on all three platforms.
• The application makes use of a native XPCOM component written in C++ that performs many of the low level smart card related functions such as enrolling the card and querying the card for specific card information. The following Mozilla document provides more information into XPCOM development Creating XPCOM Components
• High level program logic is controlled by scripts written in Javascript that control the UI while calling down into scriptable portions of the XPCOM component responsible for low level operations.
• A small set of XPCOM components have been written per platform to assist in providing any useful tray icon functionality.
• Some tricky processing is done to allow low level XPCOM native code to send messages up to the Javascript/XUL layer of the application.
• The application communicates with the TPS server system through the use of persistent HTTP connection using the Transfer Chunked Encoding format. This format allows the application to perform operations such at enrollment by routing messages between itself, the card, and the TPS server. During these operations, Smart Card Manager merely acts as a conduit of through which TPS communicates with the card.
• The application has the ability to kick off various card operations with TPS, but for the rest of the transaction, TPS supervises what is done to the card and what is written to the card.

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:

• Xulrunner- The Mozilla application environment allows the application to run using Mozilla XUL UI technology as well as leverage a wide range of XPCOM services built into the Mozilla platform.
• CoolKey - The applications depends upon the CoolKey PKCS #11 module for many of the low level smart card operations such as:
  • Detection of smart card insertion and deletion events.
  • Retrieval of important low level information from the card such as certificate information and cryptographic key material information.
• PCSC-Lite - This daemon on Linux and the Mac and built into Windows provides low level card functionality to CoolKey itself.
  • On Linux this daemon is shipped with the Base OS.
  • On Windows PCSC is built in to the system.
  • On the Mac, Apple maintains their own distribution of the PCSC daemon as part of the OS.
• IFD-EGATE - This driver , which is installed on all three platforms, is a plug-in module to PCSC-Lite that allows PCSC to interact with our specific type of Cyberflex smart cards.
• LIB-USB - IFD-EGATE depends upon this driver for USB functionality.
• Mac Specific Components
  • 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.
• Windows Specific Components
  • Windows Cryptographic Service Provider - 4.3. Windows Cryptographic Service Provider
    • The Windows version of the Smart Card Manager 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). CAPI allows Windows-based applications, such as the Windows-version of the Smart Card Manager, to be developed to perform secure, cryptographic functions. This API, also known as CryptoAPI, provides a layer between an application which supports it, such as Certificate System, and the details of the cryptographic services provided by the API.
    • The CAPI interface can be used to create custom CSP libraries. In Certificate System, custom CSP libraries have been created to use the Certificate System-supported smart cards.
    • The CAPI store is a repository controlled by Windows that 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.
    • The Certificate System CSP is designed to provide cryptographic functions on behalf of Windows using our supported smart cards. The Windows CSP performs its requested cryptographic functionality by calling the Certificate System PKCS #11 module.
    • The Certificate System CSP, which has been signed by Microsoft, provides the following features:
      • Allows the user to send and receive encrypted and signed emails with Microsoft Outlook.
      • Allows the user to visit SSL-protected websites with Microsoft Internet Explorer.
      • Allows the user to use smart cards with certain VPN clients, which provides secure access to protected networks.
    • The required CSP libraries are automatically installed with the Smart Card Manager. There are several common situations when a Windows user interacts directly with the CSP.
      • When a smart card is enrolled with the Smart Card Manager, 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 using applications like Outlook or Internet Explorer, the user may be prompted to enter the smart card's password. This is required when the smart card is asked to perform protected cryptographic operations such as creating digital signatures.

Platforms

Smart Card Manager runs on the following platforms:

• Fedora- Latest versions
• Windows -XP
• Has been observed running on Win2000 and Vista.
• Mac OS X 10.4x

Features

Smart Card Manager brings the following set of features:

• The Phone Home feature defines the token issuer name, TPS server, and TPS end-entities interface URL without requiring any user configuration.
• Smart Card Manager has diagnostic logging that records common access and events and records potential errors such as interruptions with the connection between the Smart Card Manager and the TPS server.
• The Smart Card Manager user interface incorporates Mozilla XULRunner technology. XULRunner is a runtime package which hosts standalone applications based on XUL, an XML markup language with a rich feature set for user interfaces. XUL has the following advantages over HTML for applications:
  • XUL provides a wide UI widget set and greater control over the presentation.
  • XUL markup is local to the client machine, so it has a greater privilege level than HTML.
  • XUL also uses Javascript as the scripting language for convenient program logic scripting.
  • XUL Javascript code can make use of the array of Mozilla functionality by using their XPCOM technology.
• The Mac Smart Card Manager can make use of the CoolKey a smart card-specific TokenD 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:
  • The Mac Keychain Access utility can be used to view the certificates and keys on Certificate System tokens.
  • The Apple Mail client can be used to view signed and encrypted emails using Certificate System tokens.
  • The Apple Safari browser can use Certificate System tokens to log onto secure SSL web sites.

How to Get ESC

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

• Fedora 6 and 7
  • ESC is built in and ready to run on these systems.
• Fedora 8
  • ESC is part of Fedora 8 in the Extras group. To get ESC simply as root:

 yum install esc

• Windows XP
  • Windows installer

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 co -d :pserver:anonymous@cvs.fedora.redhat.com/cvs/dirsec 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:

• Make sure the prerequisites are satisfied on the system.
• Check out the code from CVS.
• cd esc/rpm
• ./build.sh
• The result raw ESC is placed in BUILD/esc-1.0.1/esc/dist/<kernel>_glibc_PTH_OPT.OBJ/esc_build/esc
• The rebuilt RPM will be in the RPMS directory.
• The rebuilt Source RPM will be in the SRPMS directory.

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

• Mac OS X 10.4.x, Intel or Mac.
• Building Smart Card Manager on the cat requires once again that Mozilla can be built.

• Simple (relatively) instructions for getting Mozilla to build on OS X Tiger can be found

here: OS X Mozilla Build Prerequisites

• When satisfying the Mozilla requirements make sure to install both Fink and MacPorts package management systems as directed or the build will not complete.

• XCode 2.2 and greater, 2.2 and 2.3 have been tested.

• RPM for OS X is helpful in building one of the sub components find it here: http://rpm4darwin.sourceforge.net/

Steps:

• Check out the source code from CVS.
• cd esc/mac
• Either build as root or insert the following in the sudoers file:
  • username ALL = NOPASSWD: /usr/sbin/gcc_select
  • username ALL = NOPASSWD: /usr/sbin/chown
  • username ALL = NOPASSWD: /bin/chmod
• Set the optional environment variable containing the path to the TokenD component. The script is expecting $TOKEND_PATH_NAME=<path>/COOLKEY.zip.
• ./mac-build.sh

 Note the building of the Xulrunner portion will take quite some time since Mozilla essentially builds xulrunner twice, once for PPC and once for i386.

• The output Smart Card Manager bundle will be in:

 ./esc/dist/Darwin<kernel>_OPT.OBJ/esc_build/ESC.app

• If the installer completes it will be in:

 SmartCardManager-<version>.OSX4.darwin.dmg which contains:
 SmartCardManager-<version>.pkg

• The build script does the following:
  • Builds the libusb library.
  • Builds the egate driver.
  • Builds the CoolKeyPKCS#11 module.
  • Builds Smart Card Manager itself.
  • Obtains the TokenD data, if TOKEND_PATH_NAME is set.
  • Builds the Mac installer bundle.
• The build script can be re-run to build only a specific component:

 ./mac-build.sh [ -do Usb || -doEgate || -DoESC || -doCoolKey || -doTokenD || -doInstaller]

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:

• Have a PPC mac available for this, building on an Intel is problematic.
• Make sure XCode is installed
• Obtain and use Subversion to get a recent build of darwinbuild from MacOSForge.org:
• Subversion packages for the mac are readily available on the net.

 % svn checkout http://svn.macosforge.org/repository/darwinbuild/trunk/
 % cd trunk
 % make
 % sudo make install 

• The above will install darwinbuild under /usr/local/bin/darwinbuild
• To change the intallation tree simply do:

 %sudo make install DESTDIR=<alternate_path>

• To install it under <alternate_path>/usr/local/bin/darwinbuild
• Create a disk image where darwinbuild will build everything

 hdiutil create -size 8g -type SPARSE -fs HFSX -volname Builds -uid 0 -gid 0 -attach Builds.dmg

• Once the image is created double click on it to mount it. This will have to be done each time the machine is booted. Also note, that successive builds of darwinbuild projects can eventually fill this Volume with data. It is a simple matter to remove old builds in an effort to make room for new ones.
• cd /Volumes/Builds
• mkdir Build8P2137 : cd Build8P1237
• /usr/local/bin/darwinbuild -init 8P1237 , this sets up the darwinbuild build area for building darwinbuild projects.
• The setup done above results in a self contained build environment consisting of a subset of the XCode build tools and libraries that already exist on the target machine. When actual darwinbuild builds are attempted, the darwinbuild script will create a chroot world used to build the requested projects.
• Attempt to build the stock apple Tokend project:
  • /usr/local/bin/darwinbuild Tokend
  • This should take awhile and if everything works out ok the stock Apple TokenD's should be built.
  • The output for the stock TokenD's should be under BuildRoot/private/var/tmp/Tokend/Tokend-30557.root/System/Library/security/tokend
  • If the initial build sequence fails, it often can be the result of some needed library or command line tool that was not copied correctly into the local darwinbuild build chroot environment. The error condition is usually printed clearly on the screen. This information can be used to determine which tool or library is missing from the darwinbuild environment. For instance, the error may state the the "tar" utility could not be found. This kind of error can be fixed by taking the "tar" utility from the actual system and placing into the darwinbuild area.

Ex:

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

• This test build of the stock TokenD system will result in the following:
  • The builds for the CAC and BELPIC tokend's. Each tokenD is designed for a particular type of smart card.
  • The file ...Build8P1237/Sources/Tokend-30557.tar.gz which represents a source bundle for Apple's stock TokenD project. If modifications to the stock TokenD are desired simply unpack that tar.gz file into a directory called "Tokend-30557".
  • This allows the developer to modify the source and rebuild the TokenD using the method above.

• The following is how to build the COOLKEY tokenD from source.
  • Now take the CoolKey TokenD code from the directory esc/mac/Tokend-30557 and transport it here:

/Volumes/Builds/Build8P1237/Sources/Tokend-30557

• Attempt another build of TokenD

 /usr/local/bin/darwinbiuld Tokend

• At this point the CoolKey TokenD should only be built.
• Darwinbuild places the results of the latest build here:

 Build8C46/BuildRoot/provate/var/tmp/Tokend/Tokend-11.root/System/Library/Security/tokend/COOLKEY.tokend, a directory bundle

 The subdirectory /System/Library/Security/tokend is the actual destination on the system a TokenD lives once installed.

 If the SmartCardManager installer is built with the optional TokenD, the installer will install the TokenD in the proper location.
 Also a symbolic link to the CoolKey library is make from the directory "/Library/Application Support/CoolKey/PKCS11".
 This link is needed to allow TokenD the access to the CoolKey PKCS#11 module that it requires for operation.

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.

• Windows XP or Windows 2000 works
• MSVC 7.1 has been tested.
• Cygwin- This is discussed in the Mozilla building instructions below:

• The prerequisites for building Mozilla are listed here: [(http://developer.mozilla.org/en/docs/Windows_Build_Prerequisites_on_the_1.7_and_1.8_Branches) Windows Mozilla Prerequisites]

• The build process for Smart Card Manager also builds the CoolKey component. Prerequisites for CoolKey on Windows are located here (http://www.directory.fedora.redhat.com/wiki/BuildCoolKey)

• The INNO setup up installer is required if the build process is to create an installer for Smart Card Manager. This software can be found here: INNO Setup We have tested with INNO Setup 5. If no installer is desired this one is optional.

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:

• Make sure the prerequisites for building Mozilla on Windows are satisfied.
• Check out the source code from CVS.
• cd esc/win32
• Set up the following optional environment variables:
  • CAPI_PATH - This is a directory containing a signed Fedora CAPI CSP, containing the files:
    • clkcsp.dll clkcsp.sig cspres.dll
    • Ex: set CAPI_PATH=c:/CSP
  • MSVC_PATH - This is a directory containing the MFC dlls needed to run the application:
    • atl71.dll mfc71.dll msvcp71.dll msvcr71.dll
  • INNO_SETUP_PATH - This is the path to the optional INNO setup compiler. Ex: c:/"Program Files/Inno Setup 5"
• ./build.sh

The build script does the following:

• Builds NSS simply to provide NSS libraries for CoolKey to link against
• Obtains the optional CoolKey CSP files
• Obtains the egate drivers
• Obtains the zlib compression library
• Builds the CoolKey PKCS#11 module
• Builds Smart Card Manager itself
• If the above environment variables have been set correctly, attempt to build the optional installer executable.
• The output is placed in esc/dist/WIN<version>/esc_build/ESC
• The build script can be re-run with certain arguments to re-create single steps of the build process:

 ./build.sh [ -doEsc || -doCoolKey || -doNSS || -doInstaller ]

• -doEsc will rebuild the Smart Card Manager, -doCoolKey will rebuild CoolKey , and -doInstaller will re-generate the installer, useful for quick changes to the install script.

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 following major directories are present:
  • esc/src/lib - Contains low level libraries for CoolKey, Http Communication, and Linux tray icon functionality.
  • esc/src/app/xpcom - Contains the XPCOM components for Smart Card Manager itself and platform specific tray icon functionality.
  • esc/src/app/daemon - Contains the smart card daemon, which on Linux only detects key insertions without having the full application running.
  • esc/src/app/xul - Contains the XUL and Javascript code for Smart Card Manager. Also, it contains global preferences as well as the bundled strings for the application.

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

• The Smart Card Manager's initial build invocation builds Xulrunner. After Xulrunner has been built, this step does not have to be repeated.
• The rebuild can be done as follows:
  • cd <build_path>/esc
  • make BUILD_OPT=1 ESC_VERSION=$ESC_VERSION CKY_INCLUDE=-I$COOLKEY_PATH/include CKY_LIB_LDD=-L$COOLKEY_PATH/lib
    • ESC_VERSION controls what is shown in the diagnostics information window for version information.
    • CKY_INCLUDE is a simple variable that points to the include directory of a CoolKey build which is needed on Mac and Windows. Linux installs these headers in well known locations with the CoolKey devel package.
    • CKY_LIB_LDD is a simple variable that points to the CoolKey libraries themselves useful on Mac and Windows.
  • make clean at the top level cleans everything, except Xulrunner.
  • If changes only to the XUL markup is done a rebuild can be done as follows:
    • cd <build_path>/esc/src/app/xpcom
    • make clean
    • make BUILD_OPT=1 ESC_VERSION=$ESC_VERSION CKY_INCLUDE=-I$COOLKEY_PATH/include CKY_LIB_LDD=-L$COOLKEY_PATH/lib

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

• On Linux , launch Smart Card Manager by typing esc at the command prompt; this brings up the Smart Card Manager daemon process, which silently watches for inserted smart cards. The client can also be launched by selecting System Settings, then Smart Card Manager, from the system menu.
• On Windows, Smart Card Manager is launched from the desktop or the start menu; Smart Card Manager is also configured to launch on reboot.
• On Mac OS X, Smart Card Manager is launched by double-clicking the Smart Card Manager icon wherever the application was installed. Currently the installation procedure places Smart Card Manager in the "/Applications" folder.

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 preferred method is that the information is burned onto the token at the factory. When the tokens are ordered from the manufacturer, the company should also supply detailed information on how the tokens should be configured when shipped.
• If tokens are blank, the company IT department can supply the information when formating small groups of tokens.

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

• The TPS server and port. For example:

"esc.key.40900062ff020000ba87.tps.url" =
 "http://tps.example.com:12443//nk_service"

• The TPS enrollment interface URL. For example:

"esc.key.40900062ff020000ba87.tps.url" =
 "http://tps.example.com:12443/cgi_bin/esc.cgi?"

• The issuing company name or ID. For example:

"esc.key.40900062ff020000ba87.issuer.name" = "Example Corp"

• The Phone Home URL. For example:

"esc.key.40900062ff020000ba87.phone.home.url" =
 "http://tps.example.com:12443/phone_home/phone_home.cgi?"

• Optionally, a default browser URL to access when an enrolled smart card is inserted.

"esc.key.40900062ff020000ba87.EnrolledTokenBrowserURL" =
"http://www.test.example.com"

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 ## TPS server URL
        </Operation>

        <UI>http://tps.example.com:12443/cgi_bin/esc.cgi   ## Optional
Enrollment UI
        </UI>
        <EnrolledTokenBrowserURL>http://www.test.url.com   ## Optional
enrolled token url
        </EnrolledTokenBrowserURL%gt;
    </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.

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.

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.

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.

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: