--- name: "PCSC" section: "3pm" platform: "linux" package: "libpcsc-perl" version: "1.1.1-2" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/PCSC" --- # PCSC(3pm) Smarcard reader interface library ## NAME PCSC - Smarcard reader interface library ## SYNOPSIS ``` my $hContext = new PCSC(); ``` ``` @ReadersList = $hContext->ListReaders (); ``` ``` $hContext->SetTimeout($timeout); ``` ``` $apdu = PCSC::array_to_ascii(@apdu); ``` ``` @apdu = PCSC::ascii_to_array($apdu); ``` ``` $hContext = undef; ``` ## DESCRIPTION The PCSC module implements the PCSC class. Objects of this class are used to communicate with the PCSC-lite daemon (see *[pcscd(1)](/pcscd/1.md)* for more information). PC/SC represents an abstraction layer to smartcard 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 PCSC::Card objects. Please read 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 PCSC($scope, $remote\_host);** - • `$scope` is the scope of the connection to the PC/SC daemon. It can be any of the following: ``` $PCSC::SCARD_SCOPE_USER (not used by PCSClite); $PCSC::SCARD_SCOPE_TERMINAL (not used by PCSClite); $PCSC::SCARD_SCOPE_SYSTEM Services on the local machine; $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 `$PCSC::SCARD_SCOPE_GLOBAL`. A null value means *localhost*. - • **$hContext = new PCSC($scope);** This method is equivalent to: ``` $hContext = new PCSC($scope, 0); ``` - • **$hContext = new** ***PCSC()*****;** This method is equivalent to: ``` $hContext = new PCSC($PCSC::SCARD_SCOPE_SYSTEM, 0); ``` ## CONSTRUCTION FAILURE PCSC constructors return an `"undef"` value when the object can not be created. `$PCSC::errno` can be used to get more information about the error. (See section "ERROR HANDLING" below for more information) ## 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 ommited, `$group` defaults to a null value meaning "all groups". Please note that as of this writing, `$group` can safely be ommited as it is not used by PCSClite. The return value upon succesful completion is an array of strings: one string by available reader. If an error occured, the undef value is returned and `$PCSC::errno` should be used to get more informations about the error. (See section "ERROR HANDLING" below for more information). The following example describes the use of ListReaders: ``` $hContext = new PCSC(); die ("Can't create the PCSC object: $PCSC::errno\n") unless (defined $hContext); ``` ``` @ReadersList = $hContext->ListReaders (); die ("Can't get readers' list: $PCSC::errno\n") unless (defined($ReadersList[0])); ``` ``` $, = "\n "; print @ReadersList . "\n"; ``` - • **$apdu\_ref = PCSC::ascii\_to\_array($apdu);** The method PCSC::Card::Transmit uses references to arrays as in and out parameters. The 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 = PCSC::ascii_to_array("00 A4 01 00 02 01 00"); ``` - • **$apdu = PCSC::array\_to\_ascii($apdu\_ref);** This method is used to convert the result of a PCSC::Card::Transmit into ASCII format. Example: ``` $RecvData = $hCard->Transmit($SendData); print PCSC::array_to_ascii($RecvData); ``` - • **$hContext-\>SetTimeout( $timeout );** This method sets the working time that RPC uses when waiting for a server. It returns true upon successful exacution or false otherwise. `$timeout` contains the new timeout value in seconds. - • **$hContext-\>*****SetTimeout()*****;** This function is equivalent to: ``` $hContext->SetTimeout(5); ``` ## ERROR HANDLING All functions from PCSC objects save the return value in a global variable called `$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 PCSC(); die ("Can't create the PCSC object: $PCSC::errno\n") unless (defined $hContext); ``` In case the last call was successful, `$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: ``` $PCSC::SCARD_S_SUCCESS $PCSC::SCARD_E_CANCELLED $PCSC::SCARD_E_CANT_DISPOSE $PCSC::SCARD_E_INSUFFICIENT_BUFFER $PCSC::SCARD_E_INVALID_ATR $PCSC::SCARD_E_INVALID_HANDLE $PCSC::SCARD_E_INVALID_PARAMETER $PCSC::SCARD_E_INVALID_TARGET $PCSC::SCARD_E_INVALID_VALUE $PCSC::SCARD_E_NO_MEMORY $PCSC::SCARD_E_UNKNOWN_READER $PCSC::SCARD_E_TIMEOUT $PCSC::SCARD_E_SHARING_VIOLATION $PCSC::SCARD_E_NO_SMARTCARD $PCSC::SCARD_E_UNKNOWN_CARD $PCSC::SCARD_E_PROTO_MISMATCH $PCSC::SCARD_E_NOT_READY $PCSC::SCARD_E_SYSTEM_CANCELLED $PCSC::SCARD_E_NOT_TRANSACTED $PCSC::SCARD_E_READER_UNAVAILABLE $PCSC::SCARD_E_PCI_TOO_SMALL $PCSC::SCARD_E_READER_UNSUPPORTED $PCSC::SCARD_E_DUPLICATE_READER $PCSC::SCARD_E_CARD_UNSUPPORTED $PCSC::SCARD_E_NO_SERVICE $PCSC::SCARD_E_SERVICE_STOPPED ``` ``` $PCSC::SCARD_W_UNSUPPORTED_CARD $PCSC::SCARD_W_UNRESPONSIVE_CARD $PCSC::SCARD_W_UNPOWERED_CARD $PCSC::SCARD_W_RESET_CARD $PCSC::SCARD_W_REMOVED_CARD $PCSC::SCARD_W_INSERTED_CARD ``` PCSClite users will also be able to use the following (PCSClite specific) codes: ``` $PCSC::SCARD_E_UNSUPPORTED_FEATURE $PCSC::SCARD_W_INSERTED_CARD $PCSC::SCARD_SCOPE_GLOBAL $PCSC::SCARD_RESET $PCSC::SCARD_INSERTED $PCSC::SCARD_REMOVED ``` In addition, the wrapper defines: ``` $PCSC::SCARD_P_ALREADY_CONNECTED $PCSC::SCARD_P_NOT_CONNECTED ``` ## SEE ALSO *[pcscd(1)](/pcscd/1.md)* manpage has useful informations about PC/SC lite. PCSC::Card manpage gives informations about how to communicate with a reader and the smart card inside it. ## COPYRIGHT (C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2002 ## AUTHORS / ACKNOWLEDGEMENT ``` Lionel VICTOR ``` ``` Ludovic ROUSSEAU ```