Managing Smart Card Applications

Managing Smart Card Applications describes how to use Microsoft® Identity Lifecycle Manager "2" Certificate Management Service (ILM CMS) to manage and configure smart card applications. Smart card applications are applications that are written specifically for use with smart cards. For example, a smart card might have a Java application that maintains a credit balance for buying food at a company cafeteria.

To use smart card application management, you configure ILM CMS at the lifecycle policy level in smart card profile templates. You use the Application Management workflow settings in ILM CMS management policies to configure smart card application management.

The following topics describe, and provide a sample of, the configuration tasks that you must perform to implement smart card application management in ILM CMS:

For detailed instructions on how to use ILM CMS, see Using the ILM CMS Web site (http://go.microsoft.com/fwlink/?LinkId=89761). For a technical overview, see Technical Overview of ILM CMS (http://go.microsoft.com/fwlink/?LinkId=89760).

Implementing Smart Card Application Management for the CLM Web Site

To implement application management for the CLM Web site, you must complete the following tasks:

Create an XML profile file

You must have an XML profile for ILM CMS to use for processing smart card application management in a management policy workflow. You can create a new XML profile or modify a sample XML profile.

noteNote
To reference the sample XML profile in this document, see Appendix: Sample XML Profile File. During installation, ILM CMS installs sample XML profile files at the following location: %ProgramFiles%\Microsoft Certificate Lifecycle Manager\web\Config\Profiles\.

The XML profile has the following sections:

  • policyInfo section

    This section describes keys and key diversification in ILM CMS.

  • Actions section

    This section defines global platform actions that ILM CMS must perform.

  • Diagnostics section

    This section defines tracing information for troubleshooting ILM CMS problems.

policyInfo section

The policyInfo section of the XML profile file describes keys and key diversification. The policyInfo section has the following subsections:

For a sample, see Sample policyInfo section.

keyset section

The keyset section defines a specified key set provider and lists configuration information for that provider. This section is required.

The following excerpt is from a sample XML profile file:

<!--used for establishing secure channel-->
<keyset scVersion="SC01" 
provider="Microsoft.Clm.Ams.GP.HsmKeySetProvider, Microsoft.Clm.Ams" 
initData="lunaHsm.xml.config" />

The following table shows the settings for a key set provider.

 

Setting Description

scVersion

Secure channel protocol version. Currently supported versions are SC01 and SC02.

provider

Fully-qualified, Microsoft .NET assembly name. ILM CMS supports two key set providers:

  • Hardware Security Module (HSM): Microsoft.Clm.Ams.GP.HsmKeySetProvider, Microsoft.Clm.Ams

  • Plaintext: Microsoft.Clm.Ams.GP.FileKeySetProvider, Microsoft.Clm.Ams

initData

Key Set Provider initialization data.

Diversification section

The diversification section defines a specified key diversification provider and lists configuration information for that provider. This section is optional.

The following excerpt is from a sample XML profile file:

<!--used for specifying key diversification-->
<diversification scVersion="SC01" 
provider="Microsoft.Clm.Ams.GP.IndexKeyDiversificationProvider, Microsoft.Clm.Ams" initData="TestDiversificationData.xml.config" />

The following table shows the settings for the diversification section.

 

Setting Description

scVersion

Secure channel protocol version. Supports SC01.

provider

Fully-qualified, Microsoft .NET assembly name. ILM CMS supports the CLM.Ams.GP.IndexKeyDiversificationProvider, Alacris.Ams diversification provider. This file contains diversification information based on the Card Production Life Cycle (CPLC) data index.

initData

Diversification provider initialization data.

Inventory section

The inventory section defines an inventory provider and provides initialization data for that provider. This section is optional.

The following excerpt is from a sample XML profile file:

<!--used for specifying an inventory provider -->
<inventory 
provider="Microsoft.Clm.Ams.DataAccess.FileInventoryProvider, Microsoft.Clm.Ams"
initData="C:\logs\JC_Status.log" />

The following table shows the settings for the inventory section.

 

Setting Description

provider

Fully qualified, Microsoft .NET assembly name. ILM CMS supports the Microsoft.Clm.Ams.DataAccess.FileInventoryProvider, Microsoft.Clm.Ams inventory provider. This file contains the name of the file to receive card status information.

initData

Defines the key set provider initialization data.

The inventory returns XML data in the following format:

<cardStatus xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://microsoft.com/clm/ams/cardStatus.xsd">

<appletInfo type="80" aid="A000000003000000" lifecycles="01" privileges="9E" />

<appletInfo type="40" aid="A000000063504B43532D3135" lifecycles="07" privileges="00" />

<appletInfo type="20" aid="A00000006302" lifecycles="01" privileges="00" />

</cardStatus>

Sample policyInfo section

The following sample shows the policyInfo section of a sample XML profile file:

<policyInfo>

<!--used for establishing secure channel-->
<keyset scVersion="SC01" 
provider="Microsoft.Clm.Ams.GP.HsmKeySetProvider, Microsoft.Clm.Ams" 
initData="lunaHsm.xml.config" />

<!--used for specifying key diversification-->
<diversification scVersion="SC01" 
provider="Microsoft.Clm.Ams.GP.IndexKeyDiversificationProvider, Microsoft.Clm.Ams" initData="TestDiversificationData.xml.config" />

<!--used for specifying an inventory provider -->
<inventory 
provider="Microsoft.Clm.Ams.DataAccess.FileInventoryProvider, Microsoft.Clm.Ams"
initData="C:\logs\JC_Status.log" />

</policyInfo>

Actions section

The actions section of the XML profile file defines the global platform actions that ILM CMS must perform on a smart card. (The XML profile file refers to global platform by the acronym GP.)

ImportantImportant
Because ILM CMS processes the settings in the actions section sequentially, the order of the instructions is important. For example, the first operation that ILM CMS performs should usually be to establish a secure channel. This is an important first step because the subsequent global platform commands rely on a secure channel. Another example is to ensure that ILM CMS performs the application load file operation before instantiation operations.

The actions section includes the following subsections:

For a sample, see Sample actions section.

EstablishSecureChannel section

The EstablishSecureChannel section defines a secure channel between a smart card and ILM CMS. You must use a secure channel to perform most global platform operations. The EstablishSecureChannel section uses the key set configuration that you specify in the policyInfo section of the XLM profile file. The key set configuration contains information about the HSM and what version of the secure channel to use.

The following excerpt is from a sample XML profile file:

<action type="EstablishSecureChannel" status="Establishing secure channel..." level="3"/>

The following table shows the settings for the EstablishSecureChannel section.

 

Setting Description

level

Sets the security level of the secure channel.

DiversifyKeys section

The DiverysifyKeys section uses data from a smart card, such as its serial number, manufacturer ID, and batch ID, to deversify keys. The DiverysifyKeys section requires individual key sets for each smart card, which is a more secure approach to smart card application management than requiring that the smart cards do not have individual keys.

The DiverysifyKeys section uses the key set configuration that you specify in the policyInfo section of the XLM profile file. The key set configuration contains information about the HSM and which version of the secure channel to use.

The following excerpt is from a sample XML profile file:

<action type="DiversifyKeys" status="Diversifying keys..." force="false"/>

The following table shows the settings for the DiversifyKeys section.

 

Setting Description

Force

Defines whether ILM CMS should perform the diversification operation even if the keys are already diversified.

  • True: Perform the diversification operation

  • False: Do not perform the diversification operation

GetStatus section

The GetStatus section queries a smart card for its contents. If you specify an inventory provider in the policyInfo section, ILM CMS writes the data on the smart card in XML format to a location that you specify. The GetStatus section uses the inventory configuration in the policyInfo section of the XML profile file to determine where to store information about the data on the smart card.

The following excerpt is from a sample XML profile file:

<action type="GetStatus" status="Getting card status..."/>

GetStatus has no settings.

DeleteCardObject section

The DeleteCardObject section deletes an instance of an application or an application load file from a smart card.

The following excerpt is from a sample XML profile file:

<action type="DeleteCardObject" aid="A00000006302" status="Deleting applet(s)"/>

The following table shows the settings for the DeleteCardObject section.

 

Settings Description

aid

Specifies the application identification number of the application load file or application instance to delete.

CreateInstance section

The CreateInstance section creates an instance of an application based on a load file. The following excerpt is from a sample XML profile file:

<action type="CreateInstance" loadFileAid="A00000006302" moduleAid="A000000063504B43532D3135" applicationAid="A000000063504B43532D3135" installParameters="4244001600906210C104" instanceSize="11557" status="Creating instance..." />

The following table shows the settings for the CreateInstance section.

 

settings Description

loadFileAid

Specifies the application identification number of the application load file from which to create the instance.

moduleAid

Specifies the application identification number of the module in the application load file to instantiate.

applicationAid

Specifies the application identification number of the application instance.

installParameters

Specifies parameters that ILM CMS passes to the application instance as part of the installation.

instanceSize

Specifies the size of the application instance in decimal form.

LoadApplet section

The LoadApplet section loads an application load file onto a smart card. The file name extension of the application load file is typically .cap, .ijc or .jcf.

The following excerpt is from a sample XML profile file:

<action type="LoadApplet" appletFile="provider-x.jcf" loadFileAid="A00000006302" securityDomain="A000000003000000" status="Loading PKI applet..." />

The following table shows the settings for the LoadApplet section.

 

Settings Description

appletFile

File name of the applet to load.

loadFileAid

Application identification number of the applet load file.

securityDomain

Application identification number of the security domain to receive the load file.

appletFile

File name of the applet to load.

loadFileAid:

Application identification number of the applet load file.

CloseSecureChannel section

The CloseSecureChannel section closes the secure channel that is open between a smart card and ILM CMS.

The following excerpt is from a sample XML profile file:

<action type="CloseSecureChannel" status="Closing secure channel..."/>

CloseSecureChannel has no settings.

SendBatch section

The SendBatch section sends a batch of Application Protocol Data Units (APDUs) to a smart card. You can use the SendBatch section to initialize applications with default values, for example, personal identification numbers (PINs), PIN policies, or the number of key containers. Typically, the APDU batch is specific to the applet set because each set supports different APDUs.

The following excerpt is from a sample XML profile file:

<action type="SendBatch" file="ProviderPostPerso.xml" secure="false" status="Personalizing..."/>

The following table shows the settings for the SendBatch section.

 

Settings Description

File

Specifies the file name and path of the XML profile file that contains the APDUs.

Secure

Specifies whether ILM CMS should send the APDUs over a secure channel established between ILM CMS and a smart card.

  • True: ILM CMS should send the APDUs over a secure channel.

  • False: ILM CMS should not send the APDUs over a secure channel.

The following excerpt shows a sample XML format for an APDU batch file:

<apduBatch xmlns="http://microsoft.com/clm/ams/apduBatch.xsd">

<!--mode: 0 - no input/output, 1 - send, 2 - receive, 3 - send/receive -->

<apdu mode="1" comment="1" expectedSW="9000">0070000001</apdu>

<apdu mode="1" comment="2" expectedSW="6999">01A4000C025031</apdu>

<apdu mode="1" comment="3" expectedSW="9000">82308348070305010302010101</apdu>

</apduBatch>

Sample actions section

The following sample shows the actions section of a sample XML profile file:

<actions>
<!—- Establish secure channel -->
<action type="CloseSecureChannel" status="Please wait..."/>

<action type="EstablishSecureChannel" 
status="Establishing secure channel..." level="3"/>

<!-- remove personalization -->
<action type="DeleteCardObject" 
aid="A000000063504B43532D3135" 
status="Deleting applet instance(s)"/>

<action type="DeleteCardObject" 
aid="A00000006302" 
status="Deleting applet(s)"/>

<!-- load applets -->
<action type="LoadApplet" appletFile="aetjass2-ibmsmx.jcf" 
loadFileAid="A00000006302" securityDomain="A000000003000000" 
status="Loading PKI applet..." />

<!-- instanciate applets -->
<action type="CreateInstance" loadFileAid="A00000006302" 
moduleAid="A000000063504B43532D3135" 
applicationAid="A000000063504B43532D3135" 
installParameters="4244001600906210C104" 
status="Creating instance..." />

<!-- getting status -->
<action type="GetStatus" status="Getting card status..."/>

<!-- sending personalization batch -->
<action type="SendBatch" file="AETPostPerso.xml" 
secure="false" status="Personalizing..."/>

<!-- closing secure channel -->
<action type="CloseSecureChannel" status="Closing secure channel..."/>

</actions>

Diagnostics section

The diagnostics section contains information about tracing. Specifically, the diagnostics section initializes trace listeners, which can write to a log file on the server or to the event log. In addition, the diagnostics section sets log levels for each of the global platform actions that ILM CMS supports.

noteNote
For more information on the global platform actions that ILM CMS supports, see Actions section.

Finally, the diagnostics section limits tracing to certain smart cards, as specified by an answer to reset value (ATR) or the serial number for a smart card.

The following excerpt shows the diagnostics section of a sample XML profile file:

<diagnostics>

<traceListeners>
<listener name="Microsoft.Clm.Ams.TextWriter.Listener1"
type="Microsoft.Clm.Ams.Diagnostics.SimpleTextWriterTraceListener, Microsoft.Clm.Ams" 
initializeData="c:\logs\CLM.Ams.JC.log"/>
</traceListeners>

<switches>
<switch name="EstablishSecureChannel" value="4" />
<switch name="GetStatus" value="4" />
<switch name="DiversifyKeys" value="4" />
<switch name="LoadApplet" value="4" />
<switch name="CreateInstance" value="4" />
<switch name="DeleteCardObject" value="4" />
<switch name="SendBatch" value="4" />
<!-- General will be the "General" trace switch setting for all non-filtered tracing. -->
<switch name="General" value="4" />
</switches>

<filters>
<filter type="ATR" value="3B759400006202020201" />
<filter type="SerialNumber" value="00003FACFF021982" />
<filter type="SerialNumber" value="00004132FF021982" />
</filters>

</diagnostics>

Modify other configuration files

ILM CMS stores all application management files in the Config folder. The default location for this folder on the CLM server is %ProgramFiles%\Microsoft Certificate Lifecycle Manager\Web\Config. When you install ILM CMS, the installation program creates two subfolders in the Config folder. The HSMs folder contains HSM configuration files. The Profiles folder contains profiles that describe global platform actions that ILM CMS must perform.

To implement application management in ILM CMS, you must manually add an Applets subfolder to the Config folder. This subfolder should contain all of the application load files for your smart card applications. Typically, these files have the file name extensions .cap, .ijc, or .jcf.

Smart card mapping configuration file

In addition to the HSM, Profiles, and Applets subfolders, the Config folder also contains the Cardmap.xml.config file, which has information about classes and scripts that ILM CMS uses for different types of smart cards. The file identifies smart cards by their ATRs. You must configure the Cardmap.xml.config file with the values specific to the smart cards that you implement.

The following table shows the settings for the Cardmap.xml.config file.

 

Setting Description

atr

Specifies the ATR for a smart card.

scriptFolder

Specifies where the script files are located for a smart card type.

cardspecificclass

Specifies the global platform class that ILM CMS should use for a smart card type. ILM CMS supports the following types of smart cards:

  • IBM JCop 41: Microsoft.Clm.Ams.Protocol.GP.IbmJcop41, Microsoft.Clm.Ams

  • Gemplus: Microsoft.Clm.Ams.Protocol.GP.Gemplus, Microsoft.Clm.Ams

  • Axalto: Microsoft.Clm.Ams.Protocol.GP.Axalto, Microsoft.Clm.Ams

cardmanageraid

Specifies a smart card manager application identifier for a smart card type.

The following sample shows a Cardmap.xml.config file:

<cardMap xmlns="http://microsoft.com/clm/ams/cardmap.xsd">
<!-- Cyberflex64v2 -->
<card atr="3B959540FFAE01010203" scriptFolder="scripts/cards/axalto/Cyberflex32egate/">
<cardspecificclass>Microsoft.Clm.Ams.Protocol.GP.Axalto, Microsoft.Clm.Ams</cardspecificclass>
<cardmanageraid>A0000000030000</cardmanageraid>
</card>
<!-- GemPlus DESFire v6 64K -->
<cardatr="3B6B00008065B08301037483009000" scriptFolder="scripts/cards/Gemplus/Gemplus/">
<cardspecificclass>Microsoft.Clm.Ams.Protocol.GP.Gemplus, Microsoft.Clm.Ams</cardspecificclass>
<cardmanageraid>A000000018434D</cardmanageraid>
</card>
<!—IBM JCOP 41 -->
<card atr="3BF91800008131FE454A434F503431563232AF" scriptFolder="scripts/cards/aet/aet/">
<cardspecificclass>Microsoft.Clm.Ams.Protocol.GP.IbmJcop41, Microsoft.Clm.Ams</cardspecificclass>
<cardmanageraid>A0000000030000</cardmanageraid>
</card>
</cardMap>

HSM configuration files

ILM CMS stores all configuration data for HSMs that are implemented with application management in the HSMs folder. The default location for this folder is %ProgramFiles%\Microsoft Certificate Lifecycle Manager\Web\Config\HSMs.

The HSMs folder contains configuration files for specific HSMs. An HSM configuration file should contain the PKCS#11 library path, HSM passwords, and information on which keys to use for the cryptographic operations.

The following table shows the settings for HSMs.

 

Setting Description

p11LibraryInfo path

Specifies the path to the PKCS#11 library.

slotID

Specifies the slot ID to use in the HSM.

password

Specifies the password or the location of the password in an encrypted registry key.

keySetClass

Specifies the HSM cryptographic key set class by its fully-qualified, Microsoft .NET assembly name. ILM CMS supports the following classes:

  • SafeNet Luna SA HSM: Microsoft.Clm.Ams.GP.LunaHsm, Microsoft.Clm.Ams

  • nCipher HSM: Microsoft.Clm.Ams.GP.NCipherHsm, Microsoft.Clm.Ams

numberOfSessions

Specifies the number of simultaneous connections that ILM CMS should reserve.

authKey searchType

Specifies search filters for locating key handles in the HSM.

The following sample shows an HSM configuration file:

<hsmInfo xmlns="http://microsoft.com/CLM/ams/hsmInfo.xsd">

<p11LibraryInfo path="C:\nfast_bin\cknfast.dll" slotId="492971158" password="protected:Registry,DPAPI;value:HKLM\Software\Microsoft\CLM\Ams,nCipherPassword" keySetClass="Microsoft.Clm.Ams.GP.NCipherHsm, Microsoft.Clm.Ams" numberOfSessions="10"/>

<keyInfo>

<!-- The only supported search types so far are CkaId and CkaLabel -->

<authKey searchType="CkaLabel" searchFilter="3DES GP Auth Key” />

<macKey searchType="CkaLabel" searchFilter="3DES GP Mac Key" />

<kekKey searchType="CkaLabel" searchFilter="3DES GP Kek Key" />

</keyInfo>

</hsmInfo>

Configure application management for a management policy

After you have created the XML profile file, you must configure smart card application management in the specific management policies for your profile template.

To configure smart card application management

  1. Log on to CLM as a certificate manager.

  2. On the CLM home page, under Administration, click Manage profile templates.

  3. On the Profile Template Management page, click the profile template that you want to edit.

  4. On the Edit Profile Template page, under Select a view, click the management policy for which you want to configure application management.

  5. Under Workflow: Smart Card Application Management, click Change smart card application management settings.

  6. In Application Management, select the Enable personalization check box, type the path for the XML profile file, and then click OK.

Configuring Smart Card Application Management for HSMs

You must configure ILM CMS smart card application management for HSMs. HSMs help protect the private keys for a smart card.

When you test smart card application management, you can implement it either with an HSM or with plaintext keys.

ImportantImportant
You should only use plaintext keys for testing application management.

You must provide plaintext keys in XML profile files using the following format:

<keySetData xmlns="http://microsoft.com/clm/ams/keySetData.xsd">

<keySets>

<keySet atr="3B751200002905010401">

<!--Axalto-->

<authKey>404142434445464748494A4B4C4D4E4F</authKey>

<macKey>404142434445464748494A4B4C4D4E4F</macKey>

<kekKey>404142434445464748494A4B4C4D4E4F</kekKey>

</keySet>

<keySet atr="3BF91800008131FE454A434F503431563232AF">

<!--IBM-->

<authKey>404142434445464748494A4B4C4D4E4F</authKey>

<macKey>404142434445464748494A4B4C4D4E4F</macKey>

<kekKey>404142434445464748494A4B4C4D4E4F</kekKey>

</keySet>

<keySet atr="3B7B9400008065B08301017483009000">

<!--Gemplus-->

<authKey>47454D5850524553534F53414D504C45</authKey>

<macKey>47454D5850524553534F53414D504C45</macKey>

<kekKey>47454D5850524553534F53414D504C45</kekKey>

</keySet>

</keySets>

</keySetData>

You configure whether ILM CMS uses an HSM or a plaintext key file in the policyInfo section of the XML profile file. For information on configuring these files, see policyInfo section.

Appendix: Sample XML Profile File

<?xml version="1.0" encoding="utf-8" ?>
<cardPersonalization xmlns=http://microsoft.com/CLM/ams/CardPersonalization.xsd>

<policyInfo>

<!--used for establishing secure channel-->
<keyset scVersion="SC01" 
provider="Microsoft.Clm.Ams.GP.HsmKeySetProvider, Microsoft.Clm.Ams" 
initData="lunaHsm.xml.config" />

<!--used for specifying key diversification-->
<diversification scVersion="SC01" 
provider="Microsoft.Clm.Ams.GP.IndexKeyDiversificationProvider, Microsoft.Clm.Ams" initData="TestDiversificationData.xml.config" />

<!--used for specifying an inventory provider -->
<inventory 
provider="Microsoft.Clm.Ams.DataAccess.FileInventoryProvider, Microsoft.Clm.Ams"
initData="C:\logs\JC_Status.log" />

</policyInfo>

<actions>
<!-- Establish secure channel -->
<action type="CloseSecureChannel" status="Please wait..."/>

<action type="EstablishSecureChannel" 
status="Establishing secure channel..." level="3"/>

<!-- remove personalization -->
<action type="DeleteCardObject" 
aid="A000000063504B43532D3135" 
status="Deleting applet instance(s)"/>

<action type="DeleteCardObject" 
aid="A00000006302" 
status="Deleting applet(s)"/>

<!-- load applets -->
<action type="LoadApplet" appletFile="aetjass2-ibmsmx.jcf" 
loadFileAid="A00000006302" securityDomain="A000000003000000" 
status="Loading PKI applet..." />

<!-- instanciate applets -->
<action type="CreateInstance" loadFileAid="A00000006302" 
moduleAid="A000000063504B43532D3135" 
applicationAid="A000000063504B43532D3135" 
installParameters="4244001600906210C104" 
status="Creating instance..." />

<!-- getting status -->
<action type="GetStatus" status="Getting card status..."/>

<!-- sending personalization batch -->
<action type="SendBatch" file="AETPostPerso.xml" 
secure="false" status="Personalizing..."/>

<!-- closing secure channel -->
<action type="CloseSecureChannel" status="Closing secure channel..."/>

</actions>

</cardPersonalization>

Community Additions

ADD
Show: