Windows Inbox Smart Card Minidriver

Beginning with Windows 7 with Service Pack 1 (SP1), an inbox generic class minidriver is provided that supports PIV-compliant smart cards and cards that implement the GIDS card edge.

PIV-compliant smart cards and cards that implement the GIDS card edge. For more information about PIV, see the About Personal Identity Verification (PIV) of Federal Employees and Contractors web page.

For more information about GIDS, see the Generic Identity Device Specification web page.

When a smart card is inserted into the reader and the Base CSP/KSP calls CardAcquireContext, the class minidriver performs the following discovery process to mark the associated card as either PIV- or GIDS-compliant:

  1. A SELECT command is issued to locate the PIV AID. If the command succeeds, Windows considers the card to be a PIV device and the discovery process stops.
  2. If the command fails, a SELECT command is issued to locate the GIDS AID. If the command succeeds, Windows considers the card to be an GIDS device and the discovery process stops.
  3. If the command fails with a status code that indicates neither AID exists on the smart card, Windows still proceeds as if the card is an GIDS device. If the command fails with any other error, Windows considers the card to be an unknown device.

Electrical Profile for GIDS cards with the Microsoft Generic Profile

For Smart Cards that implement the GIDS card edge, they must be pre-provisioned with an electrical profile that enables them for provisioning with the inbox class minidriver. The information in this section requires deep understanding of APDUs, data model and the card edge as specified in the GIDS specification.

The subsections given here must be followed in the order listed before the card can be used for personalization. Please refer to section 11 of the GIDS specification for more information on APDUs referenced in this section.

GIDS Application Metadata

The DOs described in this section are managed by GIDS and can be retrieved only in the response data field of the SELECT command. This metadata can only be created when the application is in the “creation” state. Please refer to section 6 of the GIDS specification for more information on the GIDS Life Cycle Management.

Note that the metadata provided below only include what is required to be present exactly as described (unless otherwise noted). There are other fields that may be optional, or are customizable by the card application vendor.

File Control Information (DF FCI)

TagLenValue
64Var.

Application Template Data Object

Tag

4F

Len

Var.

Value

Application AID =

A0 00 00 03 97 42 54 46 59 xx yy

  • XX = GIDS specification revision number that is either 01 or 02.
  • YY = Reserved for the card application.

 

File Management Data (DF FMD)

TagLenValue
64Var.

FMD Template

Tag

5F2F

Len

Var.

Value

PIN usage policy (see “PIN Usage Policy”) =

Either 40 or 60

  • 40 – Application PIN is present and may be used to satisfy CHV.
  • 60 – Application and Global PINs are both present and may be used to satisfy CHV.

 

File Control Parameters (DF FCP)

TagLenValue
62Var.

FCP Template

Tag

82

Len

01

Value

File descriptor byte: 38 (“not shareable-DF”)

Tag

8C

Len

03

Value

Security attribute in compact format =

03 30 30

  • 40 – Following bytes specify requirements for CREATE FILE for EFs and DELETE FILE for EFs (and in that order).
  • 60 – User Authentication OR External Authentication satisfy requirements to create EFs.
  • 60 – User Authentication OR External Authentication satisfy requirements to delete EFs.
Note  The security attribute does not have to exactly match this, but allowing User Authentication OR External Authentication to both create and delete EFs is required.

 

Once the DF FCP has been created, the card shall transition to the “initialization” state, which is the state required for creating the objects listed in the following sections.

PIN Creation

To create a PIN, a CHANGE REFERENCE DATA APDU for the application password must be sent to the card:

CLA00
INS24
P101
P280
LcLength of command data field
Data Field<password>
LeAbsent

 

For example, to set the PIN to 12345678, the following APDU must be sent to the card:

00 24 01 80 08 31 32 33 34 35 36 37 38

Pin Unblock Key (PUK) Creation

A PUK is used to unblock and/or reset the PIN in the cases where the card becomes blocked or the PIN is forgotten. If admin key challenge/response is to be used instead, DO NOT create a PUK.

To create a PUK, a CHANGE REFERENCE DATA APDU for the application resetting password must be sent to the card:

CLA00
INS24
P101
P281
LcLength of command data field
Data Field<password>
LeAbsent

 

For example, to set the PUK to 12345678, the following APDU must be sent to the card:

00 24 01 81 08 31 32 33 34 35 36 37 38

ACL Creation

ACLs must be created using the CREATE FILE APDU:

CLA00
INSE0
P1-P200 00
LcLength of data field
Data FieldFCP template for EF
LeAbsent

 

The ACLs mentioned in the table below must be created. Each ACL creation APDU must be followed by ActivateFile APDU (00 44 00 00 00)

ACLAPDU
UserCreateDeleteDirAc 00 E0 00 00 0E 62 0C 82 01 39 83 02 A0 00 8C 03 03 30 00
EveryoneReadUserWriteAc00 E0 00 00 0E 62 0C 82 01 39 83 02 A0 10 8C 03 03 30 00
UserWriteExecuteAc00 E0 00 00 0E 62 0C 82 01 39 83 02 A0 11 8C 03 03 30 FF
EveryoneReadAdminWriteAc00 E0 00 00 0E 62 0C 82 01 39 83 02 A0 12 8C 03 03 20 00
UserReadWriteAc00 E0 00 00 0E 62 0C 82 01 39 83 02 A0 13 8C 03 03 30 30
AdminReadWriteAc00 E0 00 00 0E 62 0C 82 01 39 83 02 A0 14 8C 03 03 20 20

 

Create EF for Admin Key

EF for Admin key must be created using the CREATE FILE APDU:

CLA00
INSE0
P1-P200 00
LcLength of data field
Data FieldFCP template for EF (EFID = B080 and KeyID=80)
LeAbsent

 

The following APDU must be sent to the card to create the EF for a Triple-DES three-key Admin Key:

00 E0 00 00 1C 62 1A 82 01 18 83 02 B0 80 8C 04 87 00 20 FF A5 0B A4 09 80 01 02 83 01 80 95 01 C0

The command mentioned above must be followed by an ActivateFile APDU:

00 44 00 00 00

Inject Admin Key

The Admin Key must be injected onto the card using the PUT KEY APDU:

CLA00
INSDB
P1-P23F FF
LcLength of data field
Data FieldKey Usage Template
LeAbsent

 

The following APDU must be sent to the card to inject the Admin key into KeyID 80:

00 DB 3F FF 26 70 24 84 01 80 A5 1F 87 18 01 02 03 04 05 06 07 08 01 02 03 04 05 06 07 08 01 02
03 04 05 06 07 08 88 03 B0 73 DC

In the example mentioned above injects the admin key with the following value:

01 02 03 04 05 06 07 08 01 02 03 04 05 06 07 08 01 02 03 04 05 06 07 08

Set Operational State

To transition the card from the “initialization” state to the “operational” state, a SELECT DF with EFID followed an ACTIVATE FILE command needs to be sent to the card.

First, send a SELECT APDU for the DF:

CLA00
INSA4
P1-P200 0C
Lc02
Data Field3F FF
LeAbsent

 

Secondly, use the ACTIVATE FILE APDU to change the state of the DF to “operational”:

CLA00
INS44
P1-P200 00
Lc00
Data FieldAbsent
LeAbsent

 

The following APDU must be sent to the card to bring it to operational state:

00 A4 00 0C 02 3F FF
00 44 00 00 00

After this step, the card is ready for placing the file system as described in file system specification section and is considered a “blank card”. Follow the steps for card “creation” to place the filesystem on the card using the minidriver API. Alternatively, follow the steps in the next section to place the filesystem on the card using APDUs.

Data objects on a GIDS card after the filesystem is created

For cards compliant with GIDS specification with Microsoft Generic Profile, the following table describes the data objects and their corresponding EFIDs after the mandatory objects are created as per the section on card “creation”. Place each of the data objects from the table below onto the card using the PUT DATA APDU as specified in the GIDS specification if the minidriver API is not being used for creating the filesystem.

EFIDDO TagContentsFriendly Name
A000DF1F
01 6d 73 63 70 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 a0 00 00 00 00 00
00 00 00 00 00 00 63 61 72 64 69 64 00 00 00 00
00 20 df 00 00 12 a0 00 00 00 00 00 00 00 00 00
00 00 63 61 72 64 61 70 70 73 00 00 00 21 df 00
00 10 a0 00 00 00 00 00 00 00 00 00 00 00 63 61
72 64 63 66 00 00 00 00 00 22 df 00 00 10 a0 00
00 6d 73 63 70 00 00 00 00 00 63 6d 61 70 66 69
6c 65 00 00 00 23 df 00 00 10 a0 00 00
Master file system table
A010DF21
6d 73 63 70 00 00 00 00
\cardapps
A010DF22
00 00 00 00 00 00
\cardcf
A010DF23
<empty 0-byte data object>
mscp\cmapfile
A012DF20
<random 16-byte value>
\cardid

 

INF Sample to re-brand inbox class minidriver

Smart card vendors can use the inbox minidriver without the need to ship a driver package. To add branding information to the Plug and Play experience for such cards, vendors can provide INF files that override various strings to provide branding information. These strings include the following:

  • ProviderName
  • CardDeviceName
  • SmartCardName

The following is a sample INF file that can be used with the inbox minidriver. This INF file is decorated for installation in x86 and amd64 CPU platforms.

;
;FabrikamVendor Smartcard Minidriver for an x86 and x64 based package.
;

[Version]
Signature="$Windows NT$"
Class=SmartCard
ClassGuid={990A2BD7-E738-46c7-B26F-1CF8FB9F1391}
Provider=%ProviderName%
CatalogFile=delta.cat
DriverVer=10/03/2009,10.0.0.1

[Manufacturer]
%ProviderName%=Minidriver,NTamd64,NTamd64.6.1,NTx86,NTx86.6.1

[Minidriver.NTamd64]
%CardDeviceName%=Minidriver64_Install,SCFILTER\CID_51FF0800

[Minidriver.NTx86]
%CardDeviceName%=Minidriver32_Install,SCFILTER\CID_51FF0800

[Minidriver.NTamd64.6.1]
%CardDeviceName%=Minidriver64_61_Install,SCFILTER\CID_51FF0800

[Minidriver.NTx86.6.1]
%CardDeviceName%=Minidriver32_61_Install,SCFILTER\CID_51FF0800

[DefaultInstall]
CopyFiles=x86_CopyFiles
AddReg=AddRegDefault

[DefaultInstall.ntamd64]
CopyFiles=amd64_CopyFiles
CopyFiles=wow64_CopyFiles
AddReg=AddRegWOW64
AddReg=AddRegDefault

[DefaultInstall.NTx86]
CopyFiles=x86_CopyFiles
AddReg=AddRegDefault

[DefaultInstall.ntamd64.6.1]
AddReg=AddRegWOW64
AddReg=AddRegDefault

[DefaultInstall.NTx86.6.1]
AddReg=AddRegDefault

[SourceDisksFiles]
msclmd64.dll=1
msclmd.dll=1

[SourceDisksNames]
1 = %MediaDescription%

[Minidriver64_Install.NT]
CopyFiles=amd64_CopyFiles
CopyFiles=wow64_CopyFiles
AddReg=AddRegWOW64
AddReg=AddRegDefault

[Minidriver64_61_Install.NT]
AddReg=AddRegWOW64
AddReg=AddRegDefault
Include=umpass.inf
Needs=UmPass

[Minidriver32_Install.NT]
CopyFiles=x86_CopyFiles
AddReg=AddRegDefault

[Minidriver32_61_Install.NT]
AddReg=AddRegDefault
Include=umpass.inf
Needs=UmPass

[Minidriver64_61_Install.NT.Services]
Include=umpass.inf
Needs=UmPass.Services

[Minidriver32_61_Install.NT.Services]
Include=umpass.inf
Needs=UmPass.Services


[Minidriver64_61_Install.NT.HW]
Include=umpass.inf
Needs=UmPass.HW

[Minidriver64_61_Install.NT.CoInstallers]
Include=umpass.inf
Needs=UmPass.CoInstallers


[Minidriver64_61_Install.NT.Interfaces]
Include=umpass.inf
Needs=UmPass.Interfaces


[Minidriver32_61_Install.NT.HW]
Include=umpass.inf
Needs=UmPass.HW

[Minidriver32_61_Install.NT.CoInstallers]
Include=umpass.inf
Needs=UmPass.CoInstallers


[Minidriver32_61_Install.NT.Interfaces]
Include=umpass.inf
Needs=UmPass.Interfaces


[amd64_CopyFiles]
msclmd.dll,msclmd64.dll

[x86_CopyFiles]
msclmd.dll

[wow64_CopyFiles]
msclmd.dll

[AddRegWOW64]
HKLM, %SmartCardNameWOW64%,"ATR",0x00000001,3b,04,51,ff,08,00
HKLM, %SmartCardNameWOW64%,"ATRMask",0x00000001,ff,ff,ff,ff,ff,ff
HKLM, %SmartCardNameWOW64%,"Crypto Provider",0x00000000,"Microsoft Base Smart Card Crypto Provider"
HKLM, %SmartCardNameWOW64%,"Smart Card Key Storage Provider",0x00000000,"Microsoft Smart Card Key Storage Provider"
HKLM, %SmartCardNameWOW64%,"80000001",0x00000000,%SmartCardCardModule%

[AddRegDefault]
HKLM, %SmartCardName%,"ATR",0x00000001,3b,04,51,ff,08,00
HKLM, %SmartCardName%,"ATRMask",0x00000001,ff,ff,ff,ff,ff,ff
HKLM, %SmartCardName%,"Crypto Provider",0x00000000,"Microsoft Base Smart Card Crypto Provider"
HKLM, %SmartCardName%,"Smart Card Key Storage Provider",0x00000000,"Microsoft Smart Card Key Storage Provider"
HKLM, %SmartCardName%,"80000001",0x00000000,%SmartCardCardModule%

[DestinationDirs]
amd64_CopyFiles=10,system32
x86_CopyFiles=10,system32
wow64_CopyFiles=10,syswow64


; =================== Generic ==================================

[Strings]
ProviderName ="FabrikamVendor"
MediaDescription="FabrikamVendor Smart Card Minidriver Installation Disk"
CardDeviceName="FabrikamVendor Minidriver for Smart Card"
SmartCardName="SOFTWARE\Microsoft\Cryptography\Calais\SmartCards\Fabrikam"
SmartCardNameWOW64="SOFTWARE\Wow6432Node\Microsoft\Cryptography\Calais\SmartCards\Fabrikam"
SmartCardCardModule="msclmd.dll"


The following are required for this type of INF file:

  • The hardware ID that is specified by the %FabrikamCardDeviceName% string must either be the ATR historical bytes of the device or the decoded value of the device’s smart card framework identifier. For more information about this identifier, see the “Windows Smart Card Framework Card Identifier” section in Discovery Process.
  • The DefaultInstall section is mandatory in INF files for smart card minidriver packages.
  • The DriverVer directive in the INF file must have a value that is greater than the version and timestamp value in the inbox driver’s INF file. Otherwise, the system does not install the device by using the vendor’s INF file.

    The DriverVer directive has the following syntax.

    DriverVer=mm/dd/yyyy[,w.x.y.z]
    

    We recommend that you follow these guidelines when setting the value for the DriverVer directive:

    • Specify a date value that is far enough into the future so as to avoid conflicts with Windows service pack updates.
    • Although the 4-digit version number is optional, you must specify a version that is significantly higher than the current version that is specified in the inbox driver’s INF file.

For more information on INF files and syntax, see Device and Driver Installation Design Guide.

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft