NAME
Chipcard::PCSC - Smart card reader interface library
SYNOPSIS
my
$hContext
= new Chipcard::PCSC();
@ReadersList
=
$hContext
->ListReaders ();
$hContext
->GetStatusChange(\
@readers_states
,
$timeout
);
$apdu
= Chipcard::PCSC::array_to_ascii(
@apdu
);
@apdu
= Chipcard::PCSC::ascii_to_array(
$apdu
);
$hContext
=
undef
;
DESCRIPTION
The PCSC module implements the Chipcard::PCSC class. Objects of this class are used to communicate with the PCSC-lite daemon (see pcscd(1) for more information).
PC/SC represents an abstraction layer to smart card readers. It provides a communication layer with a wide variety of smart card readers through a standardized API.
A PCSC object can be used to communicate with more than one reader through Chipcard::PCSC::Card objects. Please read Chipcard::PCSC::Card for extended information on how to talk to a smart card reader.
A PCSC object uses the following property: $pcsc_object->{hContext}
the context returned by the pcsc library
CONSTRUCTORS
The following methods can be used to construct a PCSC object:
$hContext = new Chipcard::PCSC($scope, $remote_host);
$scope
is the scope of the connection to the PC/SC daemon. It can be any of the following:$Chipcard::PCSC::SCARD_SCOPE_USER
(not used by PCSClite);
$Chipcard::PCSC::SCARD_SCOPE_TERMINAL
(not used by PCSClite);
$Chipcard::PCSC::SCARD_SCOPE_SYSTEM
Services on the
local
machine;
$Chipcard::PCSC::SCARD_SCOPE_GLOBAL
Services on a remote host.
$remote_host
is the host name of the remote machine to contact. It is only used when$scope
is equal to$Chipcard::PCSC::SCARD_SCOPE_GLOBAL
. A null value means localhost.
$hContext = new Chipcard::PCSC($scope);
This method is equivalent to:
$hContext
= new Chipcard::PCSC(
$scope
, 0);
$hContext = new Chipcard::PCSC();
This method is equivalent to:
$hContext
= new Chipcard::PCSC(
$Chipcard::PCSC::SCARD_SCOPE_SYSTEM
, 0);
CONSTRUCTION FAILURE
Chipcard::PCSC constructors return an undef
value when the object can not be created. $Chipcard::PCSC::errno
can be used to get more information about the error. (See section "ERROR HANDLING" below for more information)
Chipcard::PCSC METHODS
Here is a list of all the methods that can be used with a PCSC object.
hContext->ListReaders( $group );
This method returns the available readers in the given
$group
. If omitted,$group
defaults to a null value meaning "all groups". Please note that as of this writing,$group
can safely be omitted as it is not used by PCSClite.The return value upon successful completion is an array of strings: one string by available reader. If an error occurred, the undef value is returned and
$Chipcard::PCSC::errno
should be used to get more information about the error. (See section "ERROR HANDLING" below for more information). The following example describes the use of ListReaders:$hContext
= new Chipcard::PCSC();
die
(
"Can't create the PCSC object: $Chipcard::PCSC::errno\n"
)
unless
(
defined
$hContext
);
@ReadersList
=
$hContext
->ListReaders ();
die
(
"Can't get readers' list: $Chipcard::PCSC::errno\n"
)
unless
(
defined
(
$ReadersList
[0]));
$, =
"\n "
;
print
@ReadersList
.
"\n"
;
$hContext->GetStatusChange(\@readers_states, $timeout);
The method
$hContext->GetStatusChange(\@readers_states, $timeout)
uses a reference to a list of hashes.# create the list or readers to watch
map
{
push
@readers_states
, ({
'reader_name'
=>
"$_"
}) }
@ReadersList
;
@StatusResult
=
$hContext
->GetStatusChange(\
@readers_states
);
The keys of the hash are: 'reader_name', 'current_state', 'event_state' and 'ATR'.
To detect a status change you have to first get the status and then copy the 'event_state' in the 'current_state'. The method will return when both states are different or a timeout occurs.
@StatusResult
=
$hContext
->GetStatusChange(\
@readers_states
);
foreach
$reader
(
@readers_states
)
{
$reader
->{current_state} =
$reader
->{event_state};
}
@StatusResult
=
$hContext
->GetStatusChange(\
@readers_states
);
$hContext->GetStatusChange(\@readers_states);
This method is equivalent to:
$hContext
->GetStatusChange(\
@readers_states
, 0xFFFFFFFF);
The timeout is set to infinite.
$apdu_ref = Chipcard::PCSC::ascii_to_array($apdu);
The method
Chipcard::PCSC::Card::Transmit()
uses references to arrays as in and out parameters. TheChipcard::PCSC::ascii_to_array()
is used to transform an APDU in ASCII format to a reference to an array in the good format.Example:
$SendData
= Chipcard::PCSC::ascii_to_array(
"00 A4 01 00 02 01 00"
);
$apdu = Chipcard::PCSC::array_to_ascii($apdu_ref);
This method is used to convert the result of a
Chipcard::PCSC::Card::Transmit()
into ASCII format.Example:
$RecvData
=
$hCard
->Transmit(
$SendData
);
print
Chipcard::PCSC::array_to_ascii(
$RecvData
);
ERROR HANDLING
All functions from PCSC objects save the return value in a global variable called $Chipcard::PCSC::errno
. This variable therefore holds the latest status of PCSC.
It is a double-typed magical variable that behaves just like $!
. This means that it both holds a numerical value describing the error and the corresponding string. The numerical value may change from a system to another as it depends on the PCSC library...
Here is a small example of how to use it:
$hContext
= new Chipcard::PCSC();
die
(
"Can't create the PCSC object: $Chipcard::PCSC::errno\n"
)
unless
(
defined
$hContext
);
In case the last call was successful, $Chipcard::PCSC::errno
contains the SCARD_S_SUCCESS
status. Here is a list of all possible error codes. They are defined as read-only variables with in the PCSC module:
$Chipcard::PCSC::SCARD_S_SUCCESS
$Chipcard::PCSC::SCARD_E_CANCELLED
$Chipcard::PCSC::SCARD_E_CANT_DISPOSE
$Chipcard::PCSC::SCARD_E_CARD_UNSUPPORTED
$Chipcard::PCSC::SCARD_E_DUPLICATE_READER
$Chipcard::PCSC::SCARD_E_INSUFFICIENT_BUFFER
$Chipcard::PCSC::SCARD_E_INVALID_ATR
$Chipcard::PCSC::SCARD_E_INVALID_HANDLE
$Chipcard::PCSC::SCARD_E_INVALID_PARAMETER
$Chipcard::PCSC::SCARD_E_INVALID_TARGET
$Chipcard::PCSC::SCARD_E_INVALID_VALUE
$Chipcard::PCSC::SCARD_E_NO_MEMORY
$Chipcard::PCSC::SCARD_E_NO_SERVICE
$Chipcard::PCSC::SCARD_E_NO_SMARTCARD
$Chipcard::PCSC::SCARD_E_NOT_READY
$Chipcard::PCSC::SCARD_E_NOT_TRANSACTED
$Chipcard::PCSC::SCARD_E_PCI_TOO_SMALL
$Chipcard::PCSC::SCARD_E_PROTO_MISMATCH
$Chipcard::PCSC::SCARD_E_READER_UNAVAILABLE
$Chipcard::PCSC::SCARD_E_READER_UNSUPPORTED
$Chipcard::PCSC::SCARD_E_SERVICE_STOPPED
$Chipcard::PCSC::SCARD_E_SHARING_VIOLATION
$Chipcard::PCSC::SCARD_E_SYSTEM_CANCELLED
$Chipcard::PCSC::SCARD_E_TIMEOUT
$Chipcard::PCSC::SCARD_E_UNKNOWN_CARD
$Chipcard::PCSC::SCARD_E_UNKNOWN_READER
$Chipcard::PCSC::SCARD_E_UNSUPPORTED_FEATURE
$Chipcard::PCSC::SCARD_W_REMOVED_CARD
$Chipcard::PCSC::SCARD_W_RESET_CARD
$Chipcard::PCSC::SCARD_W_SECURITY_VIOLATION
$Chipcard::PCSC::SCARD_W_UNPOWERED_CARD
$Chipcard::PCSC::SCARD_W_UNRESPONSIVE_CARD
$Chipcard::PCSC::SCARD_W_UNSUPPORTED_CARD
PCSClite users will also be able to use the following (PCSClite specific) codes:
$Chipcard::PCSC::SCARD_INSERTED
$Chipcard::PCSC::SCARD_REMOVED
$Chipcard::PCSC::SCARD_RESET
$Chipcard::PCSC::SCARD_SCOPE_GLOBAL
In addition, the wrapper defines:
$Chipcard::PCSC::SCARD_P_ALREADY_CONNECTED
$Chipcard::PCSC::SCARD_P_NOT_CONNECTED
SEE ALSO
pcscd(1) manpage has useful information about PC/SC lite. Chipcard::PCSC::Card manpage gives information about how to communicate with a reader and the smart card inside it.
COPYRIGHT
(C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2004, GNU GPL (C) Ludovic ROUSSEAU, 2005-2008, GNU GPL
AUTHORS / ACKNOWLEDGEMENT
Lionel VICTOR <lionel.victor
@unforgettable
.com>
<lionel.victor
@free
.fr>
Ludovic ROUSSEAU <ludovic.rousseau
@free
.fr>