pcsc-lite 2.3.0
IFDHandler

This provides reader specific low-level calls. More...

Functions

RESPONSECODE IFDHCreateChannelByName (DWORD Lun, LPSTR DeviceName)
 This function is required to open a communications channel to the port listed by DeviceName.
 
RESPONSECODE IFDHControl (DWORD Lun, DWORD dwControlCode, PUCHAR TxBuffer, DWORD TxLength, PUCHAR RxBuffer, DWORD RxLength, LPDWORD pdwBytesReturned)
 This function performs a data exchange with the reader (not the card) specified by Lun.
 
RESPONSECODE IFDHCreateChannel (DWORD Lun, DWORD Channel)
 This function is required to open a communications channel to the port listed by Channel.
 
RESPONSECODE IFDHCloseChannel (DWORD Lun)
 This function should close the reader communication channel for the particular reader.
 
RESPONSECODE IFDHGetCapabilities (DWORD Lun, DWORD Tag, PDWORD Length, PUCHAR Value)
 This function should get the slot/card capabilities for a particular slot/card specified by Lun.
 
RESPONSECODE IFDHSetCapabilities (DWORD Lun, DWORD Tag, DWORD Length, PUCHAR Value)
 This function should set the slot/card capabilities for a particular slot/card specified by Lun.
 
RESPONSECODE IFDHSetProtocolParameters (DWORD Lun, DWORD Protocol, UCHAR Flags, UCHAR PTS1, UCHAR PTS2, UCHAR PTS3)
 This function should set the Protocol Type Selection (PTS) of a particular card/slot using the three PTS parameters sent.
 
RESPONSECODE IFDHPowerICC (DWORD Lun, DWORD Action, PUCHAR Atr, PDWORD AtrLength)
 This function controls the power and reset signals of the smart card reader at the particular reader/slot specified by Lun.
 
RESPONSECODE IFDHTransmitToICC (DWORD Lun, SCARD_IO_HEADER SendPci, PUCHAR TxBuffer, DWORD TxLength, PUCHAR RxBuffer, PDWORD RxLength, PSCARD_IO_HEADER RecvPci)
 This function performs an APDU exchange with the card/slot specified by Lun.
 
RESPONSECODE IFDHICCPresence (DWORD Lun)
 This function returns the status of the card inserted in the reader/slot specified by Lun.
 

Detailed Description

This provides reader specific low-level calls.

The routines specified hereafter will allow you to write an IFD handler for the PC/SC Lite resource manager. Please use the complement developer's kit complete with headers and Makefile at: https://muscle.apdu.fr/musclecard.com/sourcedrivers.html

This gives a common API for communication to most readers in a homogeneous fashion. This document assumes that the driver developer is experienced with standards such as ISO-7816-(1, 2, 3, 4), EMV and MCT specifications. For listings of these specifications please access the above web site.

USB readers

USB readers use the bundle approach so that the reader can be loaded and unloaded upon automatic detection of the device. The bundle approach is simple: the actual library is just embedded in a directory so additional information can be gathered about the device.

A bundle looks like the following:

GenericReader.bundle/
  Contents/
    Info.plist  - XML file describing the reader
    MacOS/      - Driver directory for OS X
    Solaris/    - Driver directory for Solaris
    Linux/      - Driver directory for Linux
    HPUX/       - Driver directory for HPUX

The Info.plist file describes the driver and gives the loader all the necessary information. The following must be contained in the Info.plist file:

ifdVendorID

The vendor ID of the USB device.

Example:

    <key>ifdVendorID</key>
    <string>0x04E6</string>

You may have an OEM of this reader in which an additional <string> can be used like in the below example:

    <key>ifdVendorID</key>
    <array>
      <string>0x04E6</string>
      <string>0x0973</string>
    </array>

If multiples exist all the other parameters must have a second value also. You may chose not to support this feature but it is useful when reader vendors OEM products so you only distribute one driver.

The CCID driver from Ludovic Rousseau https://ccid.apdu.fr/ uses this feature since the same driver supports many different readers.

ifdProductID

The product id of the USB device.

   <key>ifdProductID</key>
   <string>0x3437</string>

ifdFriendlyName

Example:

   <key>ifdFriendlyName</key>
   <string>SCM Microsystems USB Reader</string>

The reader name must use the ASCII character set.

CFBundleExecutable

The executable name which exists in the particular platform's directory.

Example:

   <key>CFBundleExecutable</key>
   <string>libccid.so.0.4.2</string>

ifdCapabilities

List of capabilities supported by the driver. This is a bit field. Possible values are:

Complete sample file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
    "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>English</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundlePackageType</key>
    <string>BNDL</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>CFBundleVersion</key>
    <string>0.0.1d1</string>
    <key>ifdCapabilities</key>
    <string>0x00000000</string>
    <key>ifdProtocolSupport</key>
    <string>0x00000001</string>
    <key>ifdVersionNumber</key>
    <string>0x00000001</string>

    <key>CFBundleExecutable</key>
    <string>libfoobar.so.x.y</string>

    <key>ifdManufacturerString</key>
    <string>Foo bar inc.</string>

    <key>ifdProductString</key>
    <string>Driver for Foobar reader, version x.y</string>

    <key>ifdVendorID</key>
    <string>0x1234</string>

    <key>ifdProductID</key>
    <string>0x5678</string>

    <key>ifdFriendlyName</key>
    <string>Foobar USB reader</string>
</dict>
</plist>

As indicated in the XML file the DTD is available at http://www.apple.com/DTDs/PropertyList-1.0.dtd.

Serial readers

Serial drivers must be configured to operate on a particular port and respond to a particular name. The reader.conf file is used for this purpose.

It has the following syntax:

# Configuration file for pcsc-lite
# David Corcoran <corcoran@musclecard.com>

FRIENDLYNAME  "Generic Reader"
DEVICENAME    /dev/ttyS0
LIBPATH       /usr/lib/pcsc/drivers/libgen_ifd.so
CHANNELID     1

The pound sign # denotes a comment.

FRIENDLYNAME

The FRIENDLYNAME field is an arbitrary text used to identify the reader. This text is displayed by commands like pcsc_scan https://pcsc-tools.apdu.fr/ that prints the names of all the connected and detected readers.

DEVICENAME

The DEVICENAME field was not used for old drivers (using the IFD handler version 2.0 or previous). It is now (IFD handler version 3.0) used to identify the physical port on which the reader is connected. This is the device name of this port. It is dependent of the OS kernel. For example the first serial port device is called /dev/ttyS0 under Linux and /dev/cuaa0 under FreeBSD.

If you want to use IFDHCreateChannel() instead of IFDHCreateChannelByName() then do not use any DEVICENAME line in the configuration file. IFDHCreateChannel() will then be called with the CHANNELID parameter.

LIBPATH

The LIBPATH field is the filename of the driver code. The driver is a dynamically loaded piece of code (generally a drivername.so* file).

CHANNELID

The CHANNELID is no more used for recent drivers (IFD handler 3.0) and has been superseded by DEVICENAME.

If you have an old driver this field is used to indicate the port to use. You should read your driver documentation to know what information is needed here. It should be the serial port number for a serial reader.

CHANNELID was the numeric version of the port in which the reader will be located. This may be done by a symbolic link where /dev/pcsc/1 is the first device which may be a symbolic link to /dev/ttyS0 or whichever location your reader resides.

Function Documentation

◆ IFDHCloseChannel()

RESPONSECODE IFDHCloseChannel ( DWORD Lun)

This function should close the reader communication channel for the particular reader.

Prior to closing the communication channel the reader should make sure the card is powered down and the terminal is also powered down.

Parameters
[in]LunLogical Unit Number
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHControl()

RESPONSECODE IFDHControl ( DWORD Lun,
DWORD dwControlCode,
PUCHAR TxBuffer,
DWORD TxLength,
PUCHAR RxBuffer,
DWORD RxLength,
LPDWORD pdwBytesReturned )

This function performs a data exchange with the reader (not the card) specified by Lun.

It is responsible for abstracting functionality such as PIN pads, biometrics, LCD panels, etc. You should follow the MCT and CTBCS specifications for a list of accepted commands to implement. This function is fully voluntary and does not have to be implemented unless you want extended functionality.

Parameters
[in]LunLogical Unit Number
[in]dwControlCodeControl code for the operation
This value identifies the specific operation to be performed. This value is driver specific.
[in]TxBufferTransmit data
[in]TxLengthLength of this buffer
[out]RxBufferReceive data
[in]RxLengthLength of the response buffer
[out]pdwBytesReturnedLength of response
This function will be passed the length of the buffer RxBuffer in RxLength and it must set the length of the received data in pdwBytesReturned.
Note
*pdwBytesReturned should be set to zero on error.
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_RESPONSE_TIMEOUTThe response timed out (IFD_RESPONSE_TIMEOUT)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHCreateChannel()

RESPONSECODE IFDHCreateChannel ( DWORD Lun,
DWORD Channel )

This function is required to open a communications channel to the port listed by Channel.

For example, the first serial reader on COM1 would link to /dev/pcsc/1 which would be a symbolic link to /dev/ttyS0 on some machines This is used to help with inter-machine independence.

On machines with no /dev directory the driver writer may choose to map their Channel to whatever they feel is appropriate.

Once the channel is opened the reader must be in a state in which it is possible to query IFDHICCPresence() for card status.

USB readers can ignore the Channel parameter and query the USB bus for the particular reader by manufacturer and product id.

Parameters
[in]LunLogical Unit Number
Use this for multiple card slots or multiple readers. 0xXXXXYYYY - XXXX multiple readers, YYYY multiple slots. The resource manager will set these automatically. By default the resource manager loads a new instance of the driver so if your reader does not have more than one smart card slot then ignore the Lun in all the functions.

PC/SC supports the loading of multiple readers through one instance of the driver in which XXXX is important. XXXX identifies the unique reader in which the driver communicates to. The driver should set up an array of structures that associate this XXXX with the underlying details of the particular reader.
[in]ChannelChannel ID This is denoted by the following:
  • 0x000001 /dev/pcsc/1
  • 0x000002 /dev/pcsc/2
  • 0x000003 /dev/pcsc/3
  • 0x000004 /dev/pcsc/4
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHCreateChannelByName()

RESPONSECODE IFDHCreateChannelByName ( DWORD Lun,
LPSTR DeviceName )

This function is required to open a communications channel to the port listed by DeviceName.

Once the channel is opened the reader must be in a state in which it is possible to query IFDHICCPresence() for card status.

Parameters
[in]LunLogical Unit Number
Use this for multiple card slots or multiple readers. 0xXXXXYYYY - XXXX multiple readers, YYYY multiple slots. The resource manager will set these automatically. By default the resource manager loads a new instance of the driver so if your reader does not have more than one smart card slot then ignore the Lun in all the functions.

PC/SC supports the loading of multiple readers through one instance of the driver in which XXXX is important. XXXX identifies the unique reader in which the driver communicates to. The driver should set up an array of structures that associate this XXXX with the underlying details of the particular reader.
[in]DeviceNameFilename to use by the driver.
For drivers configured by /etc/reader.conf this is the value of the field DEVICENAME.
For USB drivers the DeviceName must start with usb:VID/PID. VID is the Vendor ID and PID is the Product ID. Both are a 4-digits hex number.

Typically the string is generated by:

printf("usb:%04x/%04x", idVendor, idProduct);

The DeviceName string may also contain a more specialised identification string. This additional information is used to differentiate between two identical readers connected at the same time. In this case the driver can't differentiate the two readers using VID and PID and must use some additional information identifying the USB port used by each reader.

  • libusb

    For USB drivers using libusb-1.0 http://libusb.sourceforge.net/ for USB abstraction the DeviceName the string may be generated by:

    printf("usb:%04x/%04x:libusb-1.0:%d:%d:%d",
    idVendor, idProduct, bus_number, device_address, interface)

    So it is something like: usb:08e6/3437:libusb-1.0:7:99:0 under GNU/Linux.

  • libudev

    If pcscd is compiled with libudev support instead of libusb (default since pcsc-lite 1.6.8) the string will look like:

    printf("usb:%04x/%04x:libudev:%d:%s", idVendor, idProduct,
    bInterfaceNumber, devpath);

    bInterfaceNumber is the number of the interface on the device. It is only useful for devices with more than one CCID interface.

    devpath is the filename of the device on the file system.

    So it is something like: usb:08e6/3437:libudev:0:/dev/bus/usb/008/047 under GNU/Linux.

  • other

    If the driver does not understand the :libusb: or :libudev: scheme or if a new scheme is used, the driver should ignore the part it does not understand instead of failing.

    The driver shall recognize the usb:VID/PID part and, only if possible, the remaining of the DeviceName field.

    It is the responsibility of the driver to correctly identify the reader.

Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHGetCapabilities()

RESPONSECODE IFDHGetCapabilities ( DWORD Lun,
DWORD Tag,
PDWORD Length,
PUCHAR Value )

This function should get the slot/card capabilities for a particular slot/card specified by Lun.

Again, if you have only 1 card slot and don't mind loading a new driver for each reader then ignore Lun.

Parameters
[in]LunLogical Unit Number
[in]TagTag of the desired data value
[in,out]LengthLength of the desired data value
[out]ValueValue of the desired data
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_ERROR_INSUFFICIENT_BUFFERBuffer is too small (IFD_ERROR_INSUFFICIENT_BUFFER)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_ERROR_TAGInvalid tag given (IFD_ERROR_TAG)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHICCPresence()

RESPONSECODE IFDHICCPresence ( DWORD Lun)

This function returns the status of the card inserted in the reader/slot specified by Lun.

In cases where the device supports asynchronous card insertion/removal detection, it is advised that the driver manages this through a thread so the driver does not have to send and receive a command each time this function is called.

Parameters
[in]LunLogical Unit Number
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_ICC_NOT_PRESENTICC is not present (IFD_ICC_NOT_PRESENT)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHPowerICC()

RESPONSECODE IFDHPowerICC ( DWORD Lun,
DWORD Action,
PUCHAR Atr,
PDWORD AtrLength )

This function controls the power and reset signals of the smart card reader at the particular reader/slot specified by Lun.

Parameters
[in]LunLogical Unit Number
[in]ActionAction to be taken on the card
  • IFD_POWER_UP Power up the card (store and return Atr and AtrLength)
  • IFD_POWER_DOWN Power down the card (Atr and AtrLength should be zeroed)
  • IFD_RESET Perform a warm reset of the card (no power down). If the card is not powered then power up the card (store and return Atr and AtrLength)
[out]AtrAnswer to Reset (ATR) of the card
The driver is responsible for caching this value in case IFDHGetCapabilities() is called requesting the ATR and its length. The ATR length should not exceed MAX_ATR_SIZE.
[in,out]AtrLengthLength of the ATR
This should not exceed MAX_ATR_SIZE.
Note
Memory cards without an ATR should return IFD_SUCCESS on reset but the Atr should be zeroed and the length should be zero Reset errors should return zero for the AtrLength and return IFD_ERROR_POWER_ACTION.
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_ERROR_POWER_ACTIONError powering/resetting card (IFD_ERROR_POWER_ACTION)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_NOT_SUPPORTEDAction not supported (IFD_NOT_SUPPORTED)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHSetCapabilities()

RESPONSECODE IFDHSetCapabilities ( DWORD Lun,
DWORD Tag,
DWORD Length,
PUCHAR Value )

This function should set the slot/card capabilities for a particular slot/card specified by Lun.

Again, if you have only 1 card slot and don't mind loading a new driver for each reader then ignore Lun.

Parameters
[in]LunLogical Unit Number
[in]TagTag of the desired data value
[in,out]LengthLength of the desired data value
[out]ValueValue of the desired data

This function is also called when the application uses the PC/SC SCardSetAttrib() function. The list of supported tags is not limited.

Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_ERROR_TAGInvalid tag given (IFD_ERROR_TAG)
IFD_ERROR_SET_FAILURECould not set value (IFD_ERROR_SET_FAILURE)
IFD_ERROR_VALUE_READ_ONLYTrying to set read only value (IFD_ERROR_VALUE_READ_ONLY)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHSetProtocolParameters()

RESPONSECODE IFDHSetProtocolParameters ( DWORD Lun,
DWORD Protocol,
UCHAR Flags,
UCHAR PTS1,
UCHAR PTS2,
UCHAR PTS3 )

This function should set the Protocol Type Selection (PTS) of a particular card/slot using the three PTS parameters sent.

Parameters
[in]LunLogical Unit Number
[in]ProtocolDesired protocol
[in]FlagsLogical OR of possible values to determine which PTS values to negotiate
[in]PTS11st PTS Value
[in]PTS22nd PTS Value
[in]PTS33rd PTS Value
See ISO 7816/EMV documentation.
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_ERROR_PTS_FAILURECould not set PTS value (IFD_ERROR_PTS_FAILURE)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_PROTOCOL_NOT_SUPPORTEDProtocol is not supported (IFD_PROTOCOL_NOT_SUPPORTED)
IFD_NOT_SUPPORTEDAction not supported (IFD_NOT_SUPPORTED)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)

◆ IFDHTransmitToICC()

RESPONSECODE IFDHTransmitToICC ( DWORD Lun,
SCARD_IO_HEADER SendPci,
PUCHAR TxBuffer,
DWORD TxLength,
PUCHAR RxBuffer,
PDWORD RxLength,
PSCARD_IO_HEADER RecvPci )

This function performs an APDU exchange with the card/slot specified by Lun.

The driver is responsible for performing any protocol specific exchanges such as T=0, 1, etc. differences. Calling this function will abstract all protocol differences.

Parameters
[in]LunLogical Unit Number
[in]SendPcicontains two structure members
  • Protocol 0, 1, ... 14
    T=0 ... T=14
  • Length
    Not used.
[in]TxBufferTransmit APDU
Example: "\x00\xA4\x00\x00\x02\x3F\x00"
[in]TxLengthLength of this buffer
[out]RxBufferReceive APDU
Example: "\x61\x14"
[in,out]RxLengthLength of the received APDU
This function will be passed the size of the buffer of RxBuffer and this function is responsible for setting this to the length of the received APDU response. This should be ZERO on all errors. The resource manager will take responsibility of zeroing out any temporary APDU buffers for security reasons.
[out]RecvPcicontains two structure members
  • Protocol - 0, 1, ... 14
    T=0 ... T=14
  • Length
    Not used.
Note
The driver is responsible for knowing what type of card it has. If the current slot/card contains a memory card then this command should ignore the Protocol and use the MCT style commands for support for these style cards and transmit them appropriately. If your reader does not support memory cards or you don't want to implement this functionality, then ignore this.
RxLength should be set to zero on error.
The driver is not responsible for doing an automatic Get Response command for received buffers containing 61 XX.
Returns
Error codes
Return values
IFD_SUCCESSSuccessful (IFD_SUCCESS)
IFD_COMMUNICATION_ERRORError has occurred (IFD_COMMUNICATION_ERROR)
IFD_RESPONSE_TIMEOUTThe response timed out (IFD_RESPONSE_TIMEOUT)
IFD_ICC_NOT_PRESENTICC is not present (IFD_ICC_NOT_PRESENT)
IFD_NOT_SUPPORTEDAction not supported (IFD_NOT_SUPPORTED)
IFD_NO_SUCH_DEVICEThe reader is no more present (IFD_NO_SUCH_DEVICE)