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