2
% MUSCLE SmartCard Development (http://www.musclecard.com)
5
% David Corcoran <corcoran@musclecard.com>
6
% Ludovic Rousseau <ludovic.rousseau@free.fr>
8
% $Id: ifdhandler-3.tex,v 1.3 2005-09-06 20:37:19 rousseau Exp $
10
\documentclass[a4paper,12pt]{article}
12
\usepackage{longtable}
16
% D�tection de pdflatex
17
\ifx\pdfcompresslevel\undefined
18
% Si on fait un postscript
19
\typeout{Postscript version}
20
\usepackage[dvips]{graphicx,rotating}
21
%\usepackage[dvips,matrix,line,curve,arrow,frame]{xy}
22
\DeclareGraphicsExtensions{.eps}
26
\usepackage[pdftex]{graphicx,rotating}
27
%\usepackage[matrix,line,curve,arrow,frame]{xy}
28
\DeclareGraphicsExtensions{.jpg,.pdf}
29
\usepackage[pdftex]{hyperref}
30
\usepackage{ae,aeguill}
36
% do not number subsubsection
37
\setcounter{tocdepth}{2}
38
\setcounter{secnumdepth}{2}
41
\newcommand{\synopsis}{\subsubsection{Synopsis:}}
42
\newcommand{\parameters}{\subsubsection{Parameters:}}
43
\newcommand{\desc}{\subsubsection{Description:}}
44
\newcommand{\example}{\subsubsection{Example:}}
45
\newcommand{\returns}{\subsubsection{Returns:}}
47
\title{MUSCLE PC/SC IFD Driver API}
48
\author{David Corcoran \& Ludovic Rousseau\\
49
\url{corcoran@musclecard.com}, \url{ludovic.rousseau@free.fr}}
57
This toolkit and documentation is provided on an as is basis. The
58
authors shall not be held responsible for any mishaps caused by the use
61
For more information please visit \url{http://www.musclecard.com/}.
65
% space between paragraphs
68
% remove paragraph indentation
69
\addtolength{\parindent}{-\parindent}
72
\begin{tabular}{|l|l|l|}
74
3.0.1 & August 9, 2003 & latest PDF only version \\
76
3.1.0 & July 28, 2004 & reformat using \LaTeX{}, correct bugs and add
85
%---------%---------%---------%---------%---------%---------%---------
86
\section{Introduction/Overview}
88
This document describes the API calls required to make a PC/SC driver
89
for a device to be supported under the MUSCLE PC/SC resource manager. By
90
implementing these calls correctly in a driver or shared object form,
91
reader manufacturers can fit their hardware into an already existing
92
infrastructure under several operating systems and hardware platforms.
93
This IFD Handler interface is not restricted to smart cards and readers
94
and could also be used for other types of smart card like devices. I
95
would really like to hear from you. If you have any feedback either on
96
this documentation or on the MUSCLE project please feel free to email me
97
at: \url{corcoran@musclecard.com}.
101
%---------%---------%---------%---------%---------%---------%---------
102
\section{Definitions}
105
%---------%---------%---------%---------%---------%---------
106
\subsection{Defined types}
108
The following is a list of commonly used type definitions in the
109
following API. These definitions and more can be found in the
110
\texttt{ifdhandler.h} file.
113
\begin{longtable}{|l|l|}
115
\textrm{PC/SC type} & \textrm{C type} \\
118
DWORD & unsigned long \\
120
PDWORD & unsigned long * \\
121
PUCHAR & unsigned char * \\
122
RESPONSECODE & long \\
129
%---------%---------%---------%---------%---------%---------
130
\subsection{Error codes}
132
The following is a list of returned values:
135
\begin{longtable}{|l|}
139
IFD\_COMMUNICATION\_ERROR\\
140
IFD\_ERROR\_CONFISCATE\\
142
IFD\_ERROR\_NOT\_SUPPORTED\\
143
IFD\_ERROR\_POWER\_ACTION\\
144
IFD\_ERROR\_PTS\_FAILURE\\
145
IFD\_ERROR\_SET\_FAILURE\\
146
IFD\_ERROR\_SWALLOW\\
148
IFD\_ERROR\_VALUE\_READ\_ONLY\\
149
IFD\_ICC\_NOT\_PRESENT\\
151
IFD\_NOT\_SUPPORTED\\
152
IFD\_PROTOCOL\_NOT\_SUPPORTED\\
153
IFD\_RESPONSE\_TIMEOUT\\
158
%---------%---------%---------%---------%---------%---------%---------
159
\section{Readers configuration}
162
%---------%---------%---------%---------%---------%---------
163
\subsection{USB readers}
165
USB readers use the bundle approach so that the reader can be loaded and
166
unloaded upon automatic detection of the device. The bundle approach is
167
simple: the actual library is just embedded in a directory so additional
168
information can be gathered about the device.
170
A bundle looks like the following:
173
GenericReader.bundle/
175
Info.plist - XML file describing the reader
176
MacOS/ - Driver directory for OS X
177
Solaris/ - Driver directory for Solaris
178
Linux/ - Driver directory for Linux
179
HPUX/ - Driver directory for HPUX
182
The \texttt{Info.plist} file describes the driver and gives the loader all
183
the necessary information. The following must be contained in the
184
\texttt{Info.plist} file:
187
\item \texttt{ifdVendorID}
189
The vendor ID of the USB device.
193
<key>ifdVendorID</key>
194
<string>0x04E6</string>
197
You may have an OEM of this reader in which an additional
198
\texttt{<string>} can be used like in the below example:
200
<key>ifdVendorID</key>
202
<string>0x04E6</string>
203
<string>0x0973</string>
207
If multiples exist all the other parameters must have a second value
208
also. You may chose not to support this feature but it is useful when
209
reader vendors OEM products so you only distribute one driver.
211
The CCID driver from Ludovic
212
Rousseau\footnote{\url{http://pcsclite.alioth.debian.org/ccid.html}}
213
uses this feature since the same driver supports many different readers.
215
\item \texttt{ifdProductID}
217
The product id of the USB device.
220
<key>ifdProductID</key>
221
<string>0x3437</string>
224
\item \texttt{ifdFriendlyName}
228
<key>ifdFriendlyName</key>
229
<string>SCM Microsystems USB Reader</string>
232
\item \texttt{CFBundleExecutable}
234
The executable name which exists in the particular platform's directory.
238
<key>CFBundleExecutable</key>
239
<string>libccid.so.0.4.2</string>
244
Complete sample file:
246
<?xml version="1.0" encoding="UTF-8"?>
247
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
248
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
249
<plist version="1.0">
251
<key>CFBundleDevelopmentRegion</key>
252
<string>English</string>
253
<key>CFBundleInfoDictionaryVersion</key>
255
<key>CFBundlePackageType</key>
256
<string>BNDL</string>
257
<key>CFBundleSignature</key>
258
<string>????</string>
259
<key>CFBundleVersion</key>
260
<string>0.0.1d1</string>
261
<key>ifdCapabilities</key>
262
<string>0x00000000</string>
263
<key>ifdProtocolSupport</key>
264
<string>0x00000001</string>
265
<key>ifdVersionNumber</key>
266
<string>0x00000001</string>
268
<key>CFBundleExecutable</key>
269
<string>libfoobar.so.x.y</string>
271
<key>ifdManufacturerString</key>
272
<string>Foo bar inc.</string>
274
<key>ifdProductString</key>
275
<string>Driver for Foobar reader, version x.y</string>
277
<key>ifdVendorID</key>
278
<string>0x1234</string>
280
<key>ifdProductID</key>
281
<string>0x5678</string>
283
<key>ifdFriendlyName</key>
284
<string>Foobar USB reader</string>
289
As indicated in the XML file the DTD is available at
290
\url{http://www.apple.com/DTDs/PropertyList-1.0.dtd}.
293
%---------%---------%---------%---------%---------%---------
294
\subsection{Serial readers}
296
Serial drivers must be configured to operate on a particular port and
297
respond to a particular name. The \texttt{reader.conf} file is used for
300
It has the following syntax:
303
# Configuration file for pcsc-lite
304
# David Corcoran <corcoran@musclecard.com>
306
FRIENDLYNAME Generic Reader
307
DEVICENAME /dev/ttyS0
308
LIBPATH /usr/lib/pcsc/drivers/libgen_ifd.so
313
\item The pound sign \verb+#+ denotes a comment.
315
\item The \texttt{FRIENDLYNAME} field is an arbitrary text used to
316
identify the reader. This text is displayed by commands like
317
\texttt{pcsc\_scan}\footnote{\url{http://ludovic.rousseau.free.fr/softwares/pcsc-tools/}}
318
that prints the names of all the connected and detected readers.
320
\item The \texttt{DEVICENAME} field was not used for old drivers (using
321
the IFD handler version 2.0 or previous). It is now (IFD handler version
322
3.0) used to identify the physical port on which the reader is
323
connected. This is the device name of this port. It is dependent of the
324
OS kernel. For example the first serial port device is called
325
\texttt{/dev/ttyS0} under Linux and \texttt{/dev/cuaa0} under FreeBSD.
327
\item The \texttt{LIBPATH} field is the filename of the driver code. The
328
driver is a dynamically loaded piece of code (generally a
329
\texttt{drivername.so*} file).
331
\item The \texttt{CHANNELID} is no more used for recent drivers (IFD
332
handler 3.0) and has been superseded by \texttt{DEVICENAME}. If you
333
have an old driver this field is used to indicate the port to use. You
334
should read your driver documentation to know what information is needed
335
here. It should be the serial port number for a serial reader.
337
\texttt{CHANNELID} was the numeric version of the port in which the
338
reader will be located. This may be done by a symbolic link where
339
\texttt{/dev/pcsc/1} is the first device which may be a symbolic link to
340
\texttt{/dev/ttyS0} or whichever location your reader resides.
345
%---------%---------%---------%---------%---------%---------%---------
346
\section{API Routines}
348
The routines specified hereafter will allow you to write an IFD handler
349
for the PC/SC Lite resource manager. Please use the complement
350
developer's kit complete with headers and Makefile at:
351
\url{http://www.musclecard.com/drivers.html}.
353
This gives a common API for communication to most readers in a
354
homogeneous fashion. This document assumes that the driver developer is
355
experienced with standards such as ISO-7816-(1, 2, 3, 4), EMV and MCT
356
specifications. For listings of these specifications please access the
360
%---------%---------%---------%---------%---------%---------
361
\subsection{IFDHCreateChannel}
366
#include <PCSC/ifdhandler.h>
368
RESPONSECODE IFDHCreateChannel(DWORD Lun,
375
\texttt{Lun} & IN & Logical Unit Number \\
376
\texttt{Channel} & IN & Channel ID \\
381
This function is required to open a communications channel to the port
382
listed by \texttt{Channel}. For example, the first serial reader on COM1
383
would link to \texttt{/dev/pcsc/1} which would be a symbolic link to
384
\texttt{/dev/ttyS0} on some machines This is used to help with
385
inter-machine independence.
387
On machines with no \texttt{/dev} directory the driver writer may choose to
388
map their \texttt{Channel} to whatever they feel is appropriate.
390
Once the channel is opened the reader must be in a state in which it is
391
possible to query \texttt{IFDHICCPresence()} for card status.
394
\item \texttt{Lun} - Logical Unit Number
396
Use this for multiple card slots or multiple readers.
397
\texttt{0xXXXXYYYY} - \texttt{XXXX} multiple readers, \texttt{YYYY}
398
multiple slots. The resource manager will set these automatically. By
399
default the resource manager loads a new instance of the driver so if
400
your reader does not have more than one smart card slot then ignore the
401
Lun in all the functions.
403
PC/SC supports the loading of multiple readers through one instance of
404
the driver in which \texttt{XXXX} is important. \texttt{XXXX} identifies
405
the unique reader in which the driver communicates to. The driver should
406
set up an array of structures that associate this \texttt{XXXX} with the
407
underlying details of the particular reader.
409
\item \texttt{Channel} - Channel ID
411
This is denoted by the following:
415
0x000001 & /dev/pcsc/1\\
416
0x000002 & /dev/pcsc/2\\
417
0x000003 & /dev/pcsc/3\\
418
0x000004 & /dev/pcsc/4\\
422
USB readers can ignore the \texttt{Channel} parameter and query the USB
423
bus for the particular reader by manufacturer and product id.
430
\texttt{IFD\_SUCCESS} & Successful\\
431
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred
435
%---------%---------%---------%---------%---------%---------
436
\subsection{IFDHCreateChannelByName}
437
\label{IFDHCreateChannelByName}
441
#include <PCSC/ifdhandler.h>
443
RESPONSECODE IFDHCreateChannelByName(DWORD Lun,
450
\texttt{Lun} & IN & Logical Unit Number \\
451
\texttt{DeviceName} & IN & String device path \\
457
This function is required to open a communications channel to the port
458
listed by \texttt{DeviceName}.
460
Once the channel is opened the reader must be in a state in which it is
461
possible to query \texttt{IFDHICCPresence()} for card status.
464
\item \texttt{Lun} - Logical Unit Number
466
Use this for multiple card slots or multiple readers.
467
\texttt{0xXXXXYYYY} - \texttt{XXXX} multiple readers, \texttt{YYYY}
468
multiple slots. The resource manager will set these automatically. By
469
default the resource manager loads a new instance of the driver so if
470
your reader does not have more than one smart card slot then ignore the
471
Lun in all the functions.
473
PC/SC supports the loading of multiple readers through one instance of
474
the driver in which \texttt{XXXX} is important. \texttt{XXXX} identifies
475
the unique reader in which the driver communicates to. The driver should
476
set up an array of structures that associate this \texttt{XXXX} with the
477
underlying details of the particular reader.
479
\item \texttt{DeviceName} - filename to use by the driver.
481
For drivers configured by \texttt{/etc/reader.conf} this is the value of
482
the field \texttt{DEVICENAME}.
484
For USB drivers under platforms using
485
\texttt{libusb}\footnote{\url{http://libusb.sourceforge.net/}} for USB
486
abstraction (Any Unix except MacOSX) the \texttt{DeviceName} field uses
487
the string generated by:
489
printf("usb:%04x/%04x:libusb:%s:%s",
491
bus->dirname, dev->filename)
494
So it is something like: \texttt{usb:08e6/3437:libusb:001:042} under
497
It is the responsability of the driver to correctly identify the reader.
498
This scheme was put in place to be able to distinguish two identical
499
readers connected at the same time.
506
\texttt{IFD\_SUCCESS} & Successful\\
507
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred
511
%---------%---------%---------%---------%---------%---------
512
\subsection{IFDHCloseChannel}
516
#include <PCSC/ifdhandler.h>
518
RESPONSECODE IFDHCloseChannel(DWORD Lun);
524
\texttt{Lun} & IN & Logical Unit Number \\
529
This function should close the reader communication channel for the
530
particular reader. Prior to closing the communication channel the reader
531
should make sure the card is powered down and the terminal is also
537
\texttt{IFD\_SUCCESS} & Successful\\
538
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred
542
%---------%---------%---------%---------%---------%---------
543
\subsection{IFDHGetCapabilities}
547
#include <PCSC/ifdhandler.h>
549
RESPONSECODE IFDHGetCapabilities(DWORD Lun,
558
\texttt{Lun} & IN & Logical Unit Number \\
559
\texttt{Tag} & IN & Tag of the desired data value \\
560
\texttt{Length} & INOUT & Length of the desired data value \\
561
\texttt{Value} & OUT & Value of the desired data \\
566
This function should get the slot/card capabilities for a particular
567
slot/card specified by \texttt{Lun}. Again, if you have only 1 card slot
568
and don't mind loading a new driver for each reader then ignore
572
\item \texttt{Tag} - the tag for the information requested
575
\item \texttt{TAG\_IFD\_ATR}
577
Return the ATR and it's size (implementation is mandatory).
579
\item \texttt{SCARD\_ATTR\_ATR\_STRING}
581
Same as \texttt{TAG\_IFD\_ATR} but this one is not mandatory. It is
582
defined in Microsoft PC/SC \texttt{SCardGetAttrib()}.
584
\item \texttt{TAG\_IFD\_SIMULTANEOUS\_ACCESS}
586
Return the number of sessions (readers) the driver can handle in
589
This is used for multiple readers sharing the same driver.
591
\item \texttt{TAG\_IFD\_THREAD\_SAFE}
593
If the driver support more than one reader (see
594
\texttt{TAG\_IFD\_SIMULTANEOUS\_ACCESS} above) this tag indicates if the
595
driver supports access to multiple reader at the same time.
597
\texttt{Value[0] = 1} indicates the driver supports simultaneous
600
\item \texttt{TAG\_IFD\_SLOTS\_NUMBER}
602
Return the number of slots in this reader in \texttt{Value[0]}.
604
\item \texttt{TAG\_IFD\_SLOT\_THREAD\_SAFE}
606
If the reader has more than one slot (see
607
\texttt{TAG\_IFD\_SLOTS\_NUMBER} above) this tag indicates if the driver
608
supports access to multiple slots of the same reader at the same time.
610
\texttt{Value[0] = 1} indicates the driver supports simultaneous slot
613
\item \texttt{IOCTL\_SMARTCARD\_VENDOR\_VERIFY\_PIN}
615
Return a non null value if the driver/reader is able to perform a
616
\texttt{SCardControl(hCard, IOCTL\_SMARTCARD\_VENDOR\_VERIFY\_PIN,
617
...)}. See pcsc-lite documentation~\cite{pcsclite}.
621
\item \texttt{Length} - the length of the returned data
623
\item \texttt{Value} - the value of the data
627
This function is also called when the application uses the PC/SC
628
\texttt{SCardGetAttrib()} function. The list of supported tags is not
629
limited. The ones above are used by the PC/SC lite resource manager.
634
\texttt{IFD\_SUCCESS} & Successful\\
635
\texttt{IFD\_ERROR\_TAG} & Invalid tag given
639
%---------%---------%---------%---------%---------%---------
640
\subsection{IFDHSetCapabilities}
644
#include <PCSC/ifdhandler.h>
646
RESPONSECODE IFDHSetCapabilities(DWORD Lun,
655
\texttt{Lun} & IN & Logical Unit Number\\
656
\texttt{Tag} & IN & Tag of the desired data value\\
657
\texttt{Length} & INOUT & Length of the desired data value\\
658
\texttt{Value} & OUT & Value of the desired data\\
663
This function should set the slot/card capabilities for a particular
664
slot/card specified by Lun. Again, if you have only 1 card slot and
665
don't mind loading a new driver for each reader then ignore Lun.
668
\item \texttt{Tag} - the tag for the information needing set
671
\item \texttt{TAG\_IFD\_SLOTNUM}
673
This is used in IFDHandler v1.0 to select the slot to use for the next
674
\texttt{IFD\_*} command. This tag is no more used with versions 2.0 and
675
3.0 of the IFD Handler.
679
\item \texttt{Length} - the length of the data
680
\item \texttt{Value} - the value of the data
683
This function is also called when the application uses the PC/SC
684
\texttt{SCardGetAttrib()} function. The list of supported tags is not limited.
689
\texttt{IFD\_SUCCESS} & Success\\
690
\texttt{IFD\_ERROR\_TAG} & Invalid tag given\\
691
\texttt{IFD\_ERROR\_SET\_FAILURE} & Could not set value\\
692
\texttt{IFD\_ERROR\_VALUE\_READ\_ONLY} & Trying to set read only value
696
%---------%---------%---------%---------%---------%---------
697
\subsection{IFDHSetProtocolParameters}
701
#include <PCSC/ifdhandler.h>
703
RESPONSECODE IFDHSetProtocolParameters(DWORD Lun,
714
\texttt{Lun} & IN & Logical Unit Number\\
715
\texttt{Protocol} & IN & Desired protocol\\
716
\texttt{Flags} & IN & OR'd Flags (See below)\\
717
\texttt{PTS1} & IN & 1st PTS Value\\
718
\texttt{PTS2} & IN & 2nd PTS Value\\
719
\texttt{PTS3} & IN & 3rd PTS Value\\
724
This function should set the Protocol Type Selection (PTS) of a
725
particular card/slot using the three PTS parameters sent
728
\item \texttt{Protocol} - 0...14
732
\item \texttt{Flags} - Logical OR of possible values to determine which PTS
736
\item \texttt{IFD\_NEGOTIATE\_PTS1}
737
\item \texttt{IFD\_NEGOTIATE\_PTS2}
738
\item \texttt{IFD\_NEGOTIATE\_PTS3}
741
\item \texttt{PTS1}, \texttt{PTS2}, \texttt{PTS3} - PTS Values
743
See ISO 7816/EMV documentation.
750
\texttt{IFD\_SUCCESS} & Success\\
751
\texttt{IFD\_ERROR\_PTS\_FAILURE} & Could not set PTS value\\
752
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred\\
753
\texttt{IFD\_PROTOCOL\_NOT\_SUPPORTED} & Protocol is not supported\\
757
%---------%---------%---------%---------%---------%---------
758
\subsection{IFDHPowerICC}
762
#include <PCSC/ifdhandler.h>
764
RESPONSECODE IFDHPowerICC(DWORD Lun,
773
\texttt{Lun} & IN & Logical Unit Number\\
774
\texttt{Action} & IN & Action to be taken\\
775
\texttt{Atr} & OUT & Answer to Reset (ATR) value of the inserted card\\
776
\texttt{AtrLength} & INOUT & Length of the ATR\\
781
This function controls the power and reset signals of the smart card
782
reader at the particular reader/slot specified by Lun.
785
\item \texttt{Action} - Action to be taken on the card
788
\item \texttt{IFD\_POWER\_UP}
790
Power and reset the card if not done so (store the ATR and return it and
793
\item \texttt{IFD\_POWER\_DOWN}
795
Power down the card then power up if not done already (\texttt{Atr} and
796
\texttt{AtrLength} should be zeroed)
798
\item \texttt{IFD\_RESET}
800
Perform a quick reset on the card. If the card is not powered power up
801
the card. (Store and return \texttt{Atr} and \texttt{Length})
805
\item \texttt{Atr} - Answer to Reset of the card
807
The driver is responsible for caching this value in case
808
\texttt{IFDHGetCapabilities()} is called requesting the ATR and it's
809
length. The ATR length should not exceed \texttt{MAX\_ATR\_SIZE}.
811
\item \texttt{AtrLength} - Length of the Atr
813
This should not exceed \texttt{MAX\_ATR\_SIZE}.
819
Memory cards without an ATR should return \texttt{IFD\_SUCCESS} on reset
820
but the \texttt{Atr} should be zeroed and the length should be zero
821
Reset errors should return zero for the \texttt{AtrLength} and return
822
\texttt{IFD\_ERROR\_POWER\_ACTION}.
827
\texttt{IFD\_SUCCESS} & Success\\
828
\texttt{IFD\_ERROR\_POWER\_ACTION} & Error powering/resetting card\\
829
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred\\
830
\texttt{IFD\_NOT\_SUPPORTED} & Action not supported\\
834
%---------%---------%---------%---------%---------%---------
835
\subsection{IFDHTransmitToICC}
839
#include <PCSC/ifdhandler.h>
841
RESPONSECODE IFDHTransmitToICC(DWORD Lun,
842
SCARD_IO_HEADER SendPci,
847
PSCARD_IO_HEADER RecvPci);
853
\texttt{Lun} & IN & Logical Unit Number\\
854
\texttt{SendPci} & IN & Protocol structure\\
855
\texttt{TxBuffer} & IN & APDU to be sent\\
856
\texttt{TxLength} & IN & Length of sent APDU\\
857
\texttt{RxBuffer} & OUT & APDU response\\
858
\texttt{RxLength} & INOUT & Length of APDU response\\
859
\texttt{RecvPci} & INOUT & Receive protocol structure
864
This function performs an APDU exchange with the card/slot specified by
865
\texttt{Lun}. The driver is responsible for performing any protocol
866
specific exchanges such as T=0, 1, etc. differences. Calling this function
867
will abstract all protocol differences.
870
\item \texttt{SendPci} - contains two structure members
873
\item \texttt{Protocol} - 0, 1, ... 14
877
\item \texttt{Length} \tab - Not used.
880
\item \texttt{TxBuffer} \tab - Transmit APDU
882
example: \verb+"\x00\xA4\x00\x00\x02\x3F\x00"+
884
\item \texttt{TxLength} \tab - Length of this buffer
885
\item \texttt{RxBuffer} \tab - Receive APDU
887
example: \verb+"\x61\x14"+
889
\item \texttt{RxLength} \tab - Length of the received APDU
891
This function will be passed the size of the buffer of \texttt{RxBuffer}
892
and this function is responsible for setting this to the length of the
893
received APDU response. This should be ZERO on all errors. The resource
894
manager will take responsibility of zeroing out any temporary APDU
895
buffers for security reasons.
897
\item \texttt{RecvPci} - contains two structure members
900
\item \texttt{Protocol} - 0, 1, ... 14
904
\item \texttt{Length} - Not used.
910
The driver is responsible for knowing what type of card it has. If the
911
current slot/card contains a memory card then this command should ignore
912
the \texttt{Protocol} and use the MCT style commands for support for
913
these style cards and transmit them appropriately. If your reader does
914
not support memory cards or you don't want to implement this
915
functionality, then ignore this.
917
\texttt{RxLength} should be set to zero on error.
919
The driver is \emph{not} responsible for doing an automatic Get Response
920
command for received buffers containing \texttt{61 XX}.
925
\texttt{IFD\_SUCCESS} & Success\\
926
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred\\
927
\texttt{IFD\_RESPONSE\_TIMEOUT} & The response timed out\\
928
\texttt{IFD\_ICC\_NOT\_PRESENT} & ICC is not present\\
929
\texttt{IFD\_PROTOCOL\_NOT\_SUPPORTED} & Protocol is not supported
933
%---------%---------%---------%---------%---------%---------
934
\subsection{IFDHControl}
939
#include <PCSC/ifdhandler.h>
941
RESPONSECODE IFDHControl(DWORD Lun,
947
PDWORD pdwBytesReturned);
953
\texttt{Lun} & IN & Logical Unit Number\\
954
\texttt{dwControlCode} & IN & Control code for the operation\\
955
\texttt{TxBuffer} & IN & Bytes to be sent\\
956
\texttt{TxLength} & IN & Length of sent bytes\\
957
\texttt{RxBuffer} & OUT & Response\\
958
\texttt{RxLength} & IN & Length of response buffer\\
959
\texttt{pdwBytesReturned} & OUT & Length of response \\
964
This function performs a data exchange with the reader (not the card)
965
specified by \texttt{Lun}. It is responsible for abstracting
966
functionality such as PIN pads, biometrics, LCD panels, etc. You should
967
follow the MCT and CTBCS specifications for a list of accepted commands
968
to implement. This function is fully voluntary and does not have to be
969
implemented unless you want extended functionality.
972
\item \texttt{dwControlCode} - Control code for the operation
974
This value identifies the specific operation to be performed. This value
977
\item \texttt{TxBuffer} - Transmit data
978
\item \texttt{TxLength} - Length of this buffer
979
\item \texttt{RxBuffer} - Receive data
980
\item \texttt{RxLength} - Length of the response buffer
982
\item \texttt{pdwBytesReturned} - Length of response
984
This function will be passed the length of the buffer \texttt{RxBuffer}
985
in \texttt{RxLength} and it must set the length of the received data in
986
\texttt{pdwBytesReturned}.
992
\texttt{*pdwBytesReturned} should be set to zero on error.
997
\texttt{IFD\_SUCCESS} & Success\\
998
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred\\
999
\texttt{IFD\_RESPONSE\_TIMEOUT} & The response timed out
1003
%---------%---------%---------%---------%---------%---------
1004
\subsection{IFDHICCPresence}
1008
#include <PCSC/ifdhandler.h>
1010
RESPONSECODE IFDHICCPresence(DWORD Lun);
1015
\begin{tabular}{lll}
1016
\texttt{Lun} & IN & Logical Unit Number
1021
This function returns the status of the card inserted in the reader/slot
1022
specified by \texttt{Lun}. In cases where the device supports
1023
asynchronous card insertion/removal detection, it is advised that the
1024
driver manages this through a thread so the driver does not have to send
1025
and receive a command each time this function is called.
1030
\texttt{IFD\_ICC\_PRESENT} & ICC is present\\
1031
\texttt{IFD\_ICC\_NOT\_PRESENT} & ICC is not present\\
1032
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred
1036
%---------%---------%---------%---------%---------%---------%---------
1037
\section{API provided by pcsc-lite}
1039
pcsc-lite also provides some API to ease the development of the driver.
1042
%---------%---------%---------%---------%---------%---------
1043
\subsection{LTPBundleFindValueWithKey}
1047
#include <PCSC/parser.h>
1049
int LTPBundleFindValueWithKey(char *fileName,
1057
\begin{tabular}{lll}
1058
\texttt{fileName} & IN & configuration file name \\
1059
\texttt{tokenKey} & IN & searched token string \\
1060
\texttt{tokenValue} & OUT & found token value \\
1061
\texttt{tokenIndice} & IN & indice of the desired token in an array \\
1066
This function is used to parse the \texttt{Info.plist} configuration
1067
file. The \texttt{tokenIndice} field is used to get the n-th element of
1073
\texttt{-1} & Error\\
1074
\texttt{0} & No error \\
1075
\texttt{1} & Configuration file not found \\
1079
%---------%---------%---------%---------%---------%---------
1080
\subsection{log\_msg}
1084
#include <debuglog.h>
1086
void debug_msg(const int priority,
1093
\begin{tabular}{lll}
1094
\texttt{priority} & IN & priority level \\
1095
\texttt{fmt} & IN & format string as in \texttt{printf()} \\
1096
\texttt{...} & IN & optionnal parameters as in \texttt{printf()} \\
1099
The \texttt{priority} parameter may be:
1102
\texttt{PCSC\_LOG\_DEBUG} & for debug information \\
1103
\texttt{PCSC\_LOG\_INFO} & default \texttt{pcscd} level \\
1104
\texttt{PCSC\_LOG\_ERROR} & for errors \\
1105
\texttt{PCSC\_LOG\_CRITICAL} & for critical messages (like the driver
1111
This function is used by the driver to send debug or log information to
1112
the administrator. The advantage of using the same debug function as
1113
pcsc-lite is that you also benefit from the debug redirection provided
1114
by pcsc-lite. You will then get \texttt{pcscd} and the driver' debug
1115
messages in the same place.
1117
The log messages are displayed by \texttt{pcscd} either on
1118
\texttt{stderr} (if \texttt{pcscd} is called with \texttt{--foreground})
1119
or using \texttt{syslog(3)} (default).
1121
The level is set using \texttt{pcscd} arguments \texttt{--debug},
1122
\texttt{--info}, \texttt{--error} or \texttt{--critical}.
1124
The levels are ordered. if \texttt{--info} is given all the messages of
1125
priority \texttt{PCSC\_LOG\_INFO}, \texttt{PCSC\_LOG\_ERROR} and
1126
\texttt{PCSC\_LOG\_CRITICAL} are displayed.
1131
#define Log2(priority, fmt, data) log_msg(priority, "%s:%d:%s " fmt, \
1132
__FILE__, __LINE__, __FUNCTION__, data)
1134
Log2("received bytes: %d", r);
1138
%---------%---------%---------%---------%---------%---------
1139
\subsection{log\_xxd}
1143
#include <debuglog.h>
1145
void log_xxd(const int priority,
1147
const unsigned char *buffer,
1153
\begin{tabular}{lll}
1154
\texttt{priority} & IN & priority level \\
1155
\texttt{msg} & IN & text string \\
1156
\texttt{buffer} & IN & buffer you want to dump in hex \\
1157
\texttt{size} & IN & size of the buffer \\
1162
Same idea as \texttt{log\_msg()} put print the hex dump of a buffer.
1166
log_xxd(PCSC_LOG_DEBUG, "received frame: ", buff, buff_size);
1170
%---------%---------%---------%---------%---------%---------%---------
1171
\section{API changes}
1173
The IFD handler API changed over the time.
1175
If the driver provides a \texttt{IFDHCreateChannelByName()} function is
1176
supposed to use API v3.0. Otherwise it is used with API v2.0.
1179
%---------%---------%---------%---------%---------%---------
1180
\subsection{API version 2.0}
1183
\item \texttt{DEVICENAME} in \texttt{reader.conf} is not used.
1185
\item \texttt{IFDHControl()} API was:
1187
RESPONSECODE IFDHControl(DWORD Lun,
1197
%---------%---------%---------%---------%---------%---------
1198
\subsection{API version 3.0}
1201
\item introduction of \texttt{IFDHCreateChannelByName()}.
1203
For serial drivers, \texttt{CHANNELID} is no more used and
1204
\texttt{DEVICENAME} is used instead.
1206
For USB drivers the device name if \verb+usb:%04x/%04x:libusb:%s:%s+.
1207
See \ref{IFDHCreateChannelByName}.
1209
\item \texttt{IFDHControl()} API changed
1211
See \ref{IFDHControl}.
1216
%---------%---------%---------%---------%---------%---------
1217
\bibliographystyle{plain}
1218
\bibliography{pcsc-lite}
added
removed
doc/ifdhandler-3.tex
