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).
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
Modify other configuration files
Configure application management for a management policy
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.
Note
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:
Keyset section
Diversification section
Inventory section
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:
|
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="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>
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.)
Important
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:
EstablishSecureChannel section
DiversifyKeys section
GetStatus section
DeleteCardObject section
CreateInstance section
LoadApplet section
CloseSecureChannel section
SendBatch section
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.
|
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.
|
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>
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.
Note
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:
|
cardmanageraid |
Specifies a smart card manager application identifier for a smart card type. |
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>
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:
|
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="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>
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
Log on to CLM as a certificate manager.
On the CLM home page, under Administration, click Manage profile templates.
On the Profile Template Management page, click the profile template that you want to edit.
On the Edit Profile Template page, under Select a view, click the management policy for which you want to configure application management.
Under Workflow: Smart Card Application Management, click Change smart card application management settings.
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.
Important
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="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.
Appendix: Sample XML Profile File
<?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>