Reading and writing data in a Mifare UltraLight Card, with a Prox’N’Roll

DOWNLOAD AND READ THE DOCUMENTATIONS

First thing to do is to obtain the documentation of the card from the manufacturer (NXP in this case) and the Prox’N’Roll developer’s reference manual.

From the card’s functional specifications, we can see that the memory is structured in 16 pages of 4 bytes. The four first pages (0-3) contain special bytes: so, we’ll only cover pages 4 to 16.

STEP BY STEP PROCEDURE

The goal is to read and write the card memory.

READ BINARY

In the developer’s reference manual, the READ BINARY instruction is described in §2.2.4 at the time of this writing.

The APDU is :

  • CLA: FF
  • INS: B0
  • P1: Address MSB
  • P2: Address LSB
  • Lc: not needed
  • Data in: not needed
  • Le: number of bytes to be read

The specifics to read Mifare Ultralight cards are detailed in §4.3.3.a (at the time of this writing).
Here, we can see that :

  • P1 must be 00
  • P2 is the address of the first page to be read
  • Le must a multiple of 4.

We want to read the whole memory, starting from page 4: this means we want to read 12 pages of 4 bytes, so 48 bytes (ie: 30 in hexadecimal).
So the APDU is :
FF B0 00 04 30

To send this APDU, please use our PC/SC Diagnostic tool, available on our main site (QuickStart for PC/SC).

Put the card on the reader: its ATR prints. To understand what this means, you can check §4.1.2 (at the time of this writing) in the developer’s reference manual.

ATRNow, double-clic on the line corresponding to the reader and enter the above-mentioned APDU :

read_capduClic on Transmit, or press “Enter”: the APDU is sent to the card and its response is printed in the bottom.

read_rapduThe card has obviously been previously written and the ASCII translation is provided: “Mifare Ultralight card, used with Prox’N’Roll”.
Please note that the card’s reponse ends with “90 00”, which means success.

UPDATE BINARY

In the developer’s reference manual, the UPDATE BINARY instruction is described in §2.2.5 at the time of this writing.

The APDU is :

  • CLA: FF
  • INS: D6
  • P1: Address MSB
  • P2: Address LSB
  • Lc: Lenght of Data In
  • Data in: Bytes to be written
  • Le: not needed

The specifics to write Mifare Ultralight cards are detailed in §4.3.3.b (at the time of this writing).
Here, we can see that :

  • P1 must be 00
  • P2 is the address of the unique page to be written
  • Le must be 4.

We want to replace “Prox’N’Roll” by “SpringCard” in the card memory, so we first have to determine which pages must be updated. Remember that Le must be 4 : this means that we can write exactely 4 bytes at a time (one page), no more, no less.

To determine the content of each page, just use the READ BINARY APDU.
For example, for page 12, the APDU should be : FF B0 00 0C 04

read_single_pageUsing those commands, we can see that:

  • content of page 12 (0x0C) is 68 20 50 72 (in ASCII : “h Pr”)
  • content of page 13 (0x0D) is 6F 78 27 4E (in ASCII: “ox’N”)
  • content of page 14 (0x0E) is 27 52 6F 6C (in ASCII: “‘Rol”)
  • content of page 15 (0x0F) is 6C 00 00 00 (in ASCII: “l” followed by invalid characters)

So, we’ll need to change 4 pages : pages 12, 13, 14 and 15.

SpringCard in ASCII is : “53 70 72 69 6E 67 43 61 72 64”

The 4 APDUs (one for each page) should be:

  • page 12: FF D6 00 0C 04 68 20 53 70 (the first two bytes remain unchanged)
  • page 13: FF D6 00 0D 04 72 69 6E 67
  • page 14: FF D6 00 0E 04 43 61 72 64
  • page 15: FF D6 00 0F 04 00 00 00 00 (we replace the first byte)

Enter those APDUs and click on “Transmit” :

write_single_pageOperation is successful if the card answers 90 00.

Now, you can read back the whole memory, using FF B0 00 04 0C:

final_readWe can see that “Prox’N’Roll” has been replaced by “SpringCard” in the card memory.

 

 

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.

Introducing the new FunkyGate-IP NFC

SpringCard‘s technical team is proud to announce the launch of a new generation of contactless readers for high-end access control applications, the FunkyGate NFC family.

Using the same shell as previous generation’s FunkyGate-DW (Dataclock, Wiegand and RS485 interfaces) and FunkyGate-SU (RS232 and USB interfaces), the FunkyGate NFC family introduces a brand-new member, the FunkyGate-IP NFC.

As the name suggests, the FunkyGate-IP NFC brings the power of TCP/IP up to the door or gate. A standard RJ45 plug connects the reader to any Ethernet LAN (10 or 100 Mbps). More than that, the FunkyGate-IP+POE NFC reader is powered directly by the network (Power Over Ethernet), thus removing the need for the classical 12V power cable.

The FunkyGate-IP+POE eases the job of wiring the building to before installing the access control system. With only a single Cat5e right to the door, the reader is operational as soon as it is plugged to the network.

The FunkyGate-IP+POE eases the job of wiring the building before installing the access control system. With only a single Cat5e right to the door, the reader is operational as soon as it is plugged to the network.

The FunkyGate-IP NFC and FunkyGate-IP+POE NFC readers take full benefit of SpringCard‘s know-how in all the various 13.56MHz protocols, and pave the way for a easier and wider use of NFC mobile phones in access control and identification applications.

SpringCard MultiConf is a new, versatile, configuration application for all SpringCard products. Define the FunkyGate-IP NFC's configuration, write this configuration into a Master Card, apply this Card to all the readers you want to configure, and voila!

SpringCard MultiConf is a new, versatile, configuration application for all SpringCard products. Define the FunkyGate-IP NFC’s configuration, write this configuration into a Master Card, apply this Card to all the readers you want to configure, and voila!

Thanks to the 4 card processing templates -a concept shared with the Prox’N’Roll RFID Scanner and among all SpringCard standalone readers-, the FunkyGate-IP NFC is able to fetch virtually any data from current contactless cards and RFID tags.

The ‘NFC’ in the product’s name denotes the exclusive ability to support new reading schemes based on NFC Forum’s concepts :

  • Read an NDEF record stored on a NFC Tag and retrieve its data,
  • Receive an NDEF message from a mobile phone, using NFC Peer-to-peer technology (SNEP over LLCP, Push mode : PUT request from smartphone to reader),
  • Get data from a card-emulation application, possibly running on an Android system thanks to the HCE (Host Card Emulation) feature.
Thanks to Android's 4.4 HCE mode, the FunkyGate-IP is able to get an identifier or perform a transaction over the NFC smartphone, even in screen-off mode. (this is also an unusual selfie)

Thanks to Android’s 4.4 HCE mode, the FunkyGate-IP is able to get an identifier or perform a transaction over the NFC smartphone, even in screen-off mode.
(this is also an unusual selfie)

When it comes to communication with the access control system (embedded control unit or computer running an access control server application), FunkyGate-IP NFC provides an efficient, low-overhead, fully secured communication protocol using TCP sockets and AES cipher for authentication, integrity and confidentiality.

An SDK will be released soon, together with a demo of an access control server application running on a small Linux system, typically a Raspberry Pi.

The reader also embeds a tiny HTTP server that makes it possible to develop a client application in no-time using high-level languages. A simple REST API exposes the reader’s behaviour (basically controlling the LEDs and buzzer) and the card/tag numbers to the outer world.

An example setup of using the FunkyGate-IP in the cloud: the reader provides data using a REST API (HTTP request, JSON content). The demo application runs in the browser (JavaScript).

An example setup of using the FunkyGate-IP in the cloud: the reader provides data using a REST API (HTTP request, JSON content). The demo application runs in the browser (JavaScript).
(click the image to enlarge)

FunkyGate-IP NFC HTTP access (REST) demo-page

Using the FunkyGate-IP NFC through HTTP: a demo-page showing how to use the REST API from a JavaScript application (if you have a FunkyGate-IP, use the demo at www.springcard.com/goto/iwm2/

First batches of FunkyGate-IP NFC (and FunkyGate-IP+POE NFC) are already shipping to our early-adopters. Don’t hesitate to contact us for a demo or to evaluate the product.

New documents and the SDK will be published on our web site in the oncoming weeks. In a second step, the E663, which is the core the FunkyGate-IP NFC is built on, will be offered to developers and integrators as a versatile Ethernet-based RFID/NFC OEM module. Stay tuned !

The FunkyGate-IP is built upon the new SpringCard E663 core. Supporting Ethernet and TCP/IP, this OEM RFID/NFC module could be the basis of new generation solutions that closes the gap between contactless smartcard technologies and today's cloud architectures.

The FunkyGate-IP is built upon the new SpringCard E663 core. Supporting Ethernet and TCP/IP, this OEM RFID/NFC module could be the basis of new generation solutions that closes the gap between contactless smartcard technologies and today’s cloud architectures.

.

EAS management for ICODE SLI/SLI-X (standard, type S and type L)

ICODE SLI are ISO 15693 compliant but feature proprietary extensions not implemented in the reader’s firmware. However, you can use those features in transparent mode. The following post will focus on EAS management with this type of tag. The function entries described are available in the CSB6 SDK.


EAS management in the different ICODE SLI types 

The way to access to the EAS field depend on the type of ICODE used. With ICODE SLI/SLI-X type L and S, EAS field can be password protected. Once password protected, a “set password” command must be sent to the card once in the RF field or if the password is modified. It will allow the execution of most of the other commands. This security is not available on classic ICODE SLI/SLI-X.


Transparent mode APDU structure

Most of the frames sent to the card contains :

Flags (1 byte) :
Those are detailed in the ISO 15693 documentation.

Command ID (1 byte) :
Allows to identify the type of command sent.

IC manufacturing code (1 byte) :
It refers to the tag type and is contained in the UID of the tag. For NXP Semiconductors, This code is 04h.

UID (8 bytes).

Some other fields are command specific and will be detailed below.


Command available in the SDK

*** AVAILABLE FOR ALL ICODE SLI TYPES ***

Set EAS
Available with void set_EAS(BYTE snr[8]);  
Set EAS status to 1.                                                                        

Reset EAS
Available with void reset_EAS(BYTE snr[8]); 
Set
 EAS status to 1.

Lock EAS
Available with void lock_EAS(BYTE snr[8]); 
This field is commented in the source code. Once locked, EAS cannot be modified anymore.

AVAILABLE FOR ICODE SLI/SLI-X S and L types

Protect EAS
Available with void protect_EAS(BYTE snr[8]);
This command allows to protect the EAS field with a password. Once set, this field cannot be changed and you will have to use the “set password” command to modify the EAS status.

Get random number
Available with short get_random_nb(BYTE snr[8], BYTE * rd_nb)      
It will request a 2 bytes randomly generated code required for a proper use of the “set password” command.

Set password
Available with void set_password(BYTE snr[8], BYTE password[4])
This command requires specific fileds : a password ID to inform the card of which fields are needed to be unlocked, and the previously stored password XOR two random numbers acquired with the “get random number” command.

ex :  if the last password was (00 00 00 00)h, and the last “get random number” command return you (0A 25)h, the 4 bytes to pass as command parameters will be (0A 25 0A 25)h.

Write password
Available with void write_password(BYTE snr[8], BYTE password[4])
Write a new password in the card (if the password field has not been locked).

Lock password
Available with void lock_password(BYTE snr[8])
This function is commented in the source code. Once locked, the password cannot be changed.


 About the reference application

The application manual is available via the executable call.
A simple [EXECUTABLE NAME] [COM] [HELP] will display the commands available.

KitKat: Impact of the latest Android OS on card emulation

“Who controls the smartphone?” is the obvious question that can lead to generating profits from every transaction by the controlling parties.

NFC use on smartphones allows for 3 modes of operation:  tag reading/writing, peer-to-peer and card emulation. The card emulation mode is the most interesting mode for the companies involved in such developments because it immediately generates cash flow. The business model is simple: one just needs to replace the existing cards (payment, transportation, etc.). A fraction of the millions of transactions performed everyday by those cards can then be transformed into profit for those controlling the smartphone.

Since 2005-2006, when NFC made its start, we have been witnessing a war among manufacturers; between those controlling the hardware and/or controlling its operating system, neither of which have strong ties with final users; and the cellphone carriers who are controlling the SIM and have strong customer relations through subscription plans.

From each side of the battlefield, the same argument is always pointed out: a transaction implies security requirements, and a security requirement implies embedded applications in a secured processor. The cellphone carriers argue that the SIM card is the best choice, since it is a secured processor and it is already present without any additional cost. The manufacturers argue that a secured processor (Secure Element) has to be added on the motherboard, the extra cost being minimal and the user being able to freely change transaction service providers without having to transfer his or her telephone service to a new vendor requiring a new SIM card.

In the middle of the battle ground, a new contender has emerged: the TSM (Trusted Service Manager), provides a unique and portable service whatever the underlying technical context, for a fee of course.

Until last week, the position of each party had remained frozen since the war started in 2005-2006. And then KitKat arrived.

KitKat is the code name for Android’s new 4.4 Operating System. And in the presentation of KitKat, from the second paragraph, one can read:

Android 4.4 introduces new platform support for secure NFC-based transactions through Host Card Emulation (HCE), for payments, loyalty programs, card access, transit passes, and other custom services. With HCE, any app on an Android device can emulate an NFC smart card, letting users tap to initiate transactions with an app of their choice — no provisioned secure element (SE) in the device is needed.(http://developer.android.com/about/versions/android-4.4.html)

Technically nothing really new; BlackBerry offered the same principle in the latest version of its OS. But Android’s market share is significantly different from BlackBerry’s market share! With this support, developers of sector-specific applications (access control, loyalty) finally have a solution to develop the card emulation mode on smartphones easily and without depending on anyone.

A few technical points to keep in mind:

1.      Card emulation « within the host » (HCE) cannot work if the phone is turned off (deliberately turned off or out of battery), whereas within some SIM-centric or SE-centric architectures it is sometimes possible to perform a transaction with a turned off smartphone.

2.      The main processor of the smartphone (baseband) isn’t a secure processor. Applications requiring a critical level of security (i.e., whenever the profits from the fraud is higher than the cost of the fraud: payment, public transportation, high security level access control, ID cards…) shouldn’t be implemented in this mode.

3.      The transaction times may perform less well; furthermore, they may operate less consistently than a classic implementation within a secured processor – which by nature is independent from other applications running on the smartphone.

4.      The technical architecture is based on ISO 14443 layer 4, type A, ISO 7816-4 for APDUs formalism, and ISO 7816-5 for the application selection by the reader thanks to a unique AID. Any application out of this frame wouldn’t qualify for the HCE porting. This is especially the case of some French « public transportation » implementations for which the readers only implement ISO 14443 type B.

Now, how do you implement that in the real world?

Step one, own a smartphone or a tablet running Android 4.4. Step two, download the latest SDK (API version 19). Step three, start coding!

(http://developer.android.com/reference/android/nfc/cardemulation/HostApduService.html)

1.      Declare in the Manifest of your application that you want to create a HostApduService, and associate one or several AIDs,

2.      Implement the method processCommandApdu which receives the C-APDU from the reader – and has to return the R-APDU to be re-sent. The first C-APDU received is the SELECT AID that activated your application,

3.      Implement the method onDeactivated to perform the closing of the channel (reader lost, S-DESELECT reception, selection of another application).

JavaCard developers won’t be confused; the names are different but the overall mechanics are similar (except for the initial select).

Please note that processCommandApdu is called in the main thread of the application. If the answer isn’t immediately available (if it comes from a distant server or if a user input is needed, for example), the application logic has to return a “NULL”. In a second time the application will call the function sendResponseApdu to answer efficiently. In the meantime the OS and the NFC Chipset keep the reader waiting using S-WTX.

If you are interested in NFC applications, please check our NFC readers/encoders, H512 and NFC’Roll.

Firmware release 1.75 for H512 and NFC’Roll

A new firmware version (release 1.75.2) has just been published for SpringCard H512 and NFC’Roll.

This firmware improves the behaviour in card emulation and peer-to-peer (initiator) mode, allowing more reliable exchanges with most smartphones running either in reader or peer-to-peer (target) mode.

The same version will be released very soon for H663 and Prox’N’Roll PC/SC.

NFC’Roll

The new firmware is here: https://files.springcard.com/firmwares/springprox/1-75/2212_pn512_nfcroll-10_1-75.mot

The firmware upgrade procedure is here: https://tech.springcard.com/firmware-upgrade/csb6-firmware-upgrade/

H512

The new firmware is here: https://files.springcard.com/firmwares/springprox/1-75/uc3b0256_pn512_h512_1-75.hex

The firmware upgrade procedure is here: https://tech.springcard.com/firmware-upgrade/h663-h512-firmware-upgrade/

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:

java decode:true">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:

java decode:true">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.

SpringCard introduces new SDK for NFC-enabled PC/SC readers

It’s now the final countdown before the launch of new SpringCard NFC products, H512 and NFC’Roll. Both products are not only able to read/write NFC Tags, but they also introduce NFC peer-to-peer communication and an innovative Card emulation mode.

The developers who already have an early release of either product, or who want to start evaluating the development process, are welcomed to download the first version of the SDK, which has been made available today, together with its documentation.

The NFC SDK for PC/SC includes
NFcTool, a Tag read/write Utility,
NFcBeam, implementing the NFC Forum ‘Simple NDEF Exchange Protocol’ (SNEP) on top of NFC Forum LLCP (Logical Link Control Protocol), itself on top of NFC-DEP, i.e. the NFCIP1 peer-to-peer layer (ISO 18092 chapter 12). A typical use-case would be to retrieve a contact entry (VCard) from an Android smartphone, or to push a SmartPoster from the PC to the smartphone,
NfcTagEmul, showing how easy it is for either H512 or NFC’Roll to emulate a NFC Forum Tag (type 2 or type 4). This makes it possible to push a SmartPoster, URI, Text, VCard… from the PC to the smartphone, as smoothly as if the phone was reading a static Tag,
– and much more!

Edit 15/10/2013: starting with PC/SC SDK version 2.12, the NFC extensions are now included in the PC/SC SDK itself. Please read this article for details.

Those software are available with complete source (C# for .NET) in the SDK. Please download and read PMD2228: NFC SDK for PC/SC – Getting Started Guide for a guided tour and a few technical details.

Click here to download SpringCard NFC SDK for PC/SC

The reference manual for operating the readers from PC/SC applications is here: PMD2176: H512 (and NFC’Roll) Developer’s Reference Manual.

An installer is also available (SQ2211: QuickStart for H512 and NFC’Roll) for people who want to try the products but don’t need the full SDK.

Warning: a few changes have been on the specifications since the Alpha version of the firmware (1.6x branch). Products shall be updated to firmware v1.70 in order to be compliant with the final specifications, and to work with this SDK. Current 1.7x branch doesn’t include peer-to-peer in Target mode (only Initiator mode is currently implemented). This will be added in 1.8x branch.