Chipcard::PCSC::Card(3pm)

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

NAME

6       Chipcard::PCSC::Card - Smarcard 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           the reference to the underlying PCSC object
40
41       * $pcsccard_object->{hCard}
42           the current PCSC connection handle
43
44       * $pcsccard_object->{dwProtocol}
45           the protocol being used
46

CONSTRUCTORS

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

CONSTRUCTION FAILURE

121       "Chipcard::PCSC::Card" constructors return an "undef" value when the
122       object can not be created. $Chipcard::PCSC::errno can be used to get
123       more information about the error. See section ERROR HANDLING in Chip‐
124       card::PCSC man page for more information.
125

Chipcard::PCSC::Card METHODS

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

COPYRIGHT

482       (C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2003, GNU GPL
483

AUTHORS / ACKNOWLEDGEMENT

485        Lionel VICTOR <lionel.victor@unforgettable.com>
486                      <lionel.victor@free.fr>
487
488        Ludovic ROUSSEAU <ludovic.rousseau@free.fr>
489
490
491
492perl v5.8.8                       2006-06-18                           Card(3)