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:

• Implementing Smart Card Application Management for the CLM Web Site

• Configuring Smart Card Application Management for HSMs

• Appendix: Sample XML Profile File

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

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

• Create an XML profile file

• Modify other configuration files

• Configure application management for a management policy

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.

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.

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

• Keyset section

• Diversification section

• Inventory section

For a sample, see Sample policyInfo 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.

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.

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.

The inventory returns XML data in the following format:

<cardStatus xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="https://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>

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>

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.)

The actions section includes the following subsections:

• EstablishSecureChannel section

• DiversifyKeys section

• GetStatus section

• DeleteCardObject section

• CreateInstance section

• LoadApplet section

• CloseSecureChannel section

• SendBatch section

For a sample, see Sample actions 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.

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.

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.

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.

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.

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.

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.

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.

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

<apduBatch xmlns="https://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>

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>

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.

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>

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.

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.

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

<cardMap xmlns="https://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>

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.

The following sample shows an HSM configuration file:

<hsmInfo xmlns="https://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>

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

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.

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.

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

<keySetData xmlns="https://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.

<?xml version="1.0" encoding="utf-8" ?>
<cardPersonalization xmlns=https://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>