Chipcard::PCSC::Card(3pm)

1Card(3)               User Contributed Perl Documentation              Card(3)
2
3
4

NAME

6       Chipcard::PCSC::Card - Smart card communication library
7

SYNOPSIS

9        $hCard = new Chipcard::PCSC::Card ($hContext, "GemPC430 0 0",
10               $Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE);
11
12        $RecvData = $hCard->Transmit([0xBC,0xB0,0x09,0xC8, 2]);
13
14        $hCard->Disconnect($Chipcard::PCSC::SCARD_LEAVE_CARD);
15
16        $hCard->Status();
17
18        $hCard->BeginTransaction();
19
20        $hCard->EndTransaction();
21
22        $hCard->TransmitWithCheck($apdu, $sw_expected [, $debug]);
23
24        $hCard->Control($control_code, \@data);
25
26        ISO7816Error($sw);
27

DESCRIPTION

29       The "Chipcard::PCSC::Card" module implements the "Chipcard::PCSC::Card"
30       class. Objects from this class are used to communicate with a given
31       reader. They are constructed out of a reference to a PCSC object that
32       drives the reader.
33
34       For more information about PC/SC please read the pcscd(1) man page.
35
36       A "Chipcard::PCSC::Card" object uses the following property:
37
38       •   $pcsccard_object->{hContext}
39
40           the reference to the underlying PCSC object
41
42       •   $pcsccard_object->{hCard}
43
44           the current PCSC connection handle
45
46       •   $pcsccard_object->{dwProtocol}
47
48           the protocol being used
49

CONSTRUCTORS

51       The following methods construct a "Chipcard::PCSC::Card" object:
52
53       •   $hCard = new Chipcard::PCSC::Card ($hContext);
54
55           Constructs a new "Chipcard::PCSC::Card" object without connecting
56           to any reader.
57
58           $hContext is mandatory and contains the reference to a valid PCSC
59           object.
60
61       •   $hCard = new Chipcard::PCSC::Card ($hContext, $reader_name,
62           $share_mode, $preferred_protocol);
63
64           Constructs a new Chipcard::PCSC::Card object and connect to the
65           specified reader.
66
67           •   $hContext
68
69               is mandatory and contains the reference to a valid PCSC object.
70
71           •   $reader_name
72
73               is the name of the reader you want to connect to. It is of the
74               form "GemPC410 0 0".
75
76               Please note that the list of available readers can be obtained
77               with a call to "$hContext->ListReaders()". (See the section
78               named PCSC METHODS in the Chipcard::PCSC man page for more
79               information on "ListReaders").
80
81           •   $share_mode
82
83               is the desired mode of connection to the reader. It can be any
84               of the following:
85
86               •   $Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE
87
88                   the application do not share the reader
89
90               •   $Chipcard::PCSC::SCARD_SHARE_SHARED
91
92                   the application will allow others to share the reader.
93
94               •   $Chipcard::PCSC::SCARD_SHARE_DIRECT
95
96                   (not used by PC/SC-lite)
97
98           •   $preferred_protocol
99
100               is the protocol which should be used if possible.  If the
101               protocol is not available, another protocol will be used and
102               "$hCard->{dwProtocol}" will be set accordingly. Both
103               "$hCard->{dwProtocol}" and $preferred_protocol accept the
104               following values:
105
106               •   $Chipcard::PCSC::SCARD_PROTOCOL_T0
107
108                   the T=0 protocol
109
110               •   $Chipcard::PCSC::SCARD_PROTOCOL_T1
111
112                   the T=1 protocol
113
114               •   $Chipcard::PCSC::SCARD_PROTOCOL_RAW
115
116                   raw protocol
117
118       •   $hCard = new Chipcard::PCSC::Card ($hContext, $reader_name,
119           $share_mode);
120
121           This method is equivalent to:
122
123            $hCard = new Chipcard::PCSC::Card ($hContext, $reader_name,
124               $share_mode,
125               $Chipcard::PCSC::SCARD_PROTOCOL_T0 |
126               $Chipcard::PCSC::SCARD_PROTOCOL_T1);
127
128       •   $hCard = new Chipcard::PCSC::Card ($hContext, $reader_name);
129
130           This method is equivalent to:
131
132            $hCard = new Chipcard::PCSC::Card ($hContext, $reader_name,
133               $Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE,
134               $Chipcard::PCSC::SCARD_PROTOCOL_T0 |
135               $Chipcard::PCSC::SCARD_PROTOCOL_T1);
136

CONSTRUCTION FAILURE

138       "Chipcard::PCSC::Card" constructors return an "undef" value when the
139       object can not be created. $Chipcard::PCSC::errno can be used to get
140       more information about the error. See section ERROR HANDLING in
141       Chipcard::PCSC man page for more information.
142

Chipcard::PCSC::Card METHODS

144       Here is a list of all the methods that can be used with a
145       "Chipcard::PCSC::Card" object.
146
147    $hCard->Connect($reader_name, $share_mode, $preferred_protocol);
148       "Connect()" can be used to connect to the reader and its smart card if
149       the connection has not been established yet. The default constructor
150       can establish the connection if given enough parameters.
151
152       The return value upon successful completion is the protocol used to
153       communicate with the smart card. It can be any of the following:
154
155       •   $Chipcard::PCSC::SCARD_PROTOCOL_T0
156
157           the T=0 protocol
158
159       •   $Chipcard::PCSC::SCARD_PROTOCOL_T1
160
161           the T=1 protocol
162
163       •   $Chipcard::PCSC::SCARD_PROTOCOL_RAW
164
165           raw protocol
166
167       •   $reader_name
168
169           is mandatory. It contains the name of the reader you want to
170           connect to.  It is of the form "GemPC410 0 0".
171
172           Please note that the list of available readers can be obtained with
173           a call to "$hContext->ListReaders()". (See the section named PCSC
174           METHODS in the Chipcard::PCSC man page for more information on
175           "ListReaders").
176
177       •   $share_mode
178
179           is the desired mode of connection to the reader. It can be any of
180           the following:
181
182           •   $Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE
183
184               the application do not share the reader
185
186           •   $Chipcard::PCSC::SCARD_SHARE_SHARED
187
188               the application will allow others to share the reader.
189
190           •   $Chipcard::PCSC::SCARD_SHARE_DIRECT
191
192               (not used by PCSClite)
193
194       •   $preferred_protocol
195
196           is the protocol which should be used if possible. If the protocol
197           is not available, another protocol will be used and
198           "$hCard->{dwProtocol}" will be set accordingly.
199           $preferred_protocol accept the following values:
200
201           •   $Chipcard::PCSC::SCARD_PROTOCOL_T0
202
203               the T=0 protocol
204
205           •   $Chipcard::PCSC::SCARD_PROTOCOL_T1
206
207               the T=1 protocol
208
209           •   $Chipcard::PCSC::SCARD_PROTOCOL_RAW
210
211               raw protocol
212
213    $hCard->Connect($reader_name, $share_mode);
214       This method is equivalent to:
215
216        $hCard->Connect($reader_name, $share_mode,
217           $Chipcard::PCSC::SCARD_PROTOCOL_T0 |
218           $Chipcard::PCSC::SCARD_PROTOCOL_T1);
219
220    $hCard->Connect($reader_name);
221       This method is equivalent to:
222
223        $hCard->Connect($reader_name, $Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE,
224           $Chipcard::PCSC::SCARD_PROTOCOL_T0 |
225           $Chipcard::PCSC::SCARD_PROTOCOL_T1);
226
227    $hCard->Reconnect($share_mode, $preferred_protocol, $initialization);
228       "Reconnect()" can be used to re-negotiate an already opened connection.
229       This implies that the "Chipcard::PCSC::Card" object is connected and
230       has "$hCard->{hCard}" set accordingly.
231
232       Reconnecting to a smart card is used to change the share mode and the
233       current protocol.
234
235       The return value upon successful completion is the protocol choose to
236       communicate with the smart card. It can be any of the following:
237
238       •   $Chipcard::PCSC::SCARD_PROTOCOL_T0
239
240           the T=0 protocol
241
242       •   $Chipcard::PCSC::SCARD_PROTOCOL_T1
243
244           the T=1 protocol
245
246       •   $Chipcard::PCSC::SCARD_PROTOCOL_RAW
247
248           raw protocol
249
250       •   $share_mode
251
252           is the desired mode of connection to the reader. It can be any of
253           the following:
254
255           •   $Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE
256
257               the application do not share the reader
258
259           •   $Chipcard::PCSC::SCARD_SHARE_SHARED
260
261               the application will allow others to share the reader.
262
263           •   $Chipcard::PCSC::SCARD_SHARE_DIRECT
264
265               (not used by PCSClite)
266
267       •   $preferred_protocol
268
269           is the protocol which should be used if possible. If the protocol
270           is not available, another protocol will be used and
271           "$hCard->{dwProtocol}" will be set accordingly.
272           $preferred_protocol accept the following values:
273
274           •   $Chipcard::PCSC::SCARD_PROTOCOL_T0
275
276               the T=0 protocol
277
278           •   $Chipcard::PCSC::SCARD_PROTOCOL_T1
279
280               the T=1 protocol
281
282           •   $Chipcard::PCSC::SCARD_PROTOCOL_RAW
283
284               raw protocol
285
286       •   $initialization
287
288           is the action to take when reconnecting to the smart card. It can
289           be any of the following values:
290
291           •   $Chipcard::PCSC::SCARD_LEAVE_CARD
292
293               do nothing on close
294
295           •   $Chipcard::PCSC::SCARD_RESET_CARD
296
297               reset on close
298
299           •   $Chipcard::PCSC::SCARD_UNPOWER_CARD
300
301               power down on close
302
303           •   $Chipcard::PCSC::SCARD_EJECT_CARD
304
305               eject on close
306
307    $hCard->Reconnect($share_mode, $preferred_protocol);
308       This method is equivalent to:
309
310        $hCard->Reconnect($share_mode, $preferred_protocol,
311           $Chipcard::PCSC::SCARD_LEAVE_CARD);
312
313    $hCard->Reconnect($share_mode);
314       This method is equivalent to:
315
316        $hCard->Reconnect($share_mode,
317           $Chipcard::PCSC::SCARD_PROTOCOL_T0 |
318           $Chipcard::PCSC::SCARD_PROTOCOL_T1,
319           $Chipcard::PCSC::SCARD_LEAVE_CARD);
320
321    $hCard->Reconnect();
322       This method is equivalent to:
323
324        $hCard->Reconnect($Chipcard::PCSC::SCARD_SHARE_EXCLUSIVE,
325           $Chipcard::PCSC::SCARD_PROTOCOL_T0 |
326           $Chipcard::PCSC::SCARD_PROTOCOL_T1,
327           $Chipcard::PCSC::SCARD_LEAVE_CARD);
328
329    $hCard->Disconnect($initialization);
330       "Disconnect()" closes the connection to the smart card reader. It
331       returns true upon successful completion or undef otherwise.
332       "$hCard->{hContext}" will be set to undef if the connection is
333       successfully closed.
334
335       •   $initialization
336
337           is the action to take when reconnecting to the smart card. It can
338           be any of the following values:
339
340           •   $Chipcard::PCSC::SCARD_LEAVE_CARD
341
342               do nothing on close
343
344           •   $Chipcard::PCSC::SCARD_RESET_CARD
345
346               reset on close
347
348           •   $Chipcard::PCSC::SCARD_UNPOWER_CARD
349
350               power down on close
351
352           •   $Chipcard::PCSC::SCARD_EJECT_CARD
353
354               eject on close
355
356    $hCard->Disconnect();
357       This method is equivalent to:
358
359        $hCard->Disconnect($Chipcard::PCSC::SCARD_EJECT_CARD);
360
361    $hCard->Status();
362       "Status()" returns the current status of the connection to a smart
363       card.  It is used to retrieve the ATR (Answer To Reset) value as well
364       as the protocol being used to communicate.
365
366       The return value is the "undef" value if an error occurs. In such a
367       case, $! should be set with a string describing the error. Upon
368       successful completion "Status" returns an array as follows:
369       ($reader_name, $reader_state, $protocol, "\@atr")
370
371       •   $reader_name
372
373           is a string containing the name of the reader
374
375       •   $reader_state
376
377           is a scalar containing the current state of the reader.
378
379           It can be any combination of the following values:
380
381           •    $Chipcard::PCSC::SCARD_UNKNOWN
382
383                unknown state
384
385           •    $Chipcard::PCSC::SCARD_ABSENT
386
387                card is absent
388
389           •    $Chipcard::PCSC::SCARD_PRESENT
390
391                card is present
392
393           •    $Chipcard::PCSC::SCARD_SWALLOWED
394
395                card not powered
396
397           •    $Chipcard::PCSC::SCARD_POWERED
398
399                card is powered
400
401           •    $Chipcard::PCSC::SCARD_NEGOTIABLE
402
403                ready for PTS
404
405           •    $Chipcard::PCSC::SCARD_SPECIFIC
406
407                PTS has been set
408
409       •   $protocol
410
411           is the protocol being used. It can be any of the following values:
412
413           •    $Chipcard::PCSC::SCARD_PROTOCOL_T0,
414
415           •    $Chipcard::PCSC::SCARD_PROTOCOL_T1,
416
417           •    $Chipcard::PCSC::SCARD_PROTOCOL_RAW
418
419       •   \@atr
420
421           is a reference to an array containing the ATR. Each cell of the
422           array contains one byte of the ATR. This parameter is however
423           optional as the ATR may not be available under some circumstances.
424           For instance when the card is not inserted, no ATR can be returned
425           and this parameter will be "undef".
426
427    $hCard->Transmit(\@data);
428       "Transmit()" is used to exchange data with the card.
429
430       It returns a reference to an anonymous array holding the answer to the
431       emitted data. In case of an error, the reference is the "undef" value.
432
433       •   \@data
434
435           is a reference to the data to be sent to the card.
436
437       Here is a small sample of how to use "transmit":
438
439        $SendData = [0x00, 0xA4, 0x01, 0x00, 0x02, 0x01, 0x00];
440        $RecvData = $hCard->Transmit($SendData);
441
442        print "  Recv = ";
443        foreach $tmpVal (@{$RecvData}) {
444            printf ("%02X ", $tmpVal);
445        } print "\n";
446
447    $hCard->BeginTransaction();
448       "BeginTransaction()" is used to temporarily get exclusive control over
449       the smart card.
450
451       It returns TRUE upon successful completion and FALSE otherwise.
452       $Chipcard::PCSC::errno should be set accordingly in case of an error.
453       See section ERROR HANDLING in Chipcard::PCSC man page for more
454       information.
455
456    $hCard->EndTransaction($disposition);
457       "EndTransaction()" is used to end a transaction initiated with
458       "BeginTransaction()".
459
460       It returns "TRUE" upon successful completion and FALSE otherwise.
461       $Chipcard::PCSC::errno should be set accordingly in case of an error.
462       See section ERROR HANDLING in Chipcard::PCSC man page for more
463       information.
464
465       •   $disposition
466
467           is the action to take when ending the transaction. It can be any of
468           the following values:
469
470           •   $Chipcard::PCSC::SCARD_LEAVE_CARD
471
472               do nothing on close
473
474           •   $Chipcard::PCSC::SCARD_RESET_CARD
475
476               reset on close
477
478           •   $Chipcard::PCSC::SCARD_UNPOWER_CARD
479
480               power down on close
481
482           •   $Chipcard::PCSC::SCARD_EJECT_CARD
483
484               eject on close
485
486    $hCard->EndTransaction();
487       This method is equivalent to:
488
489        $hCard->EndTransaction($Chipcard::PCSC::SCARD_LEAVE_CARD);
490
491    $hCard->TransmitWithCheck($apdu, $sw_expected [, $debug]);
492       This method is a wrapper around $hCard->Transmit(). The $apdu parameter
493       is an ASCII text like "00 A4 01 00 02 01 00", $sw_expected is a Perl
494       regular expression like "90 [01]0".
495
496       If the status word returned matches the expression $sw_expected the
497       method returns a list ($sw, $recv). $sw is the status word (like "90
498       00") of the command, $recv is the result of the command.
499
500       If the status word do not match the expression $sw_expected the method
501       returns undef and the variable $Chipcard::PCSC::Card::Error is set.
502
503       The $debug argument is optional. If present the method will print on
504       stdout the command sent and the response from the card.
505
506       Example:
507
508        ($sw, $RecvData) = $hCard->TransmitWithCheck($SendData, "6E 00", 1);
509        warn "TransmitWithCheck: $Chipcard::PCSC::Card::Error" unless defined $sw;
510
511    $hCard->Control($control_code, \@data);
512       This method uses PC/SC SCardControl() to send data specific to the
513       reader driver. See your driver documentation to know what data to use.
514
515       Example:
516
517        $data = Chipcard::PCSC::ascii_to_array ("01 23 45");
518        $RecvData = $hCard->Control(0x42000001, $SendData);
519        die ("Can't Control data: $Chipcard::PCSC::errno") unless (defined ($RecvData));
520
521    ISO7816Error($sw);
522       This method returns the ASCII text corresponding to the status word $sw
523       according to ISO 7816-4 specifications.
524
525       Example:
526
527        $sw = "90 00";
528        print "$sw: " . &Chipcard::PCSC::Card::ISO7816Error($sw) . "\n";
529

COPYRIGHT

536       (C) Lionel VICTOR, 2001, GNU GPL
537
538       (C) Ludovic ROUSSEAU, 2003-2008, GNU GPL
539

AUTHORS / ACKNOWLEDGEMENT

541        Lionel VICTOR <lionel.victor@unforgettable.com>
542                      <lionel.victor@free.fr>
543
544        Ludovic ROUSSEAU <ludovic.rousseau@free.fr>
545
546
547
548perl v5.34.0                      2021-07-22                           Card(3)