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