MacOSX/ifdhandler.h

   1 /*
   2  * MUSCLE SmartCard Development ( https://pcsclite.apdu.fr/ )
   3  *
   4  * Copyright (C) 1999-2004
   5  *  David Corcoran <corcoran@musclecard.com>
   6  * Copyright (C) 2003-2004
   7  *  Damien Sauveron <damien.sauveron@labri.fr>
   8  * Copyright (C) 2002-2011
   9  *  Ludovic Rousseau <ludovic.rousseau@free.fr>
  10  *
  11 Redistribution and use in source and binary forms, with or without
  12 modification, are permitted provided that the following conditions
  13 are met:
  14
  15 1. Redistributions of source code must retain the above copyright
  16    notice, this list of conditions and the following disclaimer.
  17 2. Redistributions in binary form must reproduce the above copyright
  18    notice, this list of conditions and the following disclaimer in the
  19    documentation and/or other materials provided with the distribution.
  20 3. The name of the author may not be used to endorse or promote products
  21    derived from this software without specific prior written permission.
  22
  23 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  24 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  25 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  26 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  27 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  28 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  32 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 /**
  36  * @file
  37  * @defgroup IFDHandler IFDHandler
  38  * @brief This provides reader specific low-level calls.
  39
  40 The routines specified hereafter will allow you to write an IFD handler
  41 for the PC/SC Lite resource manager. Please use the complement
  42 developer's kit complete with headers and Makefile at:
  43 https://muscle.apdu.fr/musclecard.com/sourcedrivers.html
  44
  45 This gives a common API for communication to most readers in a
  46 homogeneous fashion. This document assumes that the driver developer is
  47 experienced with standards such as ISO-7816-(1, 2, 3, 4), EMV and MCT
  48 specifications. For listings of these specifications please access the
  49 above web site.
  50
  51 @section UsbReaders USB readers
  52
  53 USB readers use the bundle approach so that the reader can be loaded
  54 and unloaded upon automatic detection of the device. The bundle
  55 approach is simple: the actual library is just embedded in a
  56 directory so additional information can be gathered about the device.
  57
  58 A bundle looks like the following:
  59
  60 @verbatim
  61 GenericReader.bundle/
  62   Contents/
  63     Info.plist  - XML file describing the reader
  64     MacOS/      - Driver directory for OS X
  65     Solaris/    - Driver directory for Solaris
  66     Linux/      - Driver directory for Linux
  67     HPUX/       - Driver directory for HPUX
  68 @endverbatim
  69
  70 The @c Info.plist file describes the driver and gives the loader
  71 all the necessary information. The following must be contained in the
  72 @c Info.plist file:
  73
  74 @subsection ifdVendorID
  75
  76 The vendor ID of the USB device.
  77
  78 Example:
  79
  80 @verbatim
  81     <key>ifdVendorID</key>
  82     <string>0x04E6</string>
  83 @endverbatim
  84
  85 You may have an OEM of this reader in which an additional @c \<string>
  86 can be used like in the below example:
  87
  88 @verbatim
  89     <key>ifdVendorID</key>
  90     <array>
  91       <string>0x04E6</string>
  92       <string>0x0973</string>
  93     </array>
  94 @endverbatim
  95
  96 If multiples exist all the other parameters must have a second value
  97 also. You may chose not to support this feature but it is useful when
  98 reader vendors OEM products so you only distribute one driver.
  99
 100
 101 The CCID driver from Ludovic Rousseau https://ccid.apdu.fr/ uses this
 102 feature since the same driver supports many different readers.
 103
 104 @subsection ifdProductID
 105
 106    The product id of the USB device.
 107
 108 @verbatim
 109    <key>ifdProductID</key>
 110    <string>0x3437</string>
 111 @endverbatim
 112
 113 @subsection ifdFriendlyName
 114
 115    Example:
 116
 117 @verbatim
 118    <key>ifdFriendlyName</key>
 119    <string>SCM Microsystems USB Reader</string>
 120 @endverbatim
 121
 122 The reader name must use the ASCII character set.
 123
 124 @subsection CFBundleExecutable
 125
 126    The executable name which exists in the particular platform's directory.
 127
 128    Example:
 129
 130 @verbatim
 131    <key>CFBundleExecutable</key>
 132    <string>libccid.so.0.4.2</string>
 133 @endverbatim
 134
 135 @subsection ifdCapabilities
 136
 137    List of capabilities supported by the driver. This is a bit field. Possible values are:
 138
 139 - 0
 140   No special capabilities
 141 - 1 IFD_GENERATE_HOTPLUG
 142   The driver supports the hot plug feature.
 143
 144 Complete sample file:
 145
 146 @verbatim
 147 <?xml version="1.0" encoding="UTF-8"?>
 148 <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
 149     "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 150 <plist version="1.0">
 151 <dict>
 152     <key>CFBundleDevelopmentRegion</key>
 153     <string>English</string>
 154     <key>CFBundleInfoDictionaryVersion</key>
 155     <string>6.0</string>
 156     <key>CFBundlePackageType</key>
 157     <string>BNDL</string>
 158     <key>CFBundleSignature</key>
 159     <string>????</string>
 160     <key>CFBundleVersion</key>
 161     <string>0.0.1d1</string>
 162     <key>ifdCapabilities</key>
 163     <string>0x00000000</string>
 164     <key>ifdProtocolSupport</key>
 165     <string>0x00000001</string>
 166     <key>ifdVersionNumber</key>
 167     <string>0x00000001</string>
 168
 169     <key>CFBundleExecutable</key>
 170     <string>libfoobar.so.x.y</string>
 171
 172     <key>ifdManufacturerString</key>
 173     <string>Foo bar inc.</string>
 174
 175     <key>ifdProductString</key>
 176     <string>Driver for Foobar reader, version x.y</string>
 177
 178     <key>ifdVendorID</key>
 179     <string>0x1234</string>
 180
 181     <key>ifdProductID</key>
 182     <string>0x5678</string>
 183
 184     <key>ifdFriendlyName</key>
 185     <string>Foobar USB reader</string>
 186 </dict>
 187 </plist>
 188 @endverbatim
 189
 190 As indicated in the XML file the DTD is available at
 191 http://www.apple.com/DTDs/PropertyList-1.0.dtd.
 192
 193 @section SerialReaders Serial readers
 194
 195 Serial drivers must be configured to operate on a particular port and
 196 respond to a particular name. The @c reader.conf file is used for this
 197 purpose.
 198
 199 It has the following syntax:
 200
 201 @verbatim
 202 # Configuration file for pcsc-lite
 203 # David Corcoran <corcoran@musclecard.com>
 204
 205 FRIENDLYNAME  "Generic Reader"
 206 DEVICENAME    /dev/ttyS0
 207 LIBPATH       /usr/lib/pcsc/drivers/libgen_ifd.so
 208 CHANNELID     1
 209 @endverbatim
 210
 211 The pound sign # denotes a comment.
 212
 213 @subsection FRIENDLYNAME
 214 The FRIENDLYNAME field is an arbitrary text used to identify the reader.
 215 This text is displayed by commands like @c pcsc_scan
 216 http://ludovic.rousseau.free.fr/softwares/pcsc-tools/ that prints the
 217 names of all the connected and detected readers.
 218
 219 @subsection DEVICENAME
 220 The DEVICENAME field was not used for old drivers (using the IFD handler
 221 version 2.0 or previous). It is now (IFD handler version 3.0) used to
 222 identify the physical port on which the reader is connected.  This is
 223 the device name of this port. It is dependent of the OS kernel. For
 224 example the first serial port device is called @c /dev/ttyS0 under Linux
 225 and @c /dev/cuaa0 under FreeBSD.
 226
 227 If you want to use IFDHCreateChannel() instead of
 228 IFDHCreateChannelByName() then do not use any DEVICENAME line in the
 229 configuration file.  IFDHCreateChannel() will then be called with the
 230 CHANNELID parameter.
 231
 232 @subsection LIBPATH
 233 The LIBPATH field is the filename of the driver code. The driver is a
 234 dynamically loaded piece of code (generally a @c drivername.so* file).
 235
 236 @subsection CHANNELID
 237 The CHANNELID is no more used for recent drivers (IFD handler 3.0) and
 238 has been superseded by DEVICENAME.
 239
 240 If you have an old driver this field is used to indicate the port to
 241 use. You should read your driver documentation to know what information
 242 is needed here. It should be the serial port number for a serial reader.
 243
 244 CHANNELID was the numeric version of the port in which the reader will
 245 be located. This may be done by a symbolic link where @c /dev/pcsc/1 is
 246 the first device which may be a symbolic link to @c /dev/ttyS0 or
 247 whichever location your reader resides.
 248
 249  */
 250
 251 #ifndef _ifd_handler_h_
 252 #define _ifd_handler_h_
 253
 254 #include <pcsclite.h>
 255
 256         /*
 257          * List of data structures available to ifdhandler
 258          */
 259         typedef struct _DEVICE_CAPABILITIES
 260         {
 261                 LPSTR Vendor_Name;              /**< Tag 0x0100 */
 262                 LPSTR IFD_Type;                 /**< Tag 0x0101 */
 263                 DWORD IFD_Version;              /**< Tag 0x0102 */
 264                 LPSTR IFD_Serial;               /**< Tag 0x0103 */
 265                 DWORD IFD_Channel_ID;   /**< Tag 0x0110 */
 266
 267                 DWORD Asynch_Supported; /**< Tag 0x0120 */
 268                 DWORD Default_Clock;    /**< Tag 0x0121 */
 269                 DWORD Max_Clock;                /**< Tag 0x0122 */
 270                 DWORD Default_Data_Rate;        /**< Tag 0x0123 */
 271                 DWORD Max_Data_Rate;    /**< Tag 0x0124 */
 272                 DWORD Max_IFSD;                 /**< Tag 0x0125 */
 273                 DWORD Synch_Supported;  /**< Tag 0x0126 */
 274                 DWORD Power_Mgmt;               /**< Tag 0x0131 */
 275                 DWORD Card_Auth_Devices;        /**< Tag 0x0140 */
 276                 DWORD User_Auth_Device; /**< Tag 0x0142 */
 277                 DWORD Mechanics_Supported;      /**< Tag 0x0150 */
 278                 DWORD Vendor_Features;  /**< Tag 0x0180 - 0x01F0 User Defined. */
 279         }
 280         DEVICE_CAPABILITIES, *PDEVICE_CAPABILITIES;
 281
 282         typedef struct _ICC_STATE
 283         {
 284                 UCHAR ICC_Presence;             /**< Tag 0x0300 */
 285                 UCHAR ICC_Interface_Status;     /**< Tag 0x0301 */
 286                 UCHAR ATR[MAX_ATR_SIZE];        /**< Tag 0x0303 */
 287                 UCHAR ICC_Type;                 /**< Tag 0x0304 */
 288         }
 289         ICC_STATE, *PICC_STATE;
 290
 291         typedef struct _PROTOCOL_OPTIONS
 292         {
 293                 DWORD Protocol_Type;    /**< Tag 0x0201 */
 294                 DWORD Current_Clock;    /**< Tag 0x0202 */
 295                 DWORD Current_F;                /**< Tag 0x0203 */
 296                 DWORD Current_D;                /**< Tag 0x0204 */
 297                 DWORD Current_N;                /**< Tag 0x0205 */
 298                 DWORD Current_W;                /**< Tag 0x0206 */
 299                 DWORD Current_IFSC;             /**< Tag 0x0207 */
 300                 DWORD Current_IFSD;             /**< Tag 0x0208 */
 301                 DWORD Current_BWT;              /**< Tag 0x0209 */
 302                 DWORD Current_CWT;              /**< Tag 0x020A */
 303                 DWORD Current_EBC;              /**< Tag 0x020B */
 304         }
 305         PROTOCOL_OPTIONS, *PPROTOCOL_OPTIONS;
 306
 307         /**
 308          * Use by SCardTransmit()
 309          */
 310         typedef struct _SCARD_IO_HEADER
 311         {
 312                 DWORD Protocol;
 313                 DWORD Length;
 314         }
 315         SCARD_IO_HEADER, *PSCARD_IO_HEADER;
 316
 317         /*
 318          * The list of tags should be alot more but this is all I use in the
 319          * meantime
 320          */
 321 #define TAG_IFD_ATR                     0x0303  /**< ATR */
 322 #define TAG_IFD_SLOTNUM                 0x0180  /**< select a slot */
 323 #define TAG_IFD_SLOT_THREAD_SAFE        0x0FAC  /**< support access to different slots of the reader */
 324 #define TAG_IFD_THREAD_SAFE             0x0FAD  /**< driver is thread safe */
 325 #define TAG_IFD_SLOTS_NUMBER            0x0FAE  /**< number of slots of the reader */
 326 #define TAG_IFD_SIMULTANEOUS_ACCESS     0x0FAF  /**< number of reader the driver can manage */
 327 #define TAG_IFD_POLLING_THREAD          0x0FB0  /**< not used. See TAG_IFD_POLLING_THREAD_WITH_TIMEOUT */
 328 #define TAG_IFD_POLLING_THREAD_KILLABLE 0x0FB1  /**< the polling thread can be killed */
 329 #define TAG_IFD_STOP_POLLING_THREAD     0x0FB2  /**< method used to stop the polling thread (instead of just pthread_kill()) */
 330 #define TAG_IFD_POLLING_THREAD_WITH_TIMEOUT 0x0FB3      /**< driver uses a polling thread with a timeout parameter */
 331
 332         /*
 333          * IFD Handler version number enummerations
 334          */
 335 #define IFD_HVERSION_1_0               0x00010000
 336 #define IFD_HVERSION_2_0               0x00020000
 337 #define IFD_HVERSION_3_0               0x00030000
 338
 339         /*
 340          * List of defines available to ifdhandler
 341          */
 342 #define IFD_POWER_UP                    500 /**< power up the card */
 343 #define IFD_POWER_DOWN                  501 /**< power down the card */
 344 #define IFD_RESET                       502 /**< warm reset */
 345
 346 #define IFD_NEGOTIATE_PTS1              1   /**< negotiate PTS1 */
 347 #define IFD_NEGOTIATE_PTS2              2   /**< negotiate PTS2 */
 348 #define IFD_NEGOTIATE_PTS3              4   /**< negotiate PTS3 */
 349
 350 #define IFD_SUCCESS                     0   /**< no error */
 351 #define IFD_ERROR_TAG                   600 /**< tag unknown */
 352 #define IFD_ERROR_SET_FAILURE           601 /**< set failed */
 353 #define IFD_ERROR_VALUE_READ_ONLY       602 /**< value is read only */
 354 #define IFD_ERROR_PTS_FAILURE           605 /**< failed to negotiate PTS */
 355 #define IFD_ERROR_NOT_SUPPORTED         606
 356 #define IFD_PROTOCOL_NOT_SUPPORTED      607 /**< requested protocol not supported */
 357 #define IFD_ERROR_POWER_ACTION          608 /**< power up failed */
 358 #define IFD_ERROR_SWALLOW               609
 359 #define IFD_ERROR_EJECT                 610
 360 #define IFD_ERROR_CONFISCATE            611
 361 #define IFD_COMMUNICATION_ERROR         612 /**< generic error */
 362 #define IFD_RESPONSE_TIMEOUT            613 /**< timeout */
 363 #define IFD_NOT_SUPPORTED               614 /**< request is not supported */
 364 #define IFD_ICC_PRESENT                 615 /**< card is present */
 365 #define IFD_ICC_NOT_PRESENT             616 /**< card is absent */
 366 /**
 367  * The \ref IFD_NO_SUCH_DEVICE error must be returned by the driver when
 368  * it detects the reader is no more present. This will tell pcscd to
 369  * remove the reader from the list of available readers.
 370  */
 371 #define IFD_NO_SUCH_DEVICE              617
 372 #define IFD_ERROR_INSUFFICIENT_BUFFER   618 /**< buffer is too small */
 373
 374 #ifndef RESPONSECODE_DEFINED_IN_WINTYPES_H
 375         typedef long RESPONSECODE;
 376 #endif
 377
 378         /*
 379          * If you want to compile a V2.0 IFDHandler, define IFDHANDLERv2
 380          * before you include this file.
 381          *
 382          * By default it is setup for for most recent version of the API (V3.0)
 383          */
 384
 385 #ifndef IFDHANDLERv2
 386
 387         /*
 388          * List of Defined Functions Available to IFD_Handler 3.0
 389          *
 390          * All the functions of IFD_Handler 2.0 are available
 391          * IFDHCreateChannelByName() is new
 392          * IFDHControl() API changed
 393          */
 394
 395 /**
 396 This function is required to open a communications channel to the port
 397 listed by @p DeviceName.
 398
 399 Once the channel is opened the reader must be in a state in which it is
 400 possible to query IFDHICCPresence() for card status.
 401
 402 @ingroup IFDHandler
 403 @param[in] Lun Logical Unit Number\n
 404   Use this for multiple card slots or multiple readers. 0xXXXXYYYY -
 405   XXXX multiple readers, YYYY multiple slots. The resource manager will
 406   set these automatically. By default the resource manager loads a new
 407   instance of the driver so if your reader does not have more than one
 408   smart card slot then ignore the Lun in all the functions.\n
 409   \n
 410   PC/SC supports the loading of multiple readers through one instance of
 411   the driver in which XXXX is important. XXXX identifies the unique
 412   reader in which the driver communicates to. The driver should set up
 413   an array of structures that asociate this XXXX with the underlying
 414   details of the particular reader.
 415
 416 @param[in] DeviceName Filename to use by the driver.\n
 417   For drivers configured by @p /etc/reader.conf this is the value of the
 418   field \ref DEVICENAME.
 419   \n
 420   For USB drivers the @p DeviceName must start with @p usb:VID/PID. VID
 421   is the Vendor ID and PID is the Product ID. Both are a 4-digits hex
 422   number.
 423
 424 Typically the string is generated by:
 425
 426 @code
 427 printf("usb:%04x/%04x", idVendor, idProduct);
 428 @endcode
 429
 430 The @p DeviceName string may also contain a more specialised
 431 identification string. This additional information is used to
 432 differentiate between two identical readers connected at the same time.
 433 In this case the driver can't differentiate the two readers using VID
 434 and PID and must use some additional information identifying the USB
 435 port used by each reader.
 436
 437 - libusb
 438
 439   For USB drivers using libusb-1.0 http://libusb.sourceforge.net/ for USB
 440   abstraction the @p DeviceName the string may be generated by:
 441
 442   @code
 443   printf("usb:%04x/%04x:libusb-1.0:%d:%d:%d",
 444     idVendor, idProduct, bus_number, device_address, interface)
 445   @endcode
 446
 447   So it is something like: <tt>usb:08e6/3437:libusb-1.0:7:99:0</tt> under
 448   GNU/Linux.
 449
 450 - libudev
 451
 452   If pcscd is compiled with libudev support instead of libusb (default
 453   since pcsc-lite 1.6.8) the string will look like:
 454
 455   @code
 456   printf("usb:%04x/%04x:libudev:%d:%s", idVendor, idProduct,
 457                 bInterfaceNumber, devpath);
 458   @endcode
 459
 460   bInterfaceNumber is the number of the interface on the device. It is
 461   only usefull for devices with more than one CCID interface.
 462
 463   devpath is the filename of the device on the file system.
 464
 465   So it is something like:
 466   <tt>usb:08e6/3437:libudev:0:/dev/bus/usb/008/047</tt>
 467   under GNU/Linux.
 468
 469 - other
 470
 471   If the driver does not understand the <tt>:libusb:</tt> or
 472   <tt>:libudev:</tt> scheme or if a new scheme is used, the driver should
 473   ignore the part it does not understand instead of failing.
 474
 475   The driver shall recognize the <tt>usb:VID/PID</tt> part and, only if
 476   possible, the remaining of the DeviceName field.
 477
 478   It is the responsibility of the driver to correctly identify the reader.
 479
 480 @return Error codes
 481 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 482 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 483 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 484   */
 485 RESPONSECODE IFDHCreateChannelByName(DWORD Lun, LPSTR DeviceName);
 486
 487 /**
 488 This function performs a data exchange with the reader (not the card)
 489 specified by Lun. It is responsible for abstracting functionality such
 490 as PIN pads, biometrics, LCD panels, etc. You should follow the MCT and
 491 CTBCS specifications for a list of accepted commands to implement. This
 492 function is fully voluntary and does not have to be implemented unless
 493 you want extended functionality.
 494
 495 @ingroup IFDHandler
 496 @param[in] Lun Logical Unit Number
 497 @param[in] dwControlCode Control code for the operation\n
 498   This value identifies the specific operation to be performed. This
 499   value is driver specific.
 500 @param[in] TxBuffer Transmit data
 501 @param[in] TxLength Length of this buffer
 502 @param[out] RxBuffer Receive data
 503 @param[in] RxLength Length of the response buffer
 504 @param[out] pdwBytesReturned Length of response\n
 505   This function will be passed the length of the buffer RxBuffer in
 506   RxLength and it must set the length of the received data in
 507   pdwBytesReturned.
 508
 509 @note
 510   @p *pdwBytesReturned should be set to zero on error.
 511
 512 @return Error codes
 513 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 514 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 515 @retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT)
 516 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 517  */
 518 RESPONSECODE IFDHControl(DWORD Lun, DWORD dwControlCode, PUCHAR
 519         TxBuffer, DWORD TxLength, PUCHAR RxBuffer, DWORD RxLength,
 520         LPDWORD pdwBytesReturned);
 521
 522 #else
 523
 524 /**
 525  * Available in IFD_Handler 2.0
 526  *
 527  * @deprecated
 528  * You should use the new form of IFDHControl()
 529  */
 530 RESPONSECODE IFDHControl(DWORD Lun, PUCHAR TxBuffer, DWORD TxLength,
 531         PUCHAR RxBuffer, PDWORD RxLength);
 532
 533 #endif
 534
 535         /*
 536          * common functions in IFD_Handler 2.0 and 3.0
 537          */
 538 /**
 539 This function is required to open a communications channel to the port
 540 listed by Channel. For example, the first serial reader on COM1 would
 541 link to @p /dev/pcsc/1 which would be a symbolic link to @p /dev/ttyS0
 542 on some machines This is used to help with inter-machine independence.
 543
 544 On machines with no /dev directory the driver writer may choose to map
 545 their Channel to whatever they feel is appropriate.
 546
 547 Once the channel is opened the reader must be in a state in which it is
 548 possible to query IFDHICCPresence() for card status.
 549
 550 USB readers can ignore the @p Channel parameter and query the USB bus
 551 for the particular reader by manufacturer and product id.
 552
 553 @ingroup IFDHandler
 554 @param[in] Lun Logical Unit Number\n
 555   Use this for multiple card slots or multiple readers. 0xXXXXYYYY -
 556   XXXX multiple readers, YYYY multiple slots. The resource manager will
 557   set these automatically. By default the resource manager loads a new
 558   instance of the driver so if your reader does not have more than one
 559   smart card slot then ignore the Lun in all the functions.\n
 560   \n
 561   PC/SC supports the loading of multiple readers through one instance of
 562   the driver in which XXXX is important. XXXX identifies the unique
 563   reader in which the driver communicates to. The driver should set up
 564   an array of structures that associate this XXXX with the underlying
 565   details of the particular reader.
 566 @param[in] Channel Channel ID
 567   This is denoted by the following:
 568   - 0x000001    @p /dev/pcsc/1
 569   - 0x000002    @p /dev/pcsc/2
 570   - 0x000003    @p /dev/pcsc/3
 571   - 0x000004    @p /dev/pcsc/4
 572
 573 @return Error codes
 574 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 575 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 576 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 577
 578  */
 579 RESPONSECODE IFDHCreateChannel(DWORD Lun, DWORD Channel);
 580
 581 /**
 582 This function should close the reader communication channel for the
 583 particular reader. Prior to closing the communication channel the reader
 584 should make sure the card is powered down and the terminal is also
 585 powered down.
 586
 587 @ingroup IFDHandler
 588 @param[in] Lun Logical Unit Number
 589
 590 @return Error codes
 591 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 592 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 593 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 594   */
 595 RESPONSECODE IFDHCloseChannel(DWORD Lun);
 596
 597 /**
 598 This function should get the slot/card capabilities for a particular
 599 slot/card specified by Lun. Again, if you have only 1 card slot and
 600 don't mind loading a new driver for each reader then ignore Lun.
 601
 602 @ingroup IFDHandler
 603 @param[in] Lun Logical Unit Number
 604 @param[in] Tag Tag of the desired data value
 605 - \ref TAG_IFD_ATR
 606   Return the ATR and its size (implementation is mandatory).
 607 - \ref TAG_IFD_SLOTNUM
 608   Unused/deprecated
 609 - \ref SCARD_ATTR_ATR_STRING
 610   Same as \ref TAG_IFD_ATR but this one is not mandatory. It is defined
 611   in Microsoft PC/SC SCardGetAttrib().
 612 - \ref TAG_IFD_SIMULTANEOUS_ACCESS
 613   Return the number of sessions (readers) the driver can handle in
 614   <tt>Value[0]</tt>.
 615   This is used for multiple readers sharing the same driver.
 616 - \ref TAG_IFD_THREAD_SAFE
 617   If the driver supports more than one reader (see
 618   \ref TAG_IFD_SIMULTANEOUS_ACCESS above) this tag indicates if the
 619   driver supports access to multiple readers at the same time.
 620   - <tt>Value[0] = 0</tt>: the driver DOES NOT support simultaneous accesses.
 621   - <tt>Value[0] = 1</tt>: the driver supports simultaneous accesses.
 622 - \ref TAG_IFD_SLOTS_NUMBER
 623   Return the number of slots in this reader in <tt>Value[0]</tt>.
 624 - \ref TAG_IFD_SLOT_THREAD_SAFE
 625   If the reader has more than one slot (see \ref TAG_IFD_SLOTS_NUMBER
 626   above) this tag indicates if the driver supports access to multiple
 627   slots of the same reader at the same time.
 628   - <tt>value[0] = 0</tt>: the driver supports only 1 slot access at a time.
 629   - <tt>value[0] = 1</tt>: the driver supports simultaneous slot accesses.
 630 - \ref TAG_IFD_POLLING_THREAD
 631   Unused/deprecated
 632 - \ref TAG_IFD_POLLING_THREAD_WITH_TIMEOUT
 633   If the driver provides a polling thread then @p Value is a pointer to
 634   this function. The function prototype is:
 635 @verbatim
 636   RESPONSECODE foo(DWORD Lun, int timeout);
 637 @endverbatim
 638 - \ref TAG_IFD_POLLING_THREAD_KILLABLE
 639   Tell if the polling thread can be killed (pthread_kill()) by pcscd
 640   - <tt>value[0] = 0</tt>: the driver can NOT be stopped using
 641         pthread_cancel(). The driver must then implement
 642         \ref TAG_IFD_STOP_POLLING_THREAD
 643   - <tt>value[0] = 1</tt>: the driver can be stopped using pthread_cancel()
 644 - \ref TAG_IFD_STOP_POLLING_THREAD
 645   Returns a pointer in @p Value to the function used to stop the polling
 646   thread returned by \ref TAG_IFD_POLLING_THREAD_WITH_TIMEOUT. The
 647   function prototype is:
 648 @verbatim
 649   RESPONSECODE foo(DWORD Lun);
 650 @endverbatim
 651 @param[in,out] Length Length of the desired data value
 652 @param[out] Value Value of the desired data
 653
 654 @return Error codes
 655 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 656 @retval IFD_ERROR_INSUFFICIENT_BUFFER Buffer is too small (\ref IFD_ERROR_INSUFFICIENT_BUFFER)
 657 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 658 @retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG)
 659 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 660  */
 661 RESPONSECODE IFDHGetCapabilities(DWORD Lun, DWORD Tag, PDWORD Length,
 662         PUCHAR Value);
 663
 664 /**
 665 This function should set the slot/card capabilities for a particular
 666 slot/card specified by @p Lun. Again, if you have only 1 card slot and
 667 don't mind loading a new driver for each reader then ignore @p Lun.
 668
 669 @ingroup IFDHandler
 670 @param[in] Lun Logical Unit Number
 671 @param[in] Tag Tag of the desired data value
 672 @param[in,out] Length Length of the desired data value
 673 @param[out] Value Value of the desired data
 674
 675 This function is also called when the application uses the PC/SC
 676 SCardSetAttrib() function. The list of supported tags is not limited.
 677
 678 @return Error codes
 679 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 680 @retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG)
 681 @retval IFD_ERROR_SET_FAILURE Could not set value (\ref IFD_ERROR_SET_FAILURE)
 682 @retval IFD_ERROR_VALUE_READ_ONLY Trying to set read only value (\ref IFD_ERROR_VALUE_READ_ONLY)
 683 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 684  */
 685 RESPONSECODE IFDHSetCapabilities(DWORD Lun, DWORD Tag, DWORD Length, PUCHAR Value);
 686
 687 /**
 688 This function should set the Protocol Type Selection (PTS) of a
 689 particular card/slot using the three PTS parameters sent
 690
 691 @ingroup IFDHandler
 692 @param[in] Lun Logical Unit Number
 693 @param[in] Protocol Desired protocol
 694 - \ref SCARD_PROTOCOL_T0
 695   T=0 protocol
 696 - \ref SCARD_PROTOCOL_T1
 697   T=1 protocol
 698 @param[in] Flags Logical OR of possible values to determine which PTS values
 699 to negotiate
 700 - \ref IFD_NEGOTIATE_PTS1
 701 - \ref IFD_NEGOTIATE_PTS2
 702 - \ref IFD_NEGOTIATE_PTS3
 703 @param[in] PTS1 1st PTS Value
 704 @param[in] PTS2 2nd PTS Value
 705 @param[in] PTS3 3rd PTS Value\n
 706   See ISO 7816/EMV documentation.
 707
 708 @return Error codes
 709 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 710 @retval IFD_ERROR_PTS_FAILURE Could not set PTS value (\ref IFD_ERROR_PTS_FAILURE)
 711 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 712 @retval IFD_PROTOCOL_NOT_SUPPORTED Protocol is not supported (\ref IFD_PROTOCOL_NOT_SUPPORTED)
 713 @retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
 714 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 715  */
 716 RESPONSECODE IFDHSetProtocolParameters(DWORD Lun, DWORD Protocol, UCHAR Flags,
 717         UCHAR PTS1, UCHAR PTS2, UCHAR PTS3);
 718 /**
 719 This function controls the power and reset signals of the smart card
 720 reader at the particular reader/slot specified by @p Lun.
 721
 722 @ingroup IFDHandler
 723 @param[in] Lun Logical Unit Number
 724 @param[in] Action Action to be taken on the card
 725 - \ref IFD_POWER_UP
 726   Power up the card (store and return Atr and AtrLength)
 727 - \ref IFD_POWER_DOWN
 728   Power down the card (Atr and AtrLength should be zeroed)
 729 - \ref IFD_RESET
 730   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)
 731 @param[out] Atr Answer to Reset (ATR) of the card\n
 732   The driver is responsible for caching this value in case
 733   IFDHGetCapabilities() is called requesting the ATR and its length. The
 734   ATR length should not exceed \ref MAX_ATR_SIZE.
 735 @param[in,out] AtrLength Length of the ATR\n
 736   This should not exceed \ref MAX_ATR_SIZE.
 737
 738 @note
 739 Memory cards without an ATR should return \ref IFD_SUCCESS on reset but the
 740 Atr should be zeroed and the length should be zero Reset errors should
 741 return zero for the AtrLength and return \ref IFD_ERROR_POWER_ACTION.
 742
 743 @return Error codes
 744 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 745 @retval IFD_ERROR_POWER_ACTION Error powering/resetting card (\ref IFD_ERROR_POWER_ACTION)
 746 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 747 @retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
 748 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 749  */
 750 RESPONSECODE IFDHPowerICC(DWORD Lun, DWORD Action, PUCHAR Atr, PDWORD
 751         AtrLength);
 752
 753 /**
 754 This function performs an APDU exchange with the card/slot specified by
 755 Lun. The driver is responsible for performing any protocol specific
 756 exchanges such as T=0, 1, etc. differences. Calling this function will
 757 abstract all protocol differences.
 758
 759 @ingroup IFDHandler
 760 @param[in] Lun Logical Unit Number
 761 @param[in] SendPci contains two structure members
 762 - Protocol 0, 1, ... 14\n
 763   T=0 ... T=14
 764 - Length\n
 765   Not used.
 766 @param[in] TxBuffer Transmit APDU\n
 767       Example: "\x00\xA4\x00\x00\x02\x3F\x00"
 768 @param[in] TxLength Length of this buffer
 769 @param[out] RxBuffer Receive APDU\n
 770       Example: "\x61\x14"
 771 @param[in,out] RxLength Length of the received APDU\n
 772   This function will be passed the size of the buffer of RxBuffer and
 773   this function is responsible for setting this to the length of the
 774   received APDU response. This should be ZERO on all errors. The
 775   resource manager will take responsibility of zeroing out any temporary
 776   APDU buffers for security reasons.
 777 @param[out] RecvPci contains two structure members
 778 - Protocol - 0, 1, ... 14\n
 779   T=0 ... T=14
 780 - Length\n
 781   Not used.
 782
 783 @note
 784 The driver is responsible for knowing what type of card it has. If the
 785 current slot/card contains a memory card then this command should ignore
 786 the Protocol and use the MCT style commands for support for these style
 787 cards and transmit them appropriately. If your reader does not support
 788 memory cards or you don't want to implement this functionality, then
 789 ignore this.
 790 @par
 791 RxLength should be set to zero on error.
 792 @par
 793 The driver is not responsible for doing an automatic Get Response
 794 command for received buffers containing 61 XX.
 795
 796 @return Error codes
 797 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 798 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 799 @retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT)
 800 @retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT)
 801 @retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
 802 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 803  */
 804 RESPONSECODE IFDHTransmitToICC(DWORD Lun, SCARD_IO_HEADER SendPci,
 805         PUCHAR TxBuffer, DWORD TxLength, PUCHAR RxBuffer, PDWORD
 806         RxLength, PSCARD_IO_HEADER RecvPci);
 807
 808 /**
 809 This function returns the status of the card inserted in the reader/slot
 810 specified by @p Lun. In cases where the device supports asynchronous
 811 card insertion/removal detection, it is advised that the driver manages
 812 this through a thread so the driver does not have to send and receive a
 813 command each time this function is called.
 814
 815 @ingroup IFDHandler
 816 @param[in] Lun Logical Unit Number
 817
 818 @return Error codes
 819 @retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
 820 @retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
 821 @retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT)
 822 @retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
 823  */
 824 RESPONSECODE IFDHICCPresence(DWORD Lun);
 825
 826 #endif