|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* MUSCLE SmartCard Development ( http://pcsclite.alioth.debian.org/pcsclite.html )
|
|
Packit Service |
aee942 |
*
|
|
Packit Service |
aee942 |
* Copyright (C) 1999-2004
|
|
Packit Service |
aee942 |
* David Corcoran <corcoran@musclecard.com>
|
|
Packit Service |
aee942 |
* Copyright (C) 2003-2004
|
|
Packit Service |
aee942 |
* Damien Sauveron <damien.sauveron@labri.fr>
|
|
Packit Service |
aee942 |
* Copyright (C) 2002-2011
|
|
Packit Service |
aee942 |
* Ludovic Rousseau <ludovic.rousseau@free.fr>
|
|
Packit Service |
aee942 |
*
|
|
Packit Service |
aee942 |
Redistribution and use in source and binary forms, with or without
|
|
Packit Service |
aee942 |
modification, are permitted provided that the following conditions
|
|
Packit Service |
aee942 |
are met:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
1. Redistributions of source code must retain the above copyright
|
|
Packit Service |
aee942 |
notice, this list of conditions and the following disclaimer.
|
|
Packit Service |
aee942 |
2. Redistributions in binary form must reproduce the above copyright
|
|
Packit Service |
aee942 |
notice, this list of conditions and the following disclaimer in the
|
|
Packit Service |
aee942 |
documentation and/or other materials provided with the distribution.
|
|
Packit Service |
aee942 |
3. The name of the author may not be used to endorse or promote products
|
|
Packit Service |
aee942 |
derived from this software without specific prior written permission.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
Packit Service |
aee942 |
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
Packit Service |
aee942 |
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
Packit Service |
aee942 |
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
Packit Service |
aee942 |
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
Packit Service |
aee942 |
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
Packit Service |
aee942 |
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
Packit Service |
aee942 |
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
Packit Service |
aee942 |
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
Packit Service |
aee942 |
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
* @file
|
|
Packit Service |
aee942 |
* @defgroup IFDHandler IFDHandler
|
|
Packit Service |
aee942 |
* @brief This provides reader specific low-level calls.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The routines specified hereafter will allow you to write an IFD handler
|
|
Packit Service |
aee942 |
for the PC/SC Lite resource manager. Please use the complement
|
|
Packit Service |
aee942 |
developer's kit complete with headers and Makefile at:
|
|
Packit Service |
aee942 |
http://www.musclecard.com/drivers.html
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
This gives a common API for communication to most readers in a
|
|
Packit Service |
aee942 |
homogeneous fashion. This document assumes that the driver developer is
|
|
Packit Service |
aee942 |
experienced with standards such as ISO-7816-(1, 2, 3, 4), EMV and MCT
|
|
Packit Service |
aee942 |
specifications. For listings of these specifications please access the
|
|
Packit Service |
aee942 |
above web site.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@section UsbReaders USB readers
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
USB readers use the bundle approach so that the reader can be loaded
|
|
Packit Service |
aee942 |
and unloaded upon automatic detection of the device. The bundle
|
|
Packit Service |
aee942 |
approach is simple: the actual library is just embedded in a
|
|
Packit Service |
aee942 |
directory so additional information can be gathered about the device.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
A bundle looks like the following:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
GenericReader.bundle/
|
|
Packit Service |
aee942 |
Contents/
|
|
Packit Service |
aee942 |
Info.plist - XML file describing the reader
|
|
Packit Service |
aee942 |
MacOS/ - Driver directory for OS X
|
|
Packit Service |
aee942 |
Solaris/ - Driver directory for Solaris
|
|
Packit Service |
aee942 |
Linux/ - Driver directory for Linux
|
|
Packit Service |
aee942 |
HPUX/ - Driver directory for HPUX
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The @c Info.plist file describes the driver and gives the loader
|
|
Packit Service |
aee942 |
all the necessary information. The following must be contained in the
|
|
Packit Service |
aee942 |
@c Info.plist file:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection ifdVendorID
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The vendor ID of the USB device.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Example:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
<key>ifdVendorID</key>
|
|
Packit Service |
aee942 |
<string>0x04E6</string>
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
You may have an OEM of this reader in which an additional @c <string>
|
|
Packit Service |
aee942 |
can be used like in the below example:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
<key>ifdVendorID</key>
|
|
Packit Service |
aee942 |
<array>
|
|
Packit Service |
aee942 |
<string>0x04E6</string>
|
|
Packit Service |
aee942 |
<string>0x0973</string>
|
|
Packit Service |
aee942 |
</array>
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
If multiples exist all the other parameters must have a second value
|
|
Packit Service |
aee942 |
also. You may chose not to support this feature but it is useful when
|
|
Packit Service |
aee942 |
reader vendors OEM products so you only distribute one driver.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The CCID driver from Ludovic Rousseau
|
|
Packit Service |
aee942 |
http://pcsclite.alioth.debian.org/ccid.html uses this feature since the
|
|
Packit Service |
aee942 |
same driver supports many different readers.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection ifdProductID
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The product id of the USB device.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
<key>ifdProductID</key>
|
|
Packit Service |
aee942 |
<string>0x3437</string>
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection ifdFriendlyName
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Example:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
<key>ifdFriendlyName</key>
|
|
Packit Service |
aee942 |
<string>SCM Microsystems USB Reader</string>
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The reader name must use the ASCII character set.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection CFBundleExecutable
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The executable name which exists in the particular platform's directory.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Example:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
<key>CFBundleExecutable</key>
|
|
Packit Service |
aee942 |
<string>libccid.so.0.4.2</string>
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection ifdCapabilities
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
List of capabilities supported by the driver. This is a bit field. Possible values are:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
- 0
|
|
Packit Service |
aee942 |
No special capabilities
|
|
Packit Service |
aee942 |
- 1 IFD_GENERATE_HOTPLUG
|
|
Packit Service |
aee942 |
The driver supports the hot plug feature.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Complete sample file:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
Packit Service |
aee942 |
<plist version="1.0">
|
|
Packit Service |
aee942 |
<dict>
|
|
Packit Service |
aee942 |
<key>CFBundleDevelopmentRegion</key>
|
|
Packit Service |
aee942 |
<string>English</string>
|
|
Packit Service |
aee942 |
<key>CFBundleInfoDictionaryVersion</key>
|
|
Packit Service |
aee942 |
<string>6.0</string>
|
|
Packit Service |
aee942 |
<key>CFBundlePackageType</key>
|
|
Packit Service |
aee942 |
<string>BNDL</string>
|
|
Packit Service |
aee942 |
<key>CFBundleSignature</key>
|
|
Packit Service |
aee942 |
<string>????</string>
|
|
Packit Service |
aee942 |
<key>CFBundleVersion</key>
|
|
Packit Service |
aee942 |
<string>0.0.1d1</string>
|
|
Packit Service |
aee942 |
<key>ifdCapabilities</key>
|
|
Packit Service |
aee942 |
<string>0x00000000</string>
|
|
Packit Service |
aee942 |
<key>ifdProtocolSupport</key>
|
|
Packit Service |
aee942 |
<string>0x00000001</string>
|
|
Packit Service |
aee942 |
<key>ifdVersionNumber</key>
|
|
Packit Service |
aee942 |
<string>0x00000001</string>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
<key>CFBundleExecutable</key>
|
|
Packit Service |
aee942 |
<string>libfoobar.so.x.y</string>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
<key>ifdManufacturerString</key>
|
|
Packit Service |
aee942 |
<string>Foo bar inc.</string>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
<key>ifdProductString</key>
|
|
Packit Service |
aee942 |
<string>Driver for Foobar reader, version x.y</string>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
<key>ifdVendorID</key>
|
|
Packit Service |
aee942 |
<string>0x1234</string>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
<key>ifdProductID</key>
|
|
Packit Service |
aee942 |
<string>0x5678</string>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
<key>ifdFriendlyName</key>
|
|
Packit Service |
aee942 |
<string>Foobar USB reader</string>
|
|
Packit Service |
aee942 |
</dict>
|
|
Packit Service |
aee942 |
</plist>
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
As indicated in the XML file the DTD is available at
|
|
Packit Service |
aee942 |
http://www.apple.com/DTDs/PropertyList-1.0.dtd.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@section SerialReaders Serial readers
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Serial drivers must be configured to operate on a particular port and
|
|
Packit Service |
aee942 |
respond to a particular name. The @c reader.conf file is used for this
|
|
Packit Service |
aee942 |
purpose.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
It has the following syntax:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
# Configuration file for pcsc-lite
|
|
Packit Service |
aee942 |
# David Corcoran <corcoran@musclecard.com>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
FRIENDLYNAME Generic Reader
|
|
Packit Service |
aee942 |
DEVICENAME /dev/ttyS0
|
|
Packit Service |
aee942 |
LIBPATH /usr/lib/pcsc/drivers/libgen_ifd.so
|
|
Packit Service |
aee942 |
CHANNELID 1
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The pound sign # denotes a comment.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection FRIENDLYNAME
|
|
Packit Service |
aee942 |
The FRIENDLYNAME field is an arbitrary text used to identify the reader.
|
|
Packit Service |
aee942 |
This text is displayed by commands like @c pcsc_scan
|
|
Packit Service |
aee942 |
http://ludovic.rousseau.free.fr/softwares/pcsc-tools/ that prints the
|
|
Packit Service |
aee942 |
names of all the connected and detected readers.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection DEVICENAME
|
|
Packit Service |
aee942 |
The DEVICENAME field was not used for old drivers (using the IFD handler
|
|
Packit Service |
aee942 |
version 2.0 or previous). It is now (IFD handler version 3.0) used to
|
|
Packit Service |
aee942 |
identify the physical port on which the reader is connected. This is
|
|
Packit Service |
aee942 |
the device name of this port. It is dependent of the OS kernel. For
|
|
Packit Service |
aee942 |
example the first serial port device is called @c /dev/ttyS0 under Linux
|
|
Packit Service |
aee942 |
and @c /dev/cuaa0 under FreeBSD.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
If you want to use IFDHCreateChannel() instead of
|
|
Packit Service |
aee942 |
IFDHCreateChannelByName() then do not use any DEVICENAME line in the
|
|
Packit Service |
aee942 |
configuration file. IFDHCreateChannel() will then be called with the
|
|
Packit Service |
aee942 |
CHANNELID parameter.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection LIBPATH
|
|
Packit Service |
aee942 |
The LIBPATH field is the filename of the driver code. The driver is a
|
|
Packit Service |
aee942 |
dynamically loaded piece of code (generally a @c drivername.so* file).
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@subsection CHANNELID
|
|
Packit Service |
aee942 |
The CHANNELID is no more used for recent drivers (IFD handler 3.0) and
|
|
Packit Service |
aee942 |
has been superseded by DEVICENAME.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
If you have an old driver this field is used to indicate the port to
|
|
Packit Service |
aee942 |
use. You should read your driver documentation to know what information
|
|
Packit Service |
aee942 |
is needed here. It should be the serial port number for a serial reader.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
CHANNELID was the numeric version of the port in which the reader will
|
|
Packit Service |
aee942 |
be located. This may be done by a symbolic link where @c /dev/pcsc/1 is
|
|
Packit Service |
aee942 |
the first device which may be a symbolic link to @c /dev/ttyS0 or
|
|
Packit Service |
aee942 |
whichever location your reader resides.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#ifndef _ifd_handler_h_
|
|
Packit Service |
aee942 |
#define _ifd_handler_h_
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#include <pcsclite.h>
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* List of data structures available to ifdhandler
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
typedef struct _DEVICE_CAPABILITIES
|
|
Packit Service |
aee942 |
{
|
|
Packit Service |
aee942 |
LPSTR Vendor_Name; /**< Tag 0x0100 */
|
|
Packit Service |
aee942 |
LPSTR IFD_Type; /**< Tag 0x0101 */
|
|
Packit Service |
aee942 |
DWORD IFD_Version; /**< Tag 0x0102 */
|
|
Packit Service |
aee942 |
LPSTR IFD_Serial; /**< Tag 0x0103 */
|
|
Packit Service |
aee942 |
DWORD IFD_Channel_ID; /**< Tag 0x0110 */
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
DWORD Asynch_Supported; /**< Tag 0x0120 */
|
|
Packit Service |
aee942 |
DWORD Default_Clock; /**< Tag 0x0121 */
|
|
Packit Service |
aee942 |
DWORD Max_Clock; /**< Tag 0x0122 */
|
|
Packit Service |
aee942 |
DWORD Default_Data_Rate; /**< Tag 0x0123 */
|
|
Packit Service |
aee942 |
DWORD Max_Data_Rate; /**< Tag 0x0124 */
|
|
Packit Service |
aee942 |
DWORD Max_IFSD; /**< Tag 0x0125 */
|
|
Packit Service |
aee942 |
DWORD Synch_Supported; /**< Tag 0x0126 */
|
|
Packit Service |
aee942 |
DWORD Power_Mgmt; /**< Tag 0x0131 */
|
|
Packit Service |
aee942 |
DWORD Card_Auth_Devices; /**< Tag 0x0140 */
|
|
Packit Service |
aee942 |
DWORD User_Auth_Device; /**< Tag 0x0142 */
|
|
Packit Service |
aee942 |
DWORD Mechanics_Supported; /**< Tag 0x0150 */
|
|
Packit Service |
aee942 |
DWORD Vendor_Features; /**< Tag 0x0180 - 0x01F0 User Defined. */
|
|
Packit Service |
aee942 |
}
|
|
Packit Service |
aee942 |
DEVICE_CAPABILITIES, *PDEVICE_CAPABILITIES;
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
typedef struct _ICC_STATE
|
|
Packit Service |
aee942 |
{
|
|
Packit Service |
aee942 |
UCHAR ICC_Presence; /**< Tag 0x0300 */
|
|
Packit Service |
aee942 |
UCHAR ICC_Interface_Status; /**< Tag 0x0301 */
|
|
Packit Service |
aee942 |
UCHAR ATR[MAX_ATR_SIZE]; /**< Tag 0x0303 */
|
|
Packit Service |
aee942 |
UCHAR ICC_Type; /**< Tag 0x0304 */
|
|
Packit Service |
aee942 |
}
|
|
Packit Service |
aee942 |
ICC_STATE, *PICC_STATE;
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
typedef struct _PROTOCOL_OPTIONS
|
|
Packit Service |
aee942 |
{
|
|
Packit Service |
aee942 |
DWORD Protocol_Type; /**< Tag 0x0201 */
|
|
Packit Service |
aee942 |
DWORD Current_Clock; /**< Tag 0x0202 */
|
|
Packit Service |
aee942 |
DWORD Current_F; /**< Tag 0x0203 */
|
|
Packit Service |
aee942 |
DWORD Current_D; /**< Tag 0x0204 */
|
|
Packit Service |
aee942 |
DWORD Current_N; /**< Tag 0x0205 */
|
|
Packit Service |
aee942 |
DWORD Current_W; /**< Tag 0x0206 */
|
|
Packit Service |
aee942 |
DWORD Current_IFSC; /**< Tag 0x0207 */
|
|
Packit Service |
aee942 |
DWORD Current_IFSD; /**< Tag 0x0208 */
|
|
Packit Service |
aee942 |
DWORD Current_BWT; /**< Tag 0x0209 */
|
|
Packit Service |
aee942 |
DWORD Current_CWT; /**< Tag 0x020A */
|
|
Packit Service |
aee942 |
DWORD Current_EBC; /**< Tag 0x020B */
|
|
Packit Service |
aee942 |
}
|
|
Packit Service |
aee942 |
PROTOCOL_OPTIONS, *PPROTOCOL_OPTIONS;
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
* Use by SCardTransmit()
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
typedef struct _SCARD_IO_HEADER
|
|
Packit Service |
aee942 |
{
|
|
Packit Service |
aee942 |
DWORD Protocol;
|
|
Packit Service |
aee942 |
DWORD Length;
|
|
Packit Service |
aee942 |
}
|
|
Packit Service |
aee942 |
SCARD_IO_HEADER, *PSCARD_IO_HEADER;
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* The list of tags should be alot more but this is all I use in the
|
|
Packit Service |
aee942 |
* meantime
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
#define TAG_IFD_ATR 0x0303 /**< ATR */
|
|
Packit Service |
aee942 |
#define TAG_IFD_SLOTNUM 0x0180 /**< select a slot */
|
|
Packit Service |
aee942 |
#define TAG_IFD_SLOT_THREAD_SAFE 0x0FAC /**< support access to different slots of the reader */
|
|
Packit Service |
aee942 |
#define TAG_IFD_THREAD_SAFE 0x0FAD /**< driver is thread safe */
|
|
Packit Service |
aee942 |
#define TAG_IFD_SLOTS_NUMBER 0x0FAE /**< number of slots of the reader */
|
|
Packit Service |
aee942 |
#define TAG_IFD_SIMULTANEOUS_ACCESS 0x0FAF /**< number of reader the driver can manage */
|
|
Packit Service |
aee942 |
#define TAG_IFD_POLLING_THREAD 0x0FB0 /**< not used. See TAG_IFD_POLLING_THREAD_WITH_TIMEOUT */
|
|
Packit Service |
aee942 |
#define TAG_IFD_POLLING_THREAD_KILLABLE 0x0FB1 /**< the polling thread can be killed */
|
|
Packit Service |
aee942 |
#define TAG_IFD_STOP_POLLING_THREAD 0x0FB2 /**< method used to stop the polling thread (instead of just pthread_kill()) */
|
|
Packit Service |
aee942 |
#define TAG_IFD_POLLING_THREAD_WITH_TIMEOUT 0x0FB3 /**< driver uses a polling thread with a timeout parameter */
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* IFD Handler version number enummerations
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
#define IFD_HVERSION_1_0 0x00010000
|
|
Packit Service |
aee942 |
#define IFD_HVERSION_2_0 0x00020000
|
|
Packit Service |
aee942 |
#define IFD_HVERSION_3_0 0x00030000
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* List of defines available to ifdhandler
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
#define IFD_POWER_UP 500 /**< power up the card */
|
|
Packit Service |
aee942 |
#define IFD_POWER_DOWN 501 /**< power down the card */
|
|
Packit Service |
aee942 |
#define IFD_RESET 502 /**< warm reset */
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#define IFD_NEGOTIATE_PTS1 1 /**< negotiate PTS1 */
|
|
Packit Service |
aee942 |
#define IFD_NEGOTIATE_PTS2 2 /**< negotiate PTS2 */
|
|
Packit Service |
aee942 |
#define IFD_NEGOTIATE_PTS3 4 /**< negotiate PTS3 */
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#define IFD_SUCCESS 0 /**< no error */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_TAG 600 /**< tag unknown */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_SET_FAILURE 601 /**< set failed */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_VALUE_READ_ONLY 602 /**< value is read only */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_PTS_FAILURE 605 /**< failed to negotiate PTS */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_NOT_SUPPORTED 606
|
|
Packit Service |
aee942 |
#define IFD_PROTOCOL_NOT_SUPPORTED 607 /**< requested protocol not supported */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_POWER_ACTION 608 /**< power up failed */
|
|
Packit Service |
aee942 |
#define IFD_ERROR_SWALLOW 609
|
|
Packit Service |
aee942 |
#define IFD_ERROR_EJECT 610
|
|
Packit Service |
aee942 |
#define IFD_ERROR_CONFISCATE 611
|
|
Packit Service |
aee942 |
#define IFD_COMMUNICATION_ERROR 612 /**< generic error */
|
|
Packit Service |
aee942 |
#define IFD_RESPONSE_TIMEOUT 613 /**< timeout */
|
|
Packit Service |
aee942 |
#define IFD_NOT_SUPPORTED 614 /**< request is not supported */
|
|
Packit Service |
aee942 |
#define IFD_ICC_PRESENT 615 /**< card is present */
|
|
Packit Service |
aee942 |
#define IFD_ICC_NOT_PRESENT 616 /**< card is absent */
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
* The \ref IFD_NO_SUCH_DEVICE error must be returned by the driver when
|
|
Packit Service |
aee942 |
* it detects the reader is no more present. This will tell pcscd to
|
|
Packit Service |
aee942 |
* remove the reader from the list of available readers.
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
#define IFD_NO_SUCH_DEVICE 617
|
|
Packit Service |
aee942 |
#define IFD_ERROR_INSUFFICIENT_BUFFER 618 /**< buffer is too small */
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#ifndef RESPONSECODE_DEFINED_IN_WINTYPES_H
|
|
Packit Service |
aee942 |
typedef long RESPONSECODE;
|
|
Packit Service |
aee942 |
#endif
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* If you want to compile a V2.0 IFDHandler, define IFDHANDLERv2
|
|
Packit Service |
aee942 |
* before you include this file.
|
|
Packit Service |
aee942 |
*
|
|
Packit Service |
aee942 |
* By default it is setup for for most recent version of the API (V3.0)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#ifndef IFDHANDLERv2
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* List of Defined Functions Available to IFD_Handler 3.0
|
|
Packit Service |
aee942 |
*
|
|
Packit Service |
aee942 |
* All the functions of IFD_Handler 2.0 are available
|
|
Packit Service |
aee942 |
* IFDHCreateChannelByName() is new
|
|
Packit Service |
aee942 |
* IFDHControl() API changed
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function is required to open a communications channel to the port
|
|
Packit Service |
aee942 |
listed by @p DeviceName.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Once the channel is opened the reader must be in a state in which it is
|
|
Packit Service |
aee942 |
possible to query IFDHICCPresence() for card status.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number\n
|
|
Packit Service |
aee942 |
Use this for multiple card slots or multiple readers. 0xXXXXYYYY -
|
|
Packit Service |
aee942 |
XXXX multiple readers, YYYY multiple slots. The resource manager will
|
|
Packit Service |
aee942 |
set these automatically. By default the resource manager loads a new
|
|
Packit Service |
aee942 |
instance of the driver so if your reader does not have more than one
|
|
Packit Service |
aee942 |
smart card slot then ignore the Lun in all the functions.\n
|
|
Packit Service |
aee942 |
\n
|
|
Packit Service |
aee942 |
PC/SC supports the loading of multiple readers through one instance of
|
|
Packit Service |
aee942 |
the driver in which XXXX is important. XXXX identifies the unique
|
|
Packit Service |
aee942 |
reader in which the driver communicates to. The driver should set up
|
|
Packit Service |
aee942 |
an array of structures that asociate this XXXX with the underlying
|
|
Packit Service |
aee942 |
details of the particular reader.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@param[in] DeviceName Filename to use by the driver.\n
|
|
Packit Service |
aee942 |
For drivers configured by @p /etc/reader.conf this is the value of the
|
|
Packit Service |
aee942 |
field \ref DEVICENAME.
|
|
Packit Service |
aee942 |
\n
|
|
Packit Service |
aee942 |
For USB drivers the @p DeviceName must start with @p usb:VID/PID. VID
|
|
Packit Service |
aee942 |
is the Vendor ID and PID is the Product ID. Both are a 4-digits hex
|
|
Packit Service |
aee942 |
number.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Typically the string is generated by:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@code
|
|
Packit Service |
aee942 |
printf("usb:%04x/%04x", idVendor, idProduct);
|
|
Packit Service |
aee942 |
@endcode
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The @p DeviceName string may also contain a more specialised
|
|
Packit Service |
aee942 |
identification string. This additional information is used to
|
|
Packit Service |
aee942 |
differentiate between two identical readers connected at the same time.
|
|
Packit Service |
aee942 |
In this case the driver can't differentiate the two readers using VID
|
|
Packit Service |
aee942 |
and PID and must use some additional information identifying the USB
|
|
Packit Service |
aee942 |
port used by each reader.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
- libusb
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
For USB drivers using libusb-1.0 http://libusb.sourceforge.net/ for USB
|
|
Packit Service |
aee942 |
abstraction the @p DeviceName the string may be generated by:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@code
|
|
Packit Service |
aee942 |
printf("usb:%04x/%04x:libusb-1.0:%d:%d:%d",
|
|
Packit Service |
aee942 |
idVendor, idProduct, bus_number, device_address, interface)
|
|
Packit Service |
aee942 |
@endcode
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
So it is something like: <tt>usb:08e6/3437:libusb-1.0:7:99:0</tt> under
|
|
Packit Service |
aee942 |
GNU/Linux.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
- libudev
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
If pcscd is compiled with libudev support instead of libusb (default
|
|
Packit Service |
aee942 |
since pcsc-lite 1.6.8) the string will look like:
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@code
|
|
Packit Service |
aee942 |
printf("usb:%04x/%04x:libudev:%d:%s", idVendor, idProduct,
|
|
Packit Service |
aee942 |
bInterfaceNumber, devpath);
|
|
Packit Service |
aee942 |
@endcode
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
bInterfaceNumber is the number of the interface on the device. It is
|
|
Packit Service |
aee942 |
only usefull for devices with more than one CCID interface.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
devpath is the filename of the device on the file system.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
So it is something like:
|
|
Packit Service |
aee942 |
<tt>usb:08e6/3437:libudev:0:/dev/bus/usb/008/047</tt>
|
|
Packit Service |
aee942 |
under GNU/Linux.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
- other
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
If the driver does not understand the <tt>:libusb:</tt> or
|
|
Packit Service |
aee942 |
<tt>:libudev:</tt> scheme or if a new scheme is used, the driver should
|
|
Packit Service |
aee942 |
ignore the part it does not understand instead of failing.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
The driver shall recognize the <tt>usb:VID/PID</tt> part and, only if
|
|
Packit Service |
aee942 |
possible, the remaining of the DeviceName field.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
It is the responsibility of the driver to correctly identify the reader.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHCreateChannelByName(DWORD Lun, LPSTR DeviceName);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function performs a data exchange with the reader (not the card)
|
|
Packit Service |
aee942 |
specified by Lun. It is responsible for abstracting functionality such
|
|
Packit Service |
aee942 |
as PIN pads, biometrics, LCD panels, etc. You should follow the MCT and
|
|
Packit Service |
aee942 |
CTBCS specifications for a list of accepted commands to implement. This
|
|
Packit Service |
aee942 |
function is fully voluntary and does not have to be implemented unless
|
|
Packit Service |
aee942 |
you want extended functionality.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
@param[in] dwControlCode Control code for the operation\n
|
|
Packit Service |
aee942 |
This value identifies the specific operation to be performed. This
|
|
Packit Service |
aee942 |
value is driver specific.
|
|
Packit Service |
aee942 |
@param[in] TxBuffer Transmit data
|
|
Packit Service |
aee942 |
@param[in] TxLength Length of this buffer
|
|
Packit Service |
aee942 |
@param[out] RxBuffer Receive data
|
|
Packit Service |
aee942 |
@param[in] RxLength Length of the response buffer
|
|
Packit Service |
aee942 |
@param[out] pdwBytesReturned Length of response\n
|
|
Packit Service |
aee942 |
This function will be passed the length of the buffer RxBuffer in
|
|
Packit Service |
aee942 |
RxLength and it must set the length of the received data in
|
|
Packit Service |
aee942 |
pdwBytesReturned.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@note
|
|
Packit Service |
aee942 |
@p *pdwBytesReturned should be set to zero on error.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHControl(DWORD Lun, DWORD dwControlCode, PUCHAR
|
|
Packit Service |
aee942 |
TxBuffer, DWORD TxLength, PUCHAR RxBuffer, DWORD RxLength,
|
|
Packit Service |
aee942 |
LPDWORD pdwBytesReturned);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#else
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
* Available in IFD_Handler 2.0
|
|
Packit Service |
aee942 |
*
|
|
Packit Service |
aee942 |
* @deprecated
|
|
Packit Service |
aee942 |
* You should use the new form of IFDHControl()
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHControl(DWORD Lun, PUCHAR TxBuffer, DWORD TxLength,
|
|
Packit Service |
aee942 |
PUCHAR RxBuffer, PDWORD RxLength);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#endif
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/*
|
|
Packit Service |
aee942 |
* common functions in IFD_Handler 2.0 and 3.0
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function is required to open a communications channel to the port
|
|
Packit Service |
aee942 |
listed by Channel. For example, the first serial reader on COM1 would
|
|
Packit Service |
aee942 |
link to @p /dev/pcsc/1 which would be a symbolic link to @p /dev/ttyS0
|
|
Packit Service |
aee942 |
on some machines This is used to help with inter-machine independence.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
On machines with no /dev directory the driver writer may choose to map
|
|
Packit Service |
aee942 |
their Channel to whatever they feel is appropriate.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
Once the channel is opened the reader must be in a state in which it is
|
|
Packit Service |
aee942 |
possible to query IFDHICCPresence() for card status.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
USB readers can ignore the @p Channel parameter and query the USB bus
|
|
Packit Service |
aee942 |
for the particular reader by manufacturer and product id.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number\n
|
|
Packit Service |
aee942 |
Use this for multiple card slots or multiple readers. 0xXXXXYYYY -
|
|
Packit Service |
aee942 |
XXXX multiple readers, YYYY multiple slots. The resource manager will
|
|
Packit Service |
aee942 |
set these automatically. By default the resource manager loads a new
|
|
Packit Service |
aee942 |
instance of the driver so if your reader does not have more than one
|
|
Packit Service |
aee942 |
smart card slot then ignore the Lun in all the functions.\n
|
|
Packit Service |
aee942 |
\n
|
|
Packit Service |
aee942 |
PC/SC supports the loading of multiple readers through one instance of
|
|
Packit Service |
aee942 |
the driver in which XXXX is important. XXXX identifies the unique
|
|
Packit Service |
aee942 |
reader in which the driver communicates to. The driver should set up
|
|
Packit Service |
aee942 |
an array of structures that associate this XXXX with the underlying
|
|
Packit Service |
aee942 |
details of the particular reader.
|
|
Packit Service |
aee942 |
@param[in] Channel Channel ID
|
|
Packit Service |
aee942 |
This is denoted by the following:
|
|
Packit Service |
aee942 |
- 0x000001 @p /dev/pcsc/1
|
|
Packit Service |
aee942 |
- 0x000002 @p /dev/pcsc/2
|
|
Packit Service |
aee942 |
- 0x000003 @p /dev/pcsc/3
|
|
Packit Service |
aee942 |
- 0x000004 @p /dev/pcsc/4
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHCreateChannel(DWORD Lun, DWORD Channel);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function should close the reader communication channel for the
|
|
Packit Service |
aee942 |
particular reader. Prior to closing the communication channel the reader
|
|
Packit Service |
aee942 |
should make sure the card is powered down and the terminal is also
|
|
Packit Service |
aee942 |
powered down.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHCloseChannel(DWORD Lun);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function should get the slot/card capabilities for a particular
|
|
Packit Service |
aee942 |
slot/card specified by Lun. Again, if you have only 1 card slot and
|
|
Packit Service |
aee942 |
don't mind loading a new driver for each reader then ignore Lun.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
@param[in] Tag Tag of the desired data value
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_ATR
|
|
Packit Service |
aee942 |
Return the ATR and its size (implementation is mandatory).
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_SLOTNUM
|
|
Packit Service |
aee942 |
Unused/deprecated
|
|
Packit Service |
aee942 |
- \ref SCARD_ATTR_ATR_STRING
|
|
Packit Service |
aee942 |
Same as \ref TAG_IFD_ATR but this one is not mandatory. It is defined
|
|
Packit Service |
aee942 |
in Microsoft PC/SC SCardGetAttrib().
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_SIMULTANEOUS_ACCESS
|
|
Packit Service |
aee942 |
Return the number of sessions (readers) the driver can handle in
|
|
Packit Service |
aee942 |
<tt>Value[0]</tt>.
|
|
Packit Service |
aee942 |
This is used for multiple readers sharing the same driver.
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_THREAD_SAFE
|
|
Packit Service |
aee942 |
If the driver supports more than one reader (see
|
|
Packit Service |
aee942 |
\ref TAG_IFD_SIMULTANEOUS_ACCESS above) this tag indicates if the
|
|
Packit Service |
aee942 |
driver supports access to multiple readers at the same time.\n
|
|
Packit Service |
aee942 |
<tt>Value[0] = 1</tt> indicates the driver supports simultaneous accesses.
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_SLOTS_NUMBER
|
|
Packit Service |
aee942 |
Return the number of slots in this reader in <tt>Value[0]</tt>.
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_SLOT_THREAD_SAFE
|
|
Packit Service |
aee942 |
If the reader has more than one slot (see \ref TAG_IFD_SLOTS_NUMBER
|
|
Packit Service |
aee942 |
above) this tag indicates if the driver supports access to multiple
|
|
Packit Service |
aee942 |
slots of the same reader at the same time.\n
|
|
Packit Service |
aee942 |
<tt>Value[0] = 1</tt> indicates the driver supports simultaneous slot
|
|
Packit Service |
aee942 |
accesses.
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_POLLING_THREAD
|
|
Packit Service |
aee942 |
Unused/deprecated
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_POLLING_THREAD_WITH_TIMEOUT
|
|
Packit Service |
aee942 |
If the driver provides a polling thread then @p Value is a pointer to
|
|
Packit Service |
aee942 |
this function. The function prototype is:
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
RESPONSECODE foo(DWORD Lun, int timeout);
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_POLLING_THREAD_KILLABLE
|
|
Packit Service |
aee942 |
Tell if the polling thread can be killed (pthread_kill()) by pcscd
|
|
Packit Service |
aee942 |
- \ref TAG_IFD_STOP_POLLING_THREAD
|
|
Packit Service |
aee942 |
Returns a pointer in @p Value to the function used to stop the polling
|
|
Packit Service |
aee942 |
thread returned by \ref TAG_IFD_POLLING_THREAD_WITH_TIMEOUT. The
|
|
Packit Service |
aee942 |
function prototype is:
|
|
Packit Service |
aee942 |
@verbatim
|
|
Packit Service |
aee942 |
RESPONSECODE foo(DWORD Lun);
|
|
Packit Service |
aee942 |
@endverbatim
|
|
Packit Service |
aee942 |
@param[in,out] Length Length of the desired data value
|
|
Packit Service |
aee942 |
@param[out] Value Value of the desired data
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHGetCapabilities(DWORD Lun, DWORD Tag, PDWORD Length,
|
|
Packit Service |
aee942 |
PUCHAR Value);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function should set the slot/card capabilities for a particular
|
|
Packit Service |
aee942 |
slot/card specified by @p Lun. Again, if you have only 1 card slot and
|
|
Packit Service |
aee942 |
don't mind loading a new driver for each reader then ignore @p Lun.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
@param[in] Tag Tag of the desired data value
|
|
Packit Service |
aee942 |
@param[in,out] Length Length of the desired data value
|
|
Packit Service |
aee942 |
@param[out] Value Value of the desired data
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
This function is also called when the application uses the PC/SC
|
|
Packit Service |
aee942 |
SCardGetAttrib() function. The list of supported tags is not limited.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG)
|
|
Packit Service |
aee942 |
@retval IFD_ERROR_SET_FAILURE Could not set value (\ref IFD_ERROR_SET_FAILURE)
|
|
Packit Service |
aee942 |
@retval IFD_ERROR_VALUE_READ_ONLY Trying to set read only value (\ref IFD_ERROR_VALUE_READ_ONLY)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHSetCapabilities(DWORD Lun, DWORD Tag, DWORD Length, PUCHAR Value);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function should set the Protocol Type Selection (PTS) of a
|
|
Packit Service |
aee942 |
particular card/slot using the three PTS parameters sent
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
@param[in] Protocol Desired protocol
|
|
Packit Service |
aee942 |
- \ref SCARD_PROTOCOL_T0
|
|
Packit Service |
aee942 |
T=0 protocol
|
|
Packit Service |
aee942 |
- \ref SCARD_PROTOCOL_T1
|
|
Packit Service |
aee942 |
T=1 protocol
|
|
Packit Service |
aee942 |
@param[in] Flags Logical OR of possible values to determine which PTS values
|
|
Packit Service |
aee942 |
to negotiate
|
|
Packit Service |
aee942 |
- \ref IFD_NEGOTIATE_PTS1
|
|
Packit Service |
aee942 |
- \ref IFD_NEGOTIATE_PTS2
|
|
Packit Service |
aee942 |
- \ref IFD_NEGOTIATE_PTS3
|
|
Packit Service |
aee942 |
@param[in] PTS1 1st PTS Value
|
|
Packit Service |
aee942 |
@param[in] PTS2 2nd PTS Value
|
|
Packit Service |
aee942 |
@param[in] PTS3 3rd PTS Value\n
|
|
Packit Service |
aee942 |
See ISO 7816/EMV documentation.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_ERROR_PTS_FAILURE Could not set PTS value (\ref IFD_ERROR_PTS_FAILURE)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_PROTOCOL_NOT_SUPPORTED Protocol is not supported (\ref IFD_PROTOCOL_NOT_SUPPORTED)
|
|
Packit Service |
aee942 |
@retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHSetProtocolParameters(DWORD Lun, DWORD Protocol, UCHAR Flags,
|
|
Packit Service |
aee942 |
UCHAR PTS1, UCHAR PTS2, UCHAR PTS3);
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function controls the power and reset signals of the smart card
|
|
Packit Service |
aee942 |
reader at the particular reader/slot specified by @p Lun.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
@param[in] Action Action to be taken on the card
|
|
Packit Service |
aee942 |
- \ref IFD_POWER_UP
|
|
Packit Service |
aee942 |
Power up the card (store and return Atr and AtrLength)
|
|
Packit Service |
aee942 |
- \ref IFD_POWER_DOWN
|
|
Packit Service |
aee942 |
Power down the card (Atr and AtrLength should be zeroed)
|
|
Packit Service |
aee942 |
- \ref IFD_RESET
|
|
Packit Service |
aee942 |
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)
|
|
Packit Service |
aee942 |
@param[out] Atr Answer to Reset (ATR) of the card\n
|
|
Packit Service |
aee942 |
The driver is responsible for caching this value in case
|
|
Packit Service |
aee942 |
IFDHGetCapabilities() is called requesting the ATR and its length. The
|
|
Packit Service |
aee942 |
ATR length should not exceed \ref MAX_ATR_SIZE.
|
|
Packit Service |
aee942 |
@param[in,out] AtrLength Length of the ATR\n
|
|
Packit Service |
aee942 |
This should not exceed \ref MAX_ATR_SIZE.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@note
|
|
Packit Service |
aee942 |
Memory cards without an ATR should return \ref IFD_SUCCESS on reset but the
|
|
Packit Service |
aee942 |
Atr should be zeroed and the length should be zero Reset errors should
|
|
Packit Service |
aee942 |
return zero for the AtrLength and return \ref IFD_ERROR_POWER_ACTION.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_ERROR_POWER_ACTION Error powering/resetting card (\ref IFD_ERROR_POWER_ACTION)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHPowerICC(DWORD Lun, DWORD Action, PUCHAR Atr, PDWORD
|
|
Packit Service |
aee942 |
AtrLength);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function performs an APDU exchange with the card/slot specified by
|
|
Packit Service |
aee942 |
Lun. The driver is responsible for performing any protocol specific
|
|
Packit Service |
aee942 |
exchanges such as T=0, 1, etc. differences. Calling this function will
|
|
Packit Service |
aee942 |
abstract all protocol differences.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
@param[in] SendPci contains two structure members
|
|
Packit Service |
aee942 |
- Protocol 0, 1, ... 14\n
|
|
Packit Service |
aee942 |
T=0 ... T=14
|
|
Packit Service |
aee942 |
- Length\n
|
|
Packit Service |
aee942 |
Not used.
|
|
Packit Service |
aee942 |
@param[in] TxBuffer Transmit APDU\n
|
|
Packit Service |
aee942 |
Example: "\x00\xA4\x00\x00\x02\x3F\x00"
|
|
Packit Service |
aee942 |
@param[in] TxLength Length of this buffer
|
|
Packit Service |
aee942 |
@param[out] RxBuffer Receive APDU\n
|
|
Packit Service |
aee942 |
Example: "\x61\x14"
|
|
Packit Service |
aee942 |
@param[in,out] RxLength Length of the received APDU\n
|
|
Packit Service |
aee942 |
This function will be passed the size of the buffer of RxBuffer and
|
|
Packit Service |
aee942 |
this function is responsible for setting this to the length of the
|
|
Packit Service |
aee942 |
received APDU response. This should be ZERO on all errors. The
|
|
Packit Service |
aee942 |
resource manager will take responsibility of zeroing out any temporary
|
|
Packit Service |
aee942 |
APDU buffers for security reasons.
|
|
Packit Service |
aee942 |
@param[out] RecvPci contains two structure members
|
|
Packit Service |
aee942 |
- Protocol - 0, 1, ... 14\n
|
|
Packit Service |
aee942 |
T=0 ... T=14
|
|
Packit Service |
aee942 |
- Length\n
|
|
Packit Service |
aee942 |
Not used.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@note
|
|
Packit Service |
aee942 |
The driver is responsible for knowing what type of card it has. If the
|
|
Packit Service |
aee942 |
current slot/card contains a memory card then this command should ignore
|
|
Packit Service |
aee942 |
the Protocol and use the MCT style commands for support for these style
|
|
Packit Service |
aee942 |
cards and transmit them appropriately. If your reader does not support
|
|
Packit Service |
aee942 |
memory cards or you don't want to implement this functionality, then
|
|
Packit Service |
aee942 |
ignore this.
|
|
Packit Service |
aee942 |
@par
|
|
Packit Service |
aee942 |
RxLength should be set to zero on error.
|
|
Packit Service |
aee942 |
@par
|
|
Packit Service |
aee942 |
The driver is not responsible for doing an automatic Get Response
|
|
Packit Service |
aee942 |
command for received buffers containing 61 XX.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT)
|
|
Packit Service |
aee942 |
@retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT)
|
|
Packit Service |
aee942 |
@retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHTransmitToICC(DWORD Lun, SCARD_IO_HEADER SendPci,
|
|
Packit Service |
aee942 |
PUCHAR TxBuffer, DWORD TxLength, PUCHAR RxBuffer, PDWORD
|
|
Packit Service |
aee942 |
RxLength, PSCARD_IO_HEADER RecvPci);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
/**
|
|
Packit Service |
aee942 |
This function returns the status of the card inserted in the reader/slot
|
|
Packit Service |
aee942 |
specified by @p Lun. In cases where the device supports asynchronous
|
|
Packit Service |
aee942 |
card insertion/removal detection, it is advised that the driver manages
|
|
Packit Service |
aee942 |
this through a thread so the driver does not have to send and receive a
|
|
Packit Service |
aee942 |
command each time this function is called.
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@ingroup IFDHandler
|
|
Packit Service |
aee942 |
@param[in] Lun Logical Unit Number
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
@return Error codes
|
|
Packit Service |
aee942 |
@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
|
|
Packit Service |
aee942 |
@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
|
|
Packit Service |
aee942 |
@retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT)
|
|
Packit Service |
aee942 |
@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
|
|
Packit Service |
aee942 |
*/
|
|
Packit Service |
aee942 |
RESPONSECODE IFDHICCPresence(DWORD Lun);
|
|
Packit Service |
aee942 |
|
|
Packit Service |
aee942 |
#endif
|