PC/SC Troubleshooting on Windows

Following our PC/SC installation guide on Windows, you’ve installed the appropriate driver, and made sure the “Smart Card” service is running on your Windows computer.
But still, your PC/SC reader doens’t appear on PC/SC Diagnostic.

Please first check in your device manager that your SpringCard PC/SC reader is properly installed (it should appear under Smart Card Reader).

Now, if the drivers are properly installed, the “Smart Card” service is running, but the reader doesn’t show up on the diagnostic tool, the reason must be one of the following :

  1. A third party security-related software or single-login solution takes full control over the PC/SC subsystem
  2. The computer is either running in a virtual machine or in a remote session on a terminal server
  3. Access to PC/SC readers has been disabled by the corporate administrators through a group policy
  4. A driver from one of our competitors has corrupted the registry

For reasons 1 and 2, SpringCard cannot offer any help.

For reason 3 : you should try to run a copy of our PC/SC Diagnostic tool, located on the C: drive, being logged in as Administrator. If this works, your reader is properly installed.

For reason 4, the problem is in the registry permission for LOCAL_SERVICE :
Open the registry editor (“regedit”) :

  1. Right-click on the key HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Cryptography/Calais and select Permissions…
  2. Click Add.
  3. Click Advanced.
  4. Click Locations.
  5. Click on the computer name and click OK.
  6. In the window ‘Select user or groups’, click on Find now.
  7. Select LOCAL SERVICE.
  8. Click OK.
  9. In the window ‘Select user or groups’, click OK.
  10. In the window ‘Permissions for Calais’, click on LOCAL SERVICE and make sure ‘Full control’ , ‘Read’ and ‘special permissions’ are allowed.
  11. In the window “Advance Security Settings for Calais”, deactivate the options “Inherit from parent the permission entries that apply to child objects…”
  12. When the window “Security” appears, click Copy.
  13. In the window “Advance Security Settings for Calais”, activate the option “Replace permission entries on all child objects with entries shown here that apply to child objects” and click OK.
  14. In the window “Security” click Yes
  15. In the window “Permissions for Calais”, click OK.

Restart the computer.

Accessing Reader’s configuration from command line and in batch mode

All SpringCard PC/SC Readers feature a set of Configuration Registers that allow to alter the Reader behaviour to match a particular hardware setup or end-user requirement.

Editing the configuration is easy thanks to MultiConf, the new versatile configuration tool that covers all SpringCard products. But MultiConf is a GUI-application. When it comes to configuring numerous readers at once (with the same settings of course), a command-line tool, suitable to operate in batch mode, could be preferred.

This is typically the aim of pcscconf, a simple command-line utility (targetting Windows systems).

Getting started with pcscconf

Download pcscconf (and its companion tool pcscinfo) (ZIP)

Extract the ZIP archive in the directory of the choice. There are 3 files in the archive:

  • pcscconf.exe, the tool we’ll be using
  • pcscinfo.exe, a software to retrieve all information regarding the connected readers (version, serial numbers, etc)
  • pcsctool.dll, the library that makes both software work.

Open a command-line box in the directory where you’ve extracted the archive, and at the prompt enter

pcscconf

pcscconf-1
pcscconf-2

Reading current configuration

Enter

pcscconf -d

to dump the current configuration.

pcscconf-3

It is also possible to enter

pcscconf -d <Filename>

to dump the configuration to a file. pcscconf uses the same file format as MultiConf.

If the file already exists, use

pcscconf -df <Filename>

to force the overwrite.

Changing a configuration register

Use syntax

pcscconf -s <RegisterAddress>=<RegisterValue>

 

pcscconf-4

To erase a register (i.e. restore product’s default value), use syntax

pcscconf -s <RegisterAddress>

Applying a new configuration from a file

Use syntax

pcscconf -u <Filename>

to upload the configuration from the file into the reader.

There’s no confirmation prompt or ‘Are you sure’ dialog box. Be sure to double-check the content of your file before uploading it into the reader.

pcscconf-5

Do not forget…

Changing a reader’s configuration will change its behaviour! You’re using this software at one risk. Always refer to the reader’s detailed Developer’s Guide or use MultiConf to choose the appropriate values.

Some registers play a special role and are therefore protected before delivery. This is the case of registers C0 and F0 to FF. Trying to write in one of these registers will always fail.

pcscconf targets the SpringCard PC/SC Readers only (and not the RFID Scanners, /RDR family and access control readers, nor the Legacy products).

pcscconf is able to work with only one PC/SC Reader at once. If you run pcscconf with two readers or more connected to your computer, the software will issue a warning and exit.

Using SCardControl under Linux and from a Java program

SCardControl is the PC/SC function that makes it possible for the application to invoke ‘proprietary’ functions, implemented either in the PC/SC reader itself (CSB6Prox’N’Roll PC/SCEasyFinger or CrazyWriter) , or in its driver running on the PC, or in the PC/SC middleware.

The prototype is:

LONG SCardControl(
  SCARDHANDLE hCard,
  DWORD dwControlCode,
  LPCVOID lpInBuffer,
  DWORD nInBufferSize,
  LPVOID lpOutBuffer,
  DWORD nOutBufferSize,
  LPDWORD lpBytesReturned
);

(see http://pcsclite.alioth.debian.org/api/group__API.html for the PCSC-Lite documentation, and http://msdn.microsoft.com/en-us/library/windows/desktop/aa379474%28v=vs.85%29.aspx for Microsoft’s version).

The lpInbuffer / nInBufferSize parameters hold the command buffer that will be processed by either target -reader, driver, or PC/SC middleware-.

SpringCard PC/SC Readers do provide a few ‘proprietary’ functions (called ‘Escape commands’ in the USB CCID specification). For instance, an application would send the command 58 1E 01 00 to switch the reader’s red LED ON. A question remains: what must the value of dwControlCode be, when the application wants to send the command right to the reader, bypassing both the PC/SC middleware and the driver? The answer varies with the operating system, which doesn’t help implementing portable code.

Differences between Windows and PCSC-Lite implementations

Windows

In Microsoft’s CCID driver (http://msdn.microsoft.com/en-us/library/windows/hardware/gg487509.aspx), the dwControlCode for the Escape command is defined as follows:

#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(3500)

SpringCard PC/SC Readers follow the CCID specification. SpringCard’s CCID driver (SDD480) uses the same dwControlCode as Microsoft’s.

Therefore, on Windows, the application would switch the red LED on this way:

#include <windows.h>
#include <winscard.h>

#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(3500)

(...)

const BYTE SET_RED_LED_ON[4] = { 0x58, 0x1E, 0x01, 0x00 };

SCARDCONTEXT hContext;
SCARDHANDLE hCard;
DWORD dwProtocol;
BYTE abResponse[256];
DWORD dwRespLen;
LONG rc;

(...)

/* Instanciate the winscard.dll library */
rc = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &amp;hContext);
if (rc != SCARD_S_SUCCESS) { /* TODO: handle error */ }

/* Get a direct connection to the reader (we don't need a card to send Escape commands) */
rc = SCardConnect(hContext, szReader, SCARD_SHARE_DIRECT, 0, &amp;hCard, &amp;dwProtocol);
if (rc != SCARD_S_SUCCESS) { /* TODO: handle error */ }

/* Send the command */
rc = SCardControl(hCard, IOCTL_CCID_ESCAPE, SET_RED_LED_ON, sizeof(SET_RED_LED_ON), abResponse, sizeof(abResponse), &amp;dwRespLen);
if (rc != SCARD_S_SUCCESS) { /* TODO: handle error */ }

SCardDisconnect(hCard, SCARD_LEAVE_CARD);
SCardReleaseContext(hContext);

 

Important notes:

Working with MS’ CCID driver

With Microsoft’s CCID driver, the Escape feature is disabled by default.

In order to send or receive an Escape command to a reader, the DWORD registry value EscapeCommandEnable must be added and set to a non-zero value under one of the following keys.

  • HKLM\SYSTEM\CCS\Enum\USB\Vid*Pid*\*\Device Parameters (prior to Windows 7).
  • HKLM\SYSTEM\CCS\Enum\USB\Vid*Pid*\*\Device Parameters\WUDFUsbccidDriver (Windows 7 and later).

This is clearly explained in the Developer’s Manual for every PC/SC reader.

Using SpringCard’s SDD480 CCID driver shall be preferred.

Early versions of SDD480

Branch -Ax of SpringCard’s SDD480 CCID driver uses a different value for the dwControlCode parameter.

#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(2048)

Switching to the latest version of SpringCard’s SDD480 CCID driver (branch -Bx and onwards) shall be preferred.

Linux, MacOS and other Unix*

In Ludovic Rousseau’s open-source CCID driver (http://pcsclite.alioth.debian.org/ccid.html), the dwControlCode for the Escape command is defined as follows:

#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(1)

(See http://anonscm.debian.org/viewvc/pcsclite/trunk/Drivers/ccid/SCARDCONTOL.txt?view=markup for details)

Therefore, when working with PCSC-Lite, the application would switch the red LED on this way:

#ifdef __APPLE__
#include <pcsc/winscard.h>
#include <pcsc/wintypes.h>
#else
#include <winscard.h>
#endif

#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(1)

(...)

const BYTE SET_RED_LED_ON[4] = { 0x58, 0x1E, 0x01, 0x00 };

SCARDCONTEXT hContext;
SCARDHANDLE hCard;
DWORD dwProtocol;
BYTE abResponse[256];
DWORD dwRespLen;
LONG rc;

(...)

/* Instanciate the winscard.dll library */
rc = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
if (rc != SCARD_S_SUCCESS) { /* TODO: handle error */ }

/* Get a direct connection to the reader (we don't need a card to send Escape commands) */
rc = SCardConnect(hContext, szReader, SCARD_SHARE_DIRECT, 0, &hCard, &dwProtocol);
if (rc != SCARD_S_SUCCESS) { /* TODO: handle error */ }

/* Send the command */
rc = SCardControl(hCard, IOCTL_CCID_ESCAPE, SET_RED_LED_ON, sizeof(SET_RED_LED_ON), abResponse, sizeof(abResponse), &dwRespLen);
if (rc != SCARD_S_SUCCESS) { /* TODO: handle error */ }

SCardDisconnect(hCard, SCARD_LEAVE_CARD);
SCardReleaseContext(hContext);

Enabling the Escape commands

With this CCID driver, the Escape feature is also disabled by default.

You’ll have to edit the CCID driver’s Info.plist file to enable this feature:

  • Open /usr/local/lib/pcsc/drivers/ccid/Info.plist in edit mode with root priviledge,
  • Locate the line <key>ifdDriverOptions</key>,
  • The following line is typically <string>0000</string>,
  • Define the new value: <string>0001</string>,
  • Save the file and restard pcscd.

(More details on http://ludovicrousseau.blogspot.fr/2011/10/featureccidesccommand.html)

Writing portable code

The idea is only to use a #ifdef to compile the correct value:

#ifdef WIN32
#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(3500)
#else
#define IOCTL_CCID_ESCAPE SCARD_CTL_CODE(1)
#endif

Java

The javax.smartcardio API provides Java methods that are stricly bound to the underlying PC/SC subsystem. The Card.transmitControlCommand method is the wrapper for SCardControl. The prototype is coherent:

public abstract byte[] transmitControlCommand(
  int controlCode,
  byte[] command)
    throws CardException

Now the same question: what must the value of controlCode be? The answer is short: it depends on the PC/SC stack! SCARD_CTL_CODE(3500) for Windows, and SCARD_CTL_CODE(1) for PCSC-Lite. But with another difference: the macro SCARD_CTL_CODE is not computed the same way between both systems!

 

As a consequence, the Java application must detect the OS, and compute the controlCode parameter accordingly.

Same example to switch the red LED on:

import javax.smartcardio.*;

(...)

static boolean isWindows()
{
  String os_name = System.getProperty("os.name").toLowerCase();
  if (os_name.indexOf("windows") > -1) return true;
  return false;
}

static int SCARD_CTL_CODE(int code)
{
  int ioctl;
  if (isWindows())
  {
    ioctl = (0x31 < < 16 | (code) << 2);
  } else
  {
    ioctl = 0x42000000 + (code);
  }
  return ioctl;
}

static int IOCTL_CCID_ESCAPE()
{
  if (isWindows())
  {
    return SCARD_CTL_CODE(3500);
  } else
  {
    return SCARD_CTL_CODE(1);
  }
}

static final byte[] SET_RED_LED_ON = { (byte) 0x58, (byte) 0x1E, (byte) 0x01, (byte) 0x00 };

(...)

String readerName;

/* Note that the reader's name vary with the OS too!!! */
if (isWindows())
  readerName = "SpringCard Prox'N'Roll Contactless 0";
else
  readerName = "SpringCard Prox'N'Roll (00000000) 00 00";

CardTerminal terminal = CardTerminals.getTerminal(readerName);

Card virtualCard = terminal.connect("DIRECT");

virtualCard.transmitControlCommand(IOCTL_CCID_ESCAPE(), SET_RED_LED_ON);

virtualCard.disconnect(false);

Of course this code works only if the Escape feature is enable by the underlying CCID driver, as seen above.

NOTE : Products without SAM nor contact slot (like Prox’N’Roll) could be used with Microsoft’s CCID driver (shipped with Windows or available on Windows Update). Only our driver gives access to the SAM or contact slots of the other products.

Please unplug any PC/SC reader from your computer before starting this procedure.

First, download our driver from our main website:

Then, install the downloaded driver. When executing the installation file sdd480-xx.exe file, if you have a Security Warning pop up, simply click “Run”:

Security Warning – click on “Run”

 

 

 

 

 

 

 

 

The installation of the driver is starting, click on “Next” on the following windows:

Click on “Next”

 

 

 

 

 

 

 

 

Click on “Next”

 

 

 

 

 

 

 

 

 

 

The files are installing on your computer:

Wait for the drivers file to install

 

 

 

 

 

 

 

 

 

Once the files have installed, the installation of the driver is done. Click on the “Finish” button:

Installation finished – click on “Finish”

 

 

 

 

 

 

 

 

 

Installation finished – click on “Finish”

 

 

 

 

 

 

 

 

 

 

Now plug in your PC/SC reader. You should see an icon in the bottom right corner of your screen:

Installing the reader

Reader Installed

 

 

 

 

To check that the reader has been correctly installed, run PC/SC Diag available in our PC/SC SDK:

Installation is successfull : you can see all the slots of your PC/SC reader

 

APPENDIX

If you don’t see anything in PC/SC Diag, even after doing this procedure, your Smart Card Service might be disabled.

PC/SC Diag shows no reader

In that case, go to the Control Panel of your computer, and look for “Services” under the “Administrative Tool” section.

Services Manager – look for the Smart Card service

If the “Startup Type” (4th Column) of the Smart Card service is set to “Disabled” , right click and open the “Properties” window of the Smart Card service:

Properties of Smart Card Service

 

 

 

 

 

 

 

 

 

 

 

Set startup type as “Automatic”. If “Service status” is set to “Stopped”, click on the “Start” button and wait until the Service status is set to “Start” (as shown on picture above).

Retrieving the firmware version of your SpringCard PC/SC reader

In order to retrieve the firmware version of your SpringCard PC/SC reader (CSB6Prox’N’Roll PC/SCEasyFinger and CrazyWriter), you’ll need the Springcard PC/SC Diagnostic Tool, available in our SDK (PcscDiag2.exe).

Once launched, the tool should display your smart card reader. In the following snapshots, the reader is a Prox’N’Roll PC/SC, but it would be same for other PC/SC readers (CSB6, CrazyWriter, CrazyWriter-HSP, CSB-HSP, H663, …).

Right click on it, and choose Reader Info :

A pop-up window will then appear, indicating the firmware version (1-64 in this example):

Note: Instead of right clicking on the reader, you can also press Ctl+R to get the same information.

New WHQL-certified PC/SC driver

Edited 24/04/2012: an updated version has been published to correct a few bugs. Please read this article.

Our new PC/SC driver is now online and ready for download! This driver (code name : SDD480-BA) has been certified my Microsoft’s Windows Hardware Qualification Labs (WHQL) for both 32 and 64 bits operating systems.

It targets all SpringCard USB CCID readers :
CSB6
CrazyWriter
EasyFinger
Prox’N’Roll PC/SC

Note: as the Prox’N’Roll has only one smartcard slot (its contactless card interface), it is not required to use our driver since the default CCID driver supplied by Microsoft also does the job.

The SDD480-BA driver is also ready for the new generation of USB CCID products that will be launched in a near future.

To download the driver, please go to http://www.springcard.com/download/find.php?file=sdd480

Choose either
sdd480_x86-ba.exe for 32 bits targets (certified and signed for Windows 2000, XP, Vista and Seven on i386 core)
sdd480_x64-ba.exe for 64 bits targets (certified and signed for Windows XP, Vista and Seven on amd64 or intel64 core)

The setup package uncompress the driver in Program Files\SpringCard\SDD480_x86-ba (or Program Files\SpringCard\SDD480_x64-ba depending on the target) and then installs the driver into Windows’ system directory. Of course you must run the setup with administrative priviledges.

The driver will also be available through Windows Update very soon.

A few more details for integrators and developers

Should you need to redistribute this driver with your own software or to recreate a setup package bundled with yours, just copy the uncompressed files and invoke DPInst.exe when you want the installation to take place.

Although we’ve done our best to ensure full compatibility with our previous (unsigned) driver and with Microsoft’s default CCID driver, please pay attention that the naming of the slots may be a little different in some cases. In fact slot naming and numbering has been designed to show clearly which slots belongs to which reader. Let’s suppose we have 2 CrazyWriter and 1 CSB6 connected to the PC. The 1st CrazyWriter instanciates 3 slots: CrazyWriter Contactless 0, CrazyWriter SAM A 0, CrazyWriter SAM B 0; the 2nd CrazyWriter instanciates 3 slots as well: CrazyWriter Contactless 1, CrazyWriter SAM A 1, CrazyWriter SAM B 1. Then the CSB6 instanciates 5 slots : CSB6 Contactless 2, CSB6 Contact 2, CSB6 SAM A 2, CSB6 SAM B 2, CSB6 SAM C 2. You see that the number is the same for all slots of one reader. This is the best approach to know which SAM (or contact interface) comes with whatever contactless interface.

Windows 7 complains on missing driver for smartcards – a practical workaround

Smartcards and smartcard-aware applications using application level commands (APDUs) are older than Windows and worked very well in the past, until Microsoft suddently decided that a smartcard shouldn’t be handheld directly by the applications anymore, and introduced the concept of smartcard driver software (ICC Service Provider withing the PC/SC framework). This issue sometimes occurs with our products in the SpringCard CSB6 Family (CSB6Prox’N’Roll PC/SCEasyFinger and CrazyWriter) and our NFC readers/encoders (H512NFC’Roll).

With Windows Seven, Microsoft goes one step further and mandates that every smartcard has its own driver (a ‘minidriver’ actually, i.e. a DLL running in user mode and not a SYS binary running in kernel mode). Everytime you put a smartcard on a contactless reader, or in a contact reader, the system tries to locate the appropriate driver, and this generally ends up with a red mark in the tray bar and this annoying message in the tray bar : “Device driver software was not successfully installed. Click here for details.” Luckily, smartcard-aware applications keep on working as usual on top of PC/SC API, thanks to classical SCardConnect / SCardTransmit function calls.

According to Microsoft, smartcard-issuers should provide a minidriver for their cards. The point is, the ICC Service Provider architecture is meaningfull to let security-sensitive applications access security features (digital signature, secure login) in an interoperable and high-level way, but it appears useless in other cases, when only one single software has to communicate with a single smartcard. And this is the case in 99% of the systems using contactless smartcards or contactless memory cards.

A techninal article has been published in Microsoft Knowledge base (http://support.microsoft.com/kb/976832/en-us) giving different solutions to prevent the system from looking for a driver and issuing the warning message. In this article we are detailing two solution :

  • 1st solution is to disable SmartCard PnP feature through a Group Policy. The side effect is that there’s not choice but to disable this feature for every cards, not only for the one that do not have a minidriver,
  • 2nd solution is to write in the system registry the list of cards that will not have a minidriver. In this article we do this through a small utility that makes it easier than entering the required lines in the registry one after the other.

Using a Group Policy to disable the smartcard PnP feature

Just follow this five steps :

  1. Run MMC.exe (Microsoft Management Console)
  2. Add Group Policy snap-in to the console
  3. Open Local Computer
  4. Browse to Policy\Computer Configuration\Windows Settings\Administrative Templates\Windows Components\Smart Card
  5. Disable Turn On Smart Card Plug And Play Services.

Command-line utility to selectively disable some smartcard minidrivers

The principle is to register in the system registry the ATRs of every smartcard we don’t want to go through the PnP feature, and to associate them to a dummy minidriver.

Here’s the technical part (details are to be found in MS’ reference article (http://support.microsoft.com/kb/976832/en-us),

  1. Create a branch under HKLM\Software\Microsoft\Cryptography\Calais\Smartcards, name the branch with any clever name that will describe the related smartcard
  2. In this branch create a REG_BINARY entry named ATR in which you put the smartcard’s ATR
  3. Create a REG_SZ entry named Crypto Provider and put the value $DisableSCPnP$ in it.

You may also add a REG_BINARY entry named ATRMask to associate this entry with more than one ATR. In the ATRMask, bits set to 1 means that the bits in ATR are relevant, and bits set to 0 act as wildcards.

 

A sample source code to do so is provided by MS’ with the article. We’ve  implemented this source code in a small command line tool, and added a lot of modifications to ease its use and to make it possible to disable smartcard PnP for any arbitrary-entered smartcard ATR, and not only for the smartcards physically inserted in the readers at the time of execution.

There are two binaries : pcsc_no_minidriver32.exe for 32-bit systems, and pcsc_no_minidriver64.exe for 64-bit systems. Invoke either software with the -h parameter to get help. With the -m parameter, the software starts monitoring all the PC/SC readers. For every card inserted, it disables the plug and play. Alternatively, the -a parameter let you specify the ATR (hexadecimal string) ; you may optionally use the -n parameter to specify a name for your smartcard (this is convenient if you want to remove it from the registry later on !).

Note, you must run this program as an administrator.

We supplied the software with 2 command line scripts (.CMD),

  • pcsc_no_minidriver_memory.cmd disables every memory card (ATR constructed according to PC/SC v.2 specification for memory cards)
  • pcsc_no_minidriver_well_known.cmd disables  some well-known contactless cards that do not have a minidriver (NXP Desfire, NXP Mifare Plus, various Calypso cards, …).

Of course, use this software and the related scripts with care and make sure you really do understand what it does, as it may prevent your system to work correctly with your 20$-cryptographic card that do need its minidriver to work with CryptoAPI.

Here’s the link to the package : http://www.springcard.com/download/pub/pcsc_no_minidriver.zip . It comes with complete source code. Just unzip in a local folder and enjoy.