« back to all changes in this revision
Viewing changes to doc/ifdhandler-3.tex
- browse files at revision 2.1.1
- compare with another revision
- download diff
- download tarball
- view history from revision 2.1.1
- Committer: Bazaar Package Importer
- Author(s): Ludovic Rousseau
- Date: 2004-06-13 21:45:56 UTC
- mfrom: (1.1.1 upstream)
- mto: This revision was merged to the branch mainline in revision 3.
- Revision ID: james.westby@ubuntu.com-20040613214556-zio7hrzkz9wwtffx
Tags: 1.2.9-beta2-2
* debian/rules: add -lpthread to LDFLAGS so that pthread_* symbols are
included in the library (problem only seen on mips and mipsel).
Closes: #253629
* debian/control: make libpcsclite-dev and libpcsclite1 at Priority:
optional so that other packages at Priority: optional can use them.
Closes: #249374
included in the library (problem only seen on mips and mipsel).
Closes: #253629
* debian/control: make libpcsclite-dev and libpcsclite1 at Priority:
optional so that other packages at Priority: optional can use them.
Closes: #249374
- files added:
- ChangeLog.cvs
- aclocal
- doc/example
- win32
- files removed:
- build
- files modified:
- AUTHORS
added
removed
doc/ifdhandler-3.tex
1
%
2
% MUSCLE SmartCard Development (http://www.musclecard.com)
3
%
4
% Copyright (C) 2004
5
% David Corcoran <corcoran@musclecard.com>
6
% Ludovic Rousseau <ludovic.rousseau@free.fr>
7
%
8
% $Id: ifdhandler-3.tex,v 1.1.1.1 2004/05/11 13:44:18 rousseau Exp $
9
10
\documentclass[a4paper,12pt]{article}
11
12
\usepackage{longtable}
13
\usepackage{url}
14
\usepackage{varioref}
15
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}
23
\else
24
% Si on fait un PDF
25
\typeout{PDF version}
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}
31
\fi
32
33
% smaller margins
34
\usepackage{fullpage}
35
36
% do not number subsubsection
37
\setcounter{tocdepth}{2}
38
\setcounter{secnumdepth}{2}
39
40
\newcommand{\tab}{}
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:}}
46
47
\title{MUSCLE PC/SC IFD Driver API}
48
\author{David Corcoran \& Ludovic Rousseau\\
49
\url{corcoran@musclecard.com}, \url{ludovic.rousseau@free.fr}}
50
\date{May 10, 2004}
51
52
\begin{document}
53
54
\maketitle
55
56
\begin{abstract}
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
59
of this software.
60
61
For more information please visit \url{http://www.musclecard.com/}.
62
63
\end{abstract}
64
65
% space between paragraphs
66
\parskip = 8pt
67
68
% remove paragraph indentation
69
\addtolength{\parindent}{-\parindent}
70
71
Document history: \\
72
\begin{tabular}{|l|l|l|}
73
\hline
74
3.0.1 & August 9, 2004 & latest PDF only version \\
75
\hline
76
3.1.0 & May 7, 2004 & reformat using \LaTeX{} and correct bugs \\
77
\hline
78
\end{tabular}
79
80
\newpage
81
\tableofcontents
82
\newpage
83
84
%---------%---------%---------%---------%---------%---------%---------
85
\section{Introduction/Overview}
86
87
This document describes the API calls required to make a PC/SC driver
88
for a device to be supported under the MUSCLE PC/SC resource manager. By
89
implementing these calls correctly in a driver or shared object form,
90
reader manufacturers can fit their hardware into an already existing
91
infrastructure under several operating systems and hardware platforms.
92
This IFD Handler interface is not restricted to smart cards and readers
93
and could also be used for other types of smart card like devices. I
94
would really like to hear from you. If you have any feedback either on
95
this documentation or on the MUSCLE project please feel free to email me
96
at: \url{corcoran@musclecard.com}.
97
98
99
100
%---------%---------%---------%---------%---------%---------%---------
101
\section{Definitions}
102
103
104
%---------%---------%---------%---------%---------%---------
105
\subsection{Defined types}
106
107
The following is a list of commonly used type definitions in the
108
following API. These definitions and more can be found in the
109
\texttt{ifdhandler.h} file.
110
111
{\tt
112
\begin{longtable}{|l|l|}
113
\hline
114
\textrm{PC/SC type} & \textrm{C type} \\
115
\hline
116
\hline
117
DWORD & unsigned long \\
118
LPSTR & char * \\
119
PDWORD & unsigned long * \\
120
PUCHAR & unsigned char * \\
121
RESPONSECODE & long \\
122
VOID & void \\
123
\hline
124
\end{longtable}
125
}
126
127
128
%---------%---------%---------%---------%---------%---------
129
\subsection{Error codes}
130
131
The following is a list of returned values:
132
133
{\tt
134
\begin{longtable}{|l|}
135
\hline
136
IFD\_SUCCESS \\
137
\hline
138
IFD\_COMMUNICATION\_ERROR\\
139
IFD\_ERROR\_CONFISCATE\\
140
IFD\_ERROR\_EJECT\\
141
IFD\_ERROR\_NOT\_SUPPORTED\\
142
IFD\_ERROR\_POWER\_ACTION\\
143
IFD\_ERROR\_PTS\_FAILURE\\
144
IFD\_ERROR\_SET\_FAILURE\\
145
IFD\_ERROR\_SWALLOW\\
146
IFD\_ERROR\_TAG\\
147
IFD\_ERROR\_VALUE\_READ\_ONLY\\
148
IFD\_ICC\_NOT\_PRESENT\\
149
IFD\_ICC\_PRESENT\\
150
IFD\_NOT\_SUPPORTED\\
151
IFD\_PROTOCOL\_NOT\_SUPPORTED\\
152
IFD\_RESPONSE\_TIMEOUT\\
153
\hline
154
\end{longtable}
155
}
156
157
%---------%---------%---------%---------%---------%---------%---------
158
\section{Readers configuration}
159
160
161
%---------%---------%---------%---------%---------%---------
162
\subsection{USB readers}
163
164
USB readers use the bundle approach so that the reader can be loaded and
165
unloaded upon automatic detection of the device. The bundle approach is
166
simple: the actual library is just embedded in a directory so additional
167
information can be gathered about the device.
168
169
A bundle looks like the following:
170
171
\begin{verbatim}
172
GenericReader.bundle/
173
Contents/
174
Info.plist - XML file describing the reader
175
MacOS/ - Driver directory for OS X
176
Solaris/ - Driver directory for Solaris
177
Linux/ - Driver directory for Linux
178
HPUX/ - Driver directory for HPUX
179
\end{verbatim}
180
181
The \texttt{Info.plist} file describes the driver and gives the loader all
182
the necessary information. The following must be contained in the
183
\texttt{Info.plist} file:
184
185
\begin{itemize}
186
\item \texttt{ifdVendorID}
187
188
The vendor ID of the USB device.
189
190
Example:
191
\begin{verbatim}
192
<key>ifdVendorID</key>
193
<string>0x04E6</string>
194
\end{verbatim}
195
196
You may have an OEM of this reader in which an additional
197
\texttt{<string>} can be used like in the below example:
198
\begin{verbatim}
199
<key>ifdVendorID</key>
200
<array>
201
<string>0x04E6</string>
202
<string>0x0973</string>
203
</array>
204
\end{verbatim}
205
206
If multiples exist all the other parameters must have a second value
207
also. You may chose not to support this feature but it is useful when
208
reader vendors OEM products so you only distribute one driver.
209
210
The CCID driver from Ludovic
211
Rousseau\footnote{\url{http://pcsclite.alioth.debian.org/ccid.html}}
212
uses this feature since the same driver supports many different readers.
213
214
\item \texttt{ifdProductID}
215
216
The product id of the USB device.
217
218
\begin{verbatim}
219
<key>ifdProductID</key>
220
<string>0x3437</string>
221
\end{verbatim}
222
223
\item \texttt{ifdFriendlyName}
224
225
Example:
226
\begin{verbatim}
227
<key>ifdFriendlyName</key>
228
<string>SCM Microsystems USB Reader</string>
229
\end{verbatim}
230
231
\item \texttt{CFBundleExecutable}
232
233
The executable name which exists in the particular platform's directory.
234
235
Example:
236
\begin{verbatim}
237
<key>CFBundleExecutable</key>
238
<string>libccid.so.0.4.2</string>
239
\end{verbatim}
240
241
\end{itemize}
242
243
244
%---------%---------%---------%---------%---------%---------
245
\subsection{Serial readers}
246
247
Serial drivers must be configured to operate on a particular port and
248
respond to a particular name. The \texttt{reader.conf} file is used for
249
this purpose.
250
251
It has the following syntax:
252
253
\begin{verbatim}
254
# Configuration file for pcsc-lite
255
# David Corcoran <corcoran@musclecard.com>
256
257
FRIENDLYNAME Generic Reader
258
DEVICENAME /dev/ttyS0
259
LIBPATH /usr/lib/pcsc/drivers/libgen_ifd.so
260
CHANNELID 1
261
\end{verbatim}
262
263
\begin{itemize}
264
\item The pound sign \verb+#+ denotes a comment.
265
266
\item The \texttt{FRIENDLYNAME} field is an arbitrary text used to
267
identify the reader. This text is displayed by commands like
268
\texttt{pcsc\_scan}\footnote{\url{http://ludovic.rousseau.free.fr/softwares/pcsc-tools/}}
269
that prints the names of all the connected and detected readers.
270
271
\item The \texttt{DEVICENAME} field was not used for old drivers (using
272
the IFD handler version 2.0 or previous). It is now (IFD handler version
273
3.0) used to identify the physical port on which the reader is
274
connected. This is the device name of this port. It is dependent of the
275
OS kernel. For example the first serial port device is called
276
\texttt{/dev/ttyS0} under Linux and \texttt{/dev/cuaa0} under FreeBSD.
277
278
\item The \texttt{LIBPATH} field is the filename of the driver code. The
279
driver is a dynamically loaded piece of code (generally a
280
\texttt{drivername.so*} file).
281
282
\item The \texttt{CHANNELID} is no more used for recent drivers (IFD
283
handler 3.0) and has been superseded by \texttt{DEVICENAME}. If you
284
have an old driver this field is used to indicate the port to use. You
285
should read your driver documentation to know what information is needed
286
here. It should be the serial port number for a serial reader.
287
288
\texttt{CHANNELID} was the numeric version of the port in which the
289
reader will be located. This may be done by a symbolic link where
290
\texttt{/dev/pcsc/1} is the first device which may be a symbolic link to
291
\texttt{/dev/ttyS0} or whichever location your reader resides.
292
293
\end{itemize}
294
295
296
%---------%---------%---------%---------%---------%---------%---------
297
\section{API Routines}
298
299
The routines specified hereafter will allow you to write an IFD handler
300
for the PC/SC Lite resource manager. Please use the complement
301
developer's kit complete with headers and Makefile at:
302
\url{http://www.musclecard.com/drivers.html}.
303
304
This gives a common API for communication to most readers in a
305
homogeneous fashion. This document assumes that the driver developer is
306
experienced with standards such as ISO-7816-(1, 2, 3, 4), EMV and MCT
307
specifications. For listings of these specifications please access the
308
above web site.
309
310
311
%---------%---------%---------%---------%---------%---------
312
\subsection{IFDHCreateChannel}
313
314
\synopsis
315
316
\begin{verbatim}
317
#include <ifdhandler.h>
318
319
RESPONSECODE IFDHCreateChannel(DWORD Lun,
320
DWORD Channel);
321
\end{verbatim}
322
323
\parameters
324
325
\begin{tabular}{lll}
326
\texttt{Lun} & IN & Logical Unit Number \\
327
\texttt{Channel} & IN & Channel ID \\
328
\end{tabular}
329
330
\desc
331
332
This function is required to open a communications channel to the port
333
listed by \texttt{Channel}. For example, the first serial reader on COM1
334
would link to \texttt{/dev/pcsc/1} which would be a symbolic link to
335
\texttt{/dev/ttyS0} on some machines This is used to help with
336
inter-machine independence.
337
338
On machines with no \texttt{/dev} directory the driver writer may choose to
339
map their \texttt{Channel} to whatever they feel is appropriate.
340
341
Once the channel is opened the reader must be in a state in which it is
342
possible to query \texttt{IFDHICCPresence()} for card status.
343
344
\begin{itemize}
345
\item \texttt{Lun} - Logical Unit Number
346
347
Use this for multiple card slots or multiple readers.
348
\texttt{0xXXXXYYYY} - \texttt{XXXX} multiple readers, \texttt{YYYY}
349
multiple slots. The resource manager will set these automatically. By
350
default the resource manager loads a new instance of the driver so if
351
your reader does not have more than one smart card slot then ignore the
352
Lun in all the functions.
353
354
PC/SC supports the loading of multiple readers through one instance of
355
the driver in which \texttt{XXXX} is important. \texttt{XXXX} identifies
356
the unique reader in which the driver communicates to. The driver should
357
set up an array of structures that associate this \texttt{XXXX} with the
358
underlying details of the particular reader.
359
360
\item \texttt{Channel} - Channel ID
361
362
This is denoted by the following:
363
364
{\tt
365
\begin{tabular}{ll}
366
0x000001 & /dev/pcsc/1\\
367
0x000002 & /dev/pcsc/2\\
368
0x000003 & /dev/pcsc/3\\
369
0x000004 & /dev/pcsc/4\\
370
\end{tabular}
371
}
372
373
USB readers can ignore the \texttt{Channel} parameter and query the USB
374
bus for the particular reader by manufacturer and product id.
375
376
\end{itemize}
377
378
\returns
379
380
\begin{tabular}{ll}
381
\texttt{IFD\_SUCCESS} & Successful\\
382
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred
383
\end{tabular}
384
385
386
%---------%---------%---------%---------%---------%---------
387
\subsection{IFDHCreateChannelByName}
388
\label{IFDHCreateChannelByName}
389
390
\synopsis
391
\begin{verbatim}
392
#include <ifdhandler.h>
393
394
RESPONSECODE IFDHCreateChannelByName(DWORD Lun,
395
LPSTR deviceName);
396
\end{verbatim}
397
398
\parameters
399
400
\begin{tabular}{lll}
401
\texttt{Lun} & IN & Logical Unit Number \\
402
\texttt{DeviceName} & IN & String device path \\
403
\end{tabular}
404
405
406
\desc
407
408
This function is required to open a communications channel to the port
409
listed by \texttt{DeviceName}.
410
411
Once the channel is opened the reader must be in a state in which it is
412
possible to query \texttt{IFDHICCPresence()} for card status.
413
414
\begin{itemize}
415
\item \texttt{Lun} - Logical Unit Number
416
417
Use this for multiple card slots or multiple readers.
418
\texttt{0xXXXXYYYY} - \texttt{XXXX} multiple readers, \texttt{YYYY}
419
multiple slots. The resource manager will set these automatically. By
420
default the resource manager loads a new instance of the driver so if
421
your reader does not have more than one smart card slot then ignore the
422
Lun in all the functions.
423
424
PC/SC supports the loading of multiple readers through one instance of
425
the driver in which \texttt{XXXX} is important. \texttt{XXXX} identifies
426
the unique reader in which the driver communicates to. The driver should
427
set up an array of structures that associate this \texttt{XXXX} with the
428
underlying details of the particular reader.
429
430
\item \texttt{DeviceName} - filename to use by the driver.
431
432
For drivers configured by \texttt{/etc/reader.conf} this is the value of
433
the field \texttt{DEVICENAME}.
434
435
For USB drivers under platforms using
436
\texttt{libusb}\footnote{\url{http://libusb.sourceforge.net/}} for USB
437
abstraction (Any Unix except MacOSX) the \texttt{DeviceName} field uses
438
the string generated by:
439
\begin{verbatim}
440
printf("usb:%04x/%04x:libusb:%s:%s",
441
idVendor, idProduct,
442
bus->dirname, dev->filename)
443
\end{verbatim}
444
445
So it is something like: \texttt{usb:08e6/3437:libusb:001:042} under
446
Linux.
447
448
It is the responsability of the driver to correctly identify the reader.
449
This scheme was put in place to be able to distinguish two identical
450
readers connected at the same time.
451
452
\end{itemize}
453
454
\returns
455
456
\begin{tabular}{ll}
457
\texttt{IFD\_SUCCESS} & Successful\\
458
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred
459
\end{tabular}
460
461
462
%---------%---------%---------%---------%---------%---------
463
\subsection{IFDHCloseChannel}
464
465
\synopsis
466
\begin{verbatim}
467
#include <ifdhandler.h>
468
469
RESPONSECODE IFDHCloseChannel(DWORD Lun);
470
\end{verbatim}
471
472
\parameters
473
474
\begin{tabular}{lll}
475
\texttt{Lun} & IN & Logical Unit Number \\
476
\end{tabular}
477
478
\desc
479
480
This function should close the reader communication channel for the
481
particular reader. Prior to closing the communication channel the reader
482
should make sure the card is powered down and the terminal is also
483
powered down.
484
485
\returns
486
487
\begin{tabular}{ll}
488
\texttt{IFD\_SUCCESS} & Successful\\
489
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred
490
\end{tabular}
491
492
493
%---------%---------%---------%---------%---------%---------
494
\subsection{IFDHGetCapabilities}
495
496
\synopsis
497
\begin{verbatim}
498
#include <ifdhandler.h>
499
500
RESPONSECODE IFDHGetCapabilities(DWORD Lun,
501
DWORD Tag,
502
PDWORD Length,
503
PUCHAR Value);
504
\end{verbatim}
505
506
\parameters
507
508
\begin{tabular}{lll}
509
\texttt{Lun} & IN & Logical Unit Number \\
510
\texttt{Tag} & IN & Tag of the desired data value \\
511
\texttt{Length} & INOUT & Length of the desired data value \\
512
\texttt{Value} & OUT & Value of the desired data \\
513
\end{tabular}
514
515
\desc
516
517
This function should get the slot/card capabilities for a particular
518
slot/card specified by \texttt{Lun}. Again, if you have only 1 card slot
519
and don't mind loading a new driver for each reader then ignore
520
\texttt{Lun}.
521
522
\begin{itemize}
523
\item \texttt{Tag} - the tag for the information requested
524
525
\begin{itemize}
526
\item \texttt{TAG\_IFD\_ATR}
527
528
return the Atr and it's size (required).
529
530
\item \texttt{TAG\_IFD\_SIMULTANEOUS\_ACCESS}
531
532
return the number of sessions the driver can handle
533
534
this is used for multiple readers sharing the same driver
535
536
\item \texttt{TAG\_IFD\_SLOTS\_NUMBER}
537
538
return the number of slots in this reader
539
540
\end{itemize}
541
542
\item \texttt{Length} - the length of the returned data
543
544
\item \texttt{Value} - the value of the data
545
546
\end{itemize}
547
548
This function is also called when the application uses the PC/SC
549
\texttt{SCardGetAttrib()} function. The list of supported tags is not
550
limited. The ones above are used by the PC/SC lite resource manager.
551
552
\returns
553
554
\begin{tabular}{ll}
555
\texttt{IFD\_SUCCESS} & Successful\\
556
\texttt{IFD\_ERROR\_TAG} & Invalid tag given
557
\end{tabular}
558
559
560
%---------%---------%---------%---------%---------%---------
561
\subsection{IFDHSetCapabilities}
562
563
\synopsis
564
\begin{verbatim}
565
#include <ifdhandler.h>
566
567
RESPONSECODE IFDHSetCapabilities(DWORD Lun,
568
DWORD Tag,
569
DWORD Length,
570
PUCHAR Value);
571
\end{verbatim}
572
573
\parameters
574
575
\begin{tabular}{lll}
576
\texttt{Lun} & IN & Logical Unit Number\\
577
\texttt{Tag} & IN & Tag of the desired data value\\
578
\texttt{Length} & INOUT & Length of the desired data value\\
579
\texttt{Value} & OUT & Value of the desired data\\
580
\end{tabular}
581
582
\desc
583
584
This function should set the slot/card capabilities for a particular
585
slot/card specified by Lun. Again, if you have only 1 card slot and
586
don't mind loading a new driver for each reader then ignore Lun.
587
588
\begin{itemize}
589
\item \texttt{Tag} - the tag for the information needing set
590
\item \texttt{Length} - the length of the data
591
\item \texttt{Value} - the value of the data
592
\end{itemize}
593
594
This function is also called when the application uses the PC/SC
595
\texttt{SCardGetAttrib()} function. The list of supported tags is not limited.
596
597
\returns
598
599
\begin{tabular}{ll}
600
\texttt{IFD\_SUCCESS} & Success\\
601
\texttt{IFD\_ERROR\_TAG} & Invalid tag given\\
602
\texttt{IFD\_ERROR\_SET\_FAILURE} & Could not set value\\
603
\texttt{IFD\_ERROR\_VALUE\_READ\_ONLY} & Trying to set read only value
604
\end{tabular}
605
606
607
%---------%---------%---------%---------%---------%---------
608
\subsection{IFDHSetProtocolParameters}
609
610
\synopsis
611
\begin{verbatim}
612
#include <ifdhandler.h>
613
614
RESPONSECODE IFDHSetProtocolParameters(DWORD Lun,
615
DWORD Protocol,
616
UCHAR Flags,
617
UCHAR PTS1,
618
UCHAR PTS2,
619
UCHAR PTS3);
620
\end{verbatim}
621
622
\parameters
623
624
\begin{tabular}{lll}
625
\texttt{Lun} & IN & Logical Unit Number\\
626
\texttt{Protocol} & IN & Desired protocol\\
627
\texttt{Flags} & IN & OR'd Flags (See below)\\
628
\texttt{PTS1} & IN & 1st PTS Value\\
629
\texttt{PTS2} & IN & 2nd PTS Value\\
630
\texttt{PTS3} & IN & 3rd PTS Value\\
631
\end{tabular}
632
633
\desc
634
635
This function should set the Protocol Type Selection (PTS) of a
636
particular card/slot using the three PTS parameters sent
637
638
\begin{itemize}
639
\item \texttt{Protocol} - 0...14
640
641
T=0 to T=14 protocol
642
643
\item \texttt{Flags} - Logical OR of possible values to determine which PTS
644
values to negotiate
645
646
\begin{itemize}
647
\item \texttt{IFD\_NEGOTIATE\_PTS1}
648
\item \texttt{IFD\_NEGOTIATE\_PTS2}
649
\item \texttt{IFD\_NEGOTIATE\_PTS3}
650
\end{itemize}
651
652
\item \texttt{PTS1}, \texttt{PTS2}, \texttt{PTS3} - PTS Values
653
654
See ISO 7816/EMV documentation.
655
656
\end{itemize}
657
658
\returns
659
660
\begin{tabular}{ll}
661
\texttt{IFD\_SUCCESS} & Success\\
662
\texttt{IFD\_ERROR\_PTS\_FAILURE} & Could not set PTS value\\
663
\texttt{IFD\_COMMUNICATION\_ERROR} & Error has occurred\\
664
\texttt{IFD\_PROTOCOL\_NOT\_SUPPORTED} & Protocol is not supported\\
665
\end{tabular}
666
667
668
%---------%---------%---------%---------%---------%---------
669
\subsection{IFDHPowerICC}
670
671
\synopsis
672
\begin{verbatim}
673
#include <ifdhandler.h>
674
675
RESPONSECODE IFDHPowerICC(DWORD Lun,
676
DWORD Action,
677
PUCHAR Atr,
678
PDWORD AtrLength);
679
\end{verbatim}
680
681
\parameters
682
683
\begin{tabular}{lll}
684
\texttt{Lun} & IN & Logical Unit Number\\
685
\texttt{Action} & IN & Action to be taken\\
686
\texttt{Atr} & OUT & Answer to Reset (ATR) value of the inserted card\\
687
\texttt{AtrLength} & INOUT & Length of the ATR\\
688
\end{tabular}
689
690
\desc
691
692
This function controls the power and reset signals of the smart card
693
reader at the particular reader/slot specified by Lun.
694
695
\begin{itemize}
696
\item \texttt{Action} - Action to be taken on the card
697
698
\begin{itemize}
699
\item \texttt{IFD\_POWER\_UP}
700
701
Power and reset the card if not done so (store the ATR and return it and
702
it's length)
703
704
\item \texttt{IFD\_POWER\_DOWN}
705
706
Power down the card then power up if not done already (\texttt{Atr} and
707
\texttt{AtrLength} should be zeroed)
708
709
\item \texttt{IFD\_RESET}
710
711
Perform a quick reset on the card. If the card is not powered power up
712
the card. (Store and return \texttt{Atr} and \texttt{Length})
713
714
\end{itemize}
715
716
\item \texttt{Atr} - Answer to Reset of the card
717
718
The driver is responsible for caching this value in case
719
\texttt{IFDHGetCapabilities()} is called requesting the ATR and it's
720
length. The ATR length should not exceed \texttt{MAX\_ATR\_SIZE}.
721
722
\item \texttt{AtrLength} - Length of the Atr
723
724
This should not exceed \texttt{MAX\_ATR\_SIZE}.
725
726
\end{itemize}
727
728
\textbf{Notes:}
729
730
Memory cards without an ATR should return \texttt{IFD\_SUCCESS} on reset
731
but the \texttt{Atr} should be zeroed and the length should be zero
732
Reset errors should return zero for the \texttt{AtrLength} and return
733
\texttt{IFD\_ERROR\_POWER\_ACTION}.
734
735
\returns
736
737
\begin{tabular}{ll}
738
\texttt{IFD\_SUCCESS} & Success\\
739
\texttt{IFD\_ERROR\_POWER\_ACTION} & Error powering/resetting card\\
740
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred\\
741
\texttt{IFD\_NOT\_SUPPORTED} & Action not supported\\
742
\end{tabular}
743
744
745
%---------%---------%---------%---------%---------%---------
746
\subsection{IFDHTransmitToICC}
747
748
\synopsis
749
\begin{verbatim}
750
#include <ifdhandler.h>
751
752
RESPONSECODE IFDHTransmitToICC(DWORD Lun,
753
SCARD_IO_HEADER SendPci,
754
PUCHAR TxBuffer,
755
DWORD TxLength,
756
PUCHAR RxBuffer,
757
PDWORD RxLength,
758
PSCARD_IO_HEADER RecvPci);
759
\end{verbatim}
760
761
\parameters
762
763
\begin{tabular}{lll}
764
\texttt{Lun} & IN & Logical Unit Number\\
765
\texttt{SendPci} & IN & Protocol structure\\
766
\texttt{TxBuffer} & IN & APDU to be sent\\
767
\texttt{TxLength} & IN & Length of sent APDU\\
768
\texttt{RxBuffer} & OUT & APDU response\\
769
\texttt{RxLength} & INOUT & Length of APDU response\\
770
\texttt{RecvPci} & INOUT & Receive protocol structure
771
\end{tabular}
772
773
\desc
774
775
This function performs an APDU exchange with the card/slot specified by
776
\texttt{Lun}. The driver is responsible for performing any protocol
777
specific exchanges such as T=0, 1, etc. differences. Calling this function
778
will abstract all protocol differences.
779
780
\begin{itemize}
781
\item \texttt{SendPci} - contains two structure members
782
783
\begin{itemize}
784
\item \texttt{Protocol} - 0, 1, ... 14
785
786
T=0 ... T=14
787
788
\item \texttt{Length} \tab - Not used.
789
\end{itemize}
790
791
\item \texttt{TxBuffer} \tab - Transmit APDU
792
793
example: \verb+"\x00\xA4\x00\x00\x02\x3F\x00"+
794
795
\item \texttt{TxLength} \tab - Length of this buffer
796
\item \texttt{RxBuffer} \tab - Receive APDU
797
798
example: \verb+"\x61\x14"+
799
800
\item \texttt{RxLength} \tab - Length of the received APDU
801
802
This function will be passed the size of the buffer of \texttt{RxBuffer}
803
and this function is responsible for setting this to the length of the
804
received APDU response. This should be ZERO on all errors. The resource
805
manager will take responsibility of zeroing out any temporary APDU
806
buffers for security reasons.
807
808
\item \texttt{RecvPci} - contains two structure members
809
810
\begin{itemize}
811
\item \texttt{Protocol} - 0, 1, ... 14
812
813
T=0 ... T=14
814
815
\item \texttt{Length} - Not used.
816
\end{itemize}
817
\end{itemize}
818
819
\textbf{Notes:}
820
821
The driver is responsible for knowing what type of card it has. If the
822
current slot/card contains a memory card then this command should ignore
823
the \texttt{Protocol} and use the MCT style commands for support for
824
these style cards and transmit them appropriately. If your reader does
825
not support memory cards or you don't want to implement this
826
functionality, then ignore this.
827
828
\texttt{RxLength} should be set to zero on error.
829
830
The driver is \emph{not} responsible for doing an automatic Get Response
831
command for received buffers containing \texttt{61 XX}.
832
833
\returns
834
835
\begin{tabular}{ll}
836
\texttt{IFD\_SUCCESS} & Success\\
837
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred\\
838
\texttt{IFD\_RESPONSE\_TIMEOUT} & The response timed out\\
839
\texttt{IFD\_ICC\_NOT\_PRESENT} & ICC is not present\\
840
\texttt{IFD\_PROTOCOL\_NOT\_SUPPORTED} & Protocol is not supported
841
\end{tabular}
842
843
844
%---------%---------%---------%---------%---------%---------
845
\subsection{IFDHControl}
846
\label{IFDHControl}
847
848
\synopsis
849
\begin{verbatim}
850
#include <ifdhandler.h>
851
852
RESPONSECODE IFDHControl(DWORD Lun,
853
DWORD dwControlCode,
854
PUCHAR TxBuffer,
855
DWORD TxLength,
856
PUCHAR RxBuffer,
857
PDWORD RxLength,
858
PDWORD pdwBytesReturned);
859
\end{verbatim}
860
861
\parameters
862
863
\begin{tabular}{lll}
864
\texttt{Lun} & IN & Logical Unit Number\\
865
\texttt{dwControlCode} & IN & Control code for the operation\\
866
\texttt{TxBuffer} & IN & Bytes to be sent\\
867
\texttt{TxLength} & IN & Length of sent bytes\\
868
\texttt{RxBuffer} & OUT & Response\\
869
\texttt{RxLength} & IN & Length of response buffer\\
870
\texttt{pdwBytesReturned} & OUT & Length of response \\
871
\end{tabular}
872
873
\desc
874
875
This function performs a data exchange with the reader (not the card)
876
specified by \texttt{Lun}. It is responsible for abstracting
877
functionality such as PIN pads, biometrics, LCD panels, etc. You should
878
follow the MCT and CTBCS specifications for a list of accepted commands
879
to implement. This function is fully voluntary and does not have to be
880
implemented unless you want extended functionality.
881
882
\begin{itemize}
883
\item \texttt{dwControlCode} - Control code for the operation
884
885
This value identifies the specific operation to be performed. This value
886
is driver specific.
887
888
\item \texttt{TxBuffer} - Transmit data
889
\item \texttt{TxLength} - Length of this buffer
890
\item \texttt{RxBuffer} - Receive data
891
\item \texttt{RxLength} - Length of the response buffer
892
893
\item \texttt{pdwBytesReturned} - Length of response
894
895
This function will be passed the length of the buffer \texttt{RxBuffer}
896
in \texttt{RxLength} and it must set the length of the received data in
897
\texttt{pdwBytesReturned}.
898
899
\end{itemize}
900
901
\textbf{Notes:}
902
903
\texttt{*pdwBytesReturned} should be set to zero on error.
904
905
\returns
906
907
\begin{tabular}{ll}
908
\texttt{IFD\_SUCCESS} & Success\\
909
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred\\
910
\texttt{IFD\_RESPONSE\_TIMEOUT} & The response timed out
911
\end{tabular}
912
913
914
%---------%---------%---------%---------%---------%---------
915
\subsection{IFDHICCPresence}
916
917
\synopsis
918
\begin{verbatim}
919
#include <ifdhandler.h>
920
921
RESPONSECODE IFDHICCPresence(DWORD Lun);
922
\end{verbatim}
923
924
\parameters
925
926
\begin{tabular}{lll}
927
\texttt{Lun} & IN & Logical Unit Number
928
\end{tabular}
929
930
\desc
931
932
This function returns the status of the card inserted in the reader/slot
933
specified by \texttt{Lun}. In cases where the device supports
934
asynchronous card insertion/removal detection, it is advised that the
935
driver manages this through a thread so the driver does not have to send
936
and receive a command each time this function is called.
937
938
\returns
939
940
\begin{tabular}{ll}
941
\texttt{IFD\_ICC\_PRESENT} & ICC is present\\
942
\texttt{IFD\_ICC\_NOT\_PRESENT} & ICC is not present\\
943
\texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred
944
\end{tabular}
945
946
947
%---------%---------%---------%---------%---------%---------%---------
948
\section{API changes}
949
950
The IFD handler API changed over the time.
951
952
If the driver provides a \texttt{IFDHCreateChannelByName()} function is
953
supposed to use API v3.0. Otherwise it is used with API v2.0.
954
955
956
%---------%---------%---------%---------%---------%---------
957
\subsection{API version 2.0}
958
959
\begin{itemize}
960
\item \texttt{DEVICENAME} in \texttt{reader.conf} is not used.
961
962
\item \texttt{IFDHControl()} API was:
963
\begin{verbatim}
964
RESPONSECODE IFDHControl(DWORD Lun,
965
PUCHAR TxBuffer,
966
DWORD TxLength,
967
PUCHAR RxBuffer,
968
PDWORD RxLength);
969
\end{verbatim}
970
971
\end{itemize}
972
973
974
%---------%---------%---------%---------%---------%---------
975
\subsection{API version 3.0}
976
977
\begin{itemize}
978
\item introduction of \texttt{IFDHCreateChannelByName()}.
979
980
For serial drivers, \texttt{CHANNELID} is no more used and
981
\texttt{DEVICENAME} is used instead.
982
983
For USB drivers the device name if \verb+usb:%04x/%04x:libusb:%s:%s+.
984
See \ref{IFDHCreateChannelByName}.
985
986
\item \texttt{IFDHControl()} API changed
987
988
See \ref{IFDHControl}.
989
990
\end{itemize}
991
992
993
\end{document}
994
Loggerhead is a web-based interface for Breezy
Version: 2.0.1