Gemalto Prox-DU User manual

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 1/129
Prox–DU & Prox–SU
Dual interface USB smart card reader
PC/SC Guide

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 2/129
All information herein is either public information or is the property of and owned solely by
Gemalto NV. and/or its subsidiaries who shall have and keep the sole right to file patent
applications or any other kind of intellectual property protection in connection with such
information.
Nothing herein shall be construed as implying or granting to you any rights, by license, grant
or otherwise, under any intellectual and/or industrial property rights of or concerning any of
Gemalto’s information.
This document can be used for informational, non-commercial, internal and personal use
only provided that:
• The copyright notice below, the confidentiality and proprietary legend and this full warning
notice appear in all copies.
• This document shall not be posted on any network computer or broadcast in any media
and no modification of any part of this document shall be made.
Use for any other purpose is expressly prohibited and may result in severe civil and criminal
liabilities.
The information contained in this document is provided “AS IS” without any warranty of any
kind. Unless otherwise expressly agreed in writing, Gemalto makes no warranty as to the
value or accuracy of information contained herein.
The document could include technical inaccuracies or typographical errors. Changes are
periodically added to the information herein. Furthermore, Gemalto reserves the right to
make any change or improvement in the specifications data, information, and the like
described herein, at any time.
Gemalto hereby disclaims all warranties and conditions with regard to the information
contained herein, including all implied warranties of merchantability, fitness for a particular
purpose, title and non-infringement. In no event shall Gemalto be liable, whether in contract,
tort or otherwise, for any indirect, special or consequential damages or any damages
whatsoever including but not limited to damages resulting from loss of use, data, profits,
revenues, or customers, arising out of or in connection with the use or performance of
information contained in this document.
Gemalto does not and shall not warrant that this product will be resistant to all possible
attacks and shall not incur, and disclaims, any liability in this respect. Even if each product is
compliant with current security standards in force on the date of their design, security
mechanisms' resistance necessarily evolves according to the state of the art in security and
notably under the emergence of new attacks. Under no circumstances, shall Gemalto be
held liable for any third party actions and in particular in case of any successful attack
against systems or equipment incorporating Gemalto products. Gemalto disclaims any
liability with respect to security for direct, indirect, incidental or consequential damages that
result from any use of its products. It is further stressed that independent testing and
verification by the person using the product is particularly encouraged, especially in any
application in which defective, incorrect or insecure functioning could result in damage to
persons or property, denial of service or loss of privacy.
© Copyright 2011 Gemalto N.V. All rights reserved. Gemalto and the Gemalto logo are
trademarks and service marks of Gemalto N.V. and/or its subsidiaries and are registered in
certain countries. All other trademarks and service marks, whether registered or not in
specific countries, are the property of their respective owners.
GEMALTO, B.P. 100, 13881 GEMENOS CEDEX, FRANCE.
Tel: [phone] Fax: [phone]
Printed in France.

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 3/129
REVISION HISTORY
Date Release Comments
November 2010 V0 Creation - Draft
February 2011 A First release

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 5/129
TABLE OF CONTENTS
INTRODUCTION..................................................................................................................... 9
OVERVIEW ........................................................................................................................... 11
USING PC/SC APPLICATION .............................................................................................. 12
PC/SC OVERVIEW .............................................................................................................. 12
Resource Manager ....................................................................................................... 13
Service Provider ........................................................................................................... 14
The smart card Service Provider.............................................................................. 15
The Cryptographic Service Provider ........................................................................ 15
WINSCARD API .................................................................................................................... 18
SCARDGETPROVIDERID FUNCTION...................................................................................... 18
SCARDLISTCARDS FUNCTION.............................................................................................. 20
SCARDLISTINTERFACES FUNCTION ...................................................................................... 22
SCARDLISTREADERGROUPS FUNCTION............................................................................... 24
SCARDLISTREADERS FUNCTION .......................................................................................... 26
SCARDADDREADERTOGROUP FUNCTION ............................................................................ 29
SCARDFORGETCARDTYPE FUNCTION.................................................................................. 30
SCARDFORGETREADER FUNCTION ...................................................................................... 31
SCARDFORGETREADERGROUP FUNCTION........................................................................... 32
SCARDINTRODUCECARDTYPE FUNCTION............................................................................. 33
SCARDINTRODUCEREADER FUNCTION ................................................................................. 35
SCARDINTRODUCEREADERGROUP FUNCTION...................................................................... 37
SCARDREMOVEREADERFROMGROUP FUNCTION ................................................................. 38
SCARDESTABLISHCONTEXT FUNCTION ................................................................................ 39
SCARDRELEASECONTEXT FUNCTION................................................................................... 41
SCARDFREEMEMORY FUNCTION ......................................................................................... 42
SCARDLOCATECARDS FUNCTION ........................................................................................ 43
SCARDGETSTATUSCHANGE FUNCTION................................................................................ 47
SCARDCANCEL FUNCTION................................................................................................... 49
SCARDCONNECT FUNCTION ................................................................................................ 50
SCARDRECONNECT FUNCTION ............................................................................................ 53
SCARDDISCONNECT FUNCTION ........................................................................................... 55
SCARDBEGINTRANSACTION FUNCTION ................................................................................ 56
SCARDENDTRANSACTION FUNCTION ................................................................................... 57
SCARDSTATUS FUNCTION ................................................................................................... 59
SCARDTRANSMIT FUNCTION................................................................................................ 62
SCARDCONTROL FUNCTION ................................................................................................ 66
SCARDGETATTRIB FUNCTION.............................................................................................. 68
SCARDSETATTRIB FUNCTION .............................................................................................. 72
SCARD RETURN VALUES ..................................................................................................... 74
LINUX WINSCARD API ........................................................................................................ 79
PROX–DU AND PROX–SU READER NAME....................................................................... 81
WINDOWS OPERATING SYSTEMS .......................................................................................... 81
LINUX AND MAC OS XOPERATING SYSTEMS......................................................................... 82
GEM_PC/SC SOFTWARE TOOL......................................................................................... 84
PLAYING WITH PC/SC ......................................................................................................... 85
KNOWN ISSUES AND LIMITATIONS WITH ALL THE OPERATING SYSTEMS ............... 89
KNOWN ISSUES AND LIMITATIONS WITH WINDOWS OPERATING SYSTEMS............ 89

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 6/129
KNOWN ISSUES AND LIMITATIONS WITH LINUX OPERATING SYSTEMS ................... 91
KNOWN ISSUES AND LIMITATIONS WITH MAC OPERATING SYSTEMS ...................... 91
INTERFACING WITH CONTACTLESS CARDS .................................................................. 93
DETECTING AN INSERTION.................................................................................................... 93
DETECTING A REMOVAL ....................................................................................................... 93
ATR FOR CONTACTLESS SMART CARDS ................................................................................ 94
INTERFACING WITH MIFARE®DESFIRE CARDS............................................................. 96
REQUESTING CONTACTLESS SMART CARD INFORMATION........................................ 97
INTERFACING WITH MIFARE®CARDS.............................................................................. 99
ATR FOR MIFARE®CARDS ............................................................................................... 100
GET DATA COMMAND......................................................................................................... 102
LOAD KEYS COMMAND ....................................................................................................... 103
GENERAL AUTHENTICATE COMMAND .................................................................................. 105
READ BINARY COMMAND.................................................................................................... 107
UPDATE BINARY COMMAND................................................................................................ 108
ERROR CODE LIST SUMMARY.............................................................................................. 109
INTERFACING WITH CONTACT CARDS.......................................................................... 111
DETECTING AN INSERTION ................................................................................................. 111
DETECTING A REMOVAL..................................................................................................... 111
ATR FOR CONTACT SMART CARDS .................................................................................... 111
Structures and content ............................................................................................... 113
Structure of the subsequent characters in the ATR ................................................... 113
Format character T0............................................................................................... 113
Interface characters TAi, TBi, TCi, TDi .................................................................. 114
Historical characters T1, T2, ... ,TK........................................................................ 114
Check character TCK............................................................................................. 115
Protocol type T ....................................................................................................... 115
Specifications of the global interface bytes............................................................ 115
TA1..................................................................................................................... 115
TB1 and TB2...................................................................................................... 116
TC1 .................................................................................................................... 116
TA2..................................................................................................................... 116
The first TA1 for T=15........................................................................................ 117
The first TB for T=15.......................................................................................... 117
MIFARE® CARDS MAPPING .............................................................................................. 118
MIFARE®1K MEMORY MAPPING ...................................................................................... 118
MIFARE®MINI MEMORY MAPPING .................................................................................... 119
MIFARE®4K MEMORY MAPPING ...................................................................................... 120
MIFARE®UL MEMORY MAPPING ...................................................................................... 122
Serial Number Area .................................................................................................... 122
Lock Bytes Area.......................................................................................................... 123
OTP Bytes Area.......................................................................................................... 123
Data Bytes Area.......................................................................................................... 123
MIFARE®UL Read/Write Operation........................................................................... 123
MIFARE®MEMORY ORGANIZATION ................................................................................... 124
Sector Trailer .............................................................................................................. 124
Authentication Keys................................................................................................ 124
Access Bits............................................................................................................. 125
Data Block Access Conditions ............................................................................... 125
Sector Trailer Access Conditions ........................................................................... 127

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 7/129
FOR MORE INFORMATION............................................................................................... 129
STANDARDS AND SPECIFICATIONS...................................................................................... 129
TABLE LIST
Table 1 – Dual interface USB smart card reader/writer models.............................................. 9
Table 2 – Smart Card Database Query Functions................................................................ 16
Table 3 – Smart Card Database Management Functions..................................................... 16
Table 4 – Resource Manager Context Functions ................................................................. 16
Table 5 – Resource Manager Support Function ................................................................... 16
Table 6 – Smart Card Tracking Functions ............................................................................ 17
Table 7 – Smart Card and Reader Access Functions........................................................... 17
Table 8 – Direct Card Access Functions............................................................................... 17
Table 9 – SCard return values .............................................................................................. 78
Table 10 – Linux WinSCard Functions.................................................................................. 80
Table 10 – Known issues and limitations (Windows OS)...................................................... 90
Table 11 – Known issues and limitations (Linux OS)............................................................ 91
Table 12 – PCSC-Lite known issues and limitations (Mac OS X)......................................... 92
Table 13 – ATR for contactless Smart cards ........................................................................ 94
Table 14 – ATR for MIFARE® cards .................................................................................... 100
Table 15 – SS Byte for Standard ........................................................................................ 101
Table 16 – NN Bytes for Card Name .................................................................................. 101
Table 17 – Memory card error codes .................................................................................. 110
Table 18 – ATR for contact smart cards ............................................................................. 113
Table 19 – Clock rate conversion factor F .......................................................................... 115
Table 20 – Bit rate adjustment factor D............................................................................... 116
Table 21 – clock stop indicator X ........................................................................................ 117
Table 22 – class indicator Y ................................................................................................ 117
Table 23 – Memory Sectors of MIFARE® 1K....................................................................... 118
Table 24 – Memory Sectors of MIFARE® Mini .................................................................... 119
Table 25 – Memory Sectors of MIFARE® 4K....................................................................... 121
Table 26 – Memory mapping of MIFARE®UL .................................................................... 122
Table 27 – Access to Data Blocks ...................................................................................... 127
Table 28 – Access to Sector Trailer .................................................................................... 128
FIGURE LIST
Figure 1 – PC/SC Architecture.............................................................................................. 13
Figure 2 – Prox–DU PC/SC name (Windows) ...................................................................... 81
Figure 3 – Prox–SU PC/SC name (Windows)....................................................................... 81
Figure 4 – Prox–DU and Prox–SU PC/SC names (Windows) .............................................. 81
Figure 5 – Two Prox–DU PC/SC names (Windows)............................................................. 81
Figure 6 – Prox–DU PC/SC name (Linux) ............................................................................ 82
Figure 7 – Prox–SU PC/SC name (Linux)............................................................................. 82
Figure 8 – Prox–DU and Prox–SU PC/SC names (Linux) .................................................... 82
Figure 9 – Two Prox–DU PC/SC names (Linux)................................................................... 82
Figure 10 – Gem_PCSC window .......................................................................................... 84
Figure 11 – Gem_PCSC window at start up ......................................................................... 85
Figure 12 – Gem_PCSC window after “SCardEstablishContext” ......................................... 85
Figure 13 – Gem_PCSC window after “SCardConnect”....................................................... 86
Figure 14 – Gem_PCSC window after “SCardTransmit” the Authentication command ....... 86
Figure 15 – Gem_PCSC window after “SCardTransmit” the Read command...................... 87

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 8/129
Figure 16 – Gem_PCSC window after “SCardDisconnect” .................................................. 88
Figure 17 – Gem_PCSC window after “SCardReleaseContext”........................................... 88
Figure 18 – Information provided by T0 .............................................................................. 114
Figure 19 – Information provided by TDi............................................................................. 114

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 9/129
Introduction
This guide provides information on the use of the Prox–DU and the Prox–SU dual interface
(contactless and contact) USB smart card reader/writer in the PC/SC environment.
This document is applicable to following reference, revision C and later:
Model Reference Comments
Prox–DU HWP118184
Dual interface USB smart card reader
Contact & contactless
Prox–SU HWP118185
Contactless interface USB smart card reader
With optional SIM/SAM slot
Prox–DU
with stand HWP118830 Prox–DU with a stand for vertical use
Prox–SU
with stand HWP118831 Prox–SU with a stand for vertical use
Table 1 – Dual interface USB smart card reader/writer models
For information on installation, please refer to the “Installation Guide” document.
For information on detailed operation about the smart card reader/writer, please refer to the
“Reference Manual” document.
For information on how to install the smart card reader/writer in a computer, please refer to
the “Computer Installation Guide” document.
Who Should Read This Book
This reference manual is designed for developers of PC/SC smart card application.
Conventions
Bit Numbering
A byte consists of 8 bits, b7 to b0, where b7 is the most significant bit and b0 is the least
significant bit.
One byte b7 b6 b5 b4 b3 b2 b1 b0
Byte Numbering
A string of n bytes consists of n number of concatenated bytes: Bn…B3…B0.
Bn is the most significant byte and B0 is the least significant byte:
A string of
n bytes Bn Bn-1 - - - B2 B1 B0
Contact Our Hotline
If you do not find the information you need in this document, or if you find errors, contact the
Gemalto hotline at http://support.gemalto.com/.

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 10/129
Please note the document reference number, your job function, and the name of your
company. (You will find the document reference number at the bottom of the document.)

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 11/129
Overview
PC/SC (short for “Personal Computer/Smart Card”) is a specification for smart-card
integration into computing environments.
For detailled information about PC/SC specification, please refer to the PC/SC workgroup
website: http://www.pcscworkgroup.com
Microsoft has implemented PC/SC in Microsoft Windows operating systems:
•The Winscard Smart Card API functions available in Microsoft Windows operating
systems are defined in the following website: http://msdn.microsoft.com
A free implementation of PC/SC, PC/SC Lite, is available for Linux and other unixes.
A forked version comes bundled with Mac OS X.
•The Winscard Smart Card API functions available in Linux or MAC OS X operating
systems are defined in the following website: http://pcsclite.alioth.debian.org
This document will provide detailed information about the PC/SC Winscard API functions
and will give some implementation examples.
The Prox–DU and the Prox–SU devices were designed to be fully compliant with the latest
PC/SC V2.0 specification.

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 12/129
Using PC/SC application
PC/SC Overview
The PC/SC specification describes the minimum functionality required of smart cards, smart
card readers, and PCs to allow interoperability among compliant elements as provided by a
variety of vendors.
The specification as a whole seeks to achieve the following objectives:
•Maintain consistency with existing smart card-related and PC-related standards
while expanding upon them where necessary and practical.
•Enable interoperability among components running on various platforms (platform
neutral).
•Enable applications to take advantage of products and components from multiple
manufacturers (vendor neutral).
•Enable the use of advances in technology without rewriting application-level
software (application neutral).
•Facilitate the development of standards for application-level interfaces to smart card
services in order to enhance the fielding of a broad range of smart card-based
applications in the PC environment.
•Support an environment that encourages the widest possible use of smart cards as
an adjunct to the PC environment.
The interoperability specification for smart cards and personal computer systems is
composed of nine parts. These are intended to apply only to devices and software intended
to operate as a part of an overall system that includes a personal computer.
These documents include:
•Part 1: Introduction and architecture overview
•Part 2: Interface requirements for compatible smart cards and interface devices
•Part 3: Requirements for PC-connected interface devices
•Part 4: Interface devices design considerations and reference design information.
This part is here as an example reference only.
•Part 5: Smart card resource manager definition
•Part 6: Smart card service provider interface definition
•Part 7: Application domain/developer design considerations
•Part 8: Recommendation for implementation of security and privacy smart card
devices
•Part 9: Interface devices with extended capabilities
The PC/SC Winscard API functions detailed hereafter are related to the Part 5 : Smart card
resource manager definition.

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 13/129
The next figure shows the PC/SC architecture:
Figure 1 – PC/SC Architecture
The software design considerations presented in the PC/SC specification address the
development of applications built on the architecture presented in the figure below.
This paragraph describes the way smart card-aware applications can use the functionality
provided by the smart card. By using the smart card resource manager and the service
provider layers, an application can use smart card functionality with some level of
independence from a specific reader, or to some extent, from a specific smart card.
Resource Manager
The resource manager is a key component of the PC/SC architecture. It is responsible for
managing the other smart card-relevant resources within the system and for supporting
controlled access to smart card readers and, through them, individual smart cards. The
resource manager is assumed to be a system-level component of the architecture. It must
be present and will most likely be provided by the operating system vendor. There should be
only a single resource manager within a given system.
The resource manager solves three basic problems in managing access to multiple readers
and smart cards.
First, it is responsible for identification and tracking of resources. This includes:
•Tracking installed readers and making this information accessible to other
applications.
•Tracking known smart card types, along with their associated service providers and
supported Interfaces, and making this information accessible to other applications.
•Tracking smart card insertion and removal events to maintain accurate information
on available smart cards within the readers.
Smart Card
Smart Card Reader
Smart Card Resource Manager
Smart Card - Aware Applications
Smart Card Reader Handler
Service Provider

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 14/129
Second, it is responsible for controlling the allocation of reader resources (and hence
access to smart cards) across multiple applications. It does this by providing mechanisms
for attaching to specific readers in shared or exclusive modes of operations.
Finally, it supports transaction primitives on access to services available within a given
smart card. This is extremely important because current smart cards are single-threaded
devices that often require execution of multiple commands to complete a single function.
Transactions allow multiple commands to be executed without interruption, ensuring that
intermediate state information is not corrupted.
Service Provider
The service provider is optional and is not described in this document because it is smart
card dependant. However some information is given in the next paragraph.
The service provider is the mechanism through which a smart card-specific set of
functionalities (in the form of an API) is made accessible to smart card-aware application
software. For every smart card, there will be at least one service provider; it is through this
service provider that an application can access data or services on that specific smart card.
The following three classes of services are widely implemented within existing smart cards:
•File services
•Authentication Services
•Cryptographic Services
These services, when present, have a high degree of functionality in common across smart
cards. Consequently, it is beneficial to standardize interfaces to these services so that
application development and maintenance are simpler. This specification defines such
interfaces as well as a standard interface for controlling basic access to a smart card.
Additional smart card services tend to reflect the needs of specific application domains
(EMV, GSM, and so on). It is believed most appropriate for groups within specific industries
to standardize interfaces in such areas. This architecture fully supports the addition of such
interfaces to the core set identified above.
The definition of the API’s exposed by a specific service provider generally comes from a
third-party workgroup (EMV, GSM, PC/SC, etc.). The service provider, by definition, has an
intimate knowledge of the smart card to which it provides access. The implementation of
these API’s might be expected to come from a variety of sources, including (but not limited
to) the following:
•The smart card supplier who wants to enable smart card use within the PC
environment. Providing a service provider makes accessing the smart card an
application software development effort that can be pursued by application
developers with no specific expertise in smart card technology (either smart cards
or readers).
•The smart card issuer, who might layer a “personalized” service provider on top of
the service provider provided by its smart card supplier.
•A smart card-Aware Application supplier who wishes to define the level of
functionality required of a smart card to adequately support the application. In
defining the API, the application supplier enables one or more smart card suppliers
to provide a smart card and the service provider that implements the API defined by
the application supplier.
•One or more parties interested in a specific domain, who wish to enable the
development of both applications and smart cards to support those applications
within a domain of interest.

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 15/129
The smart card Service Provider
The smart card service provider is one of two possible sub-components of the service
provider. It is responsible for exposing high-level interfaces to non-cryptographic services.
This exposure is expected to include common interfaces, defined in this specification, for
managing connections to a specific smart card, as well as access to file and authentication
services. In addition, the smart card service provider may implement interfaces that the
vendor defines for features specific to the application domain.
All smart card service providers shall implement the interface for managing connections to a
smart card as defined herein (see Section 3). This interface provides mechanisms for
connecting and disconnecting to a smart card.
In addition, to be compliant with this specification, smart card service providers that expose
file access and authentication services shall do so using the interfaces defined herein (see
Section 3.4). These interfaces encapsulate functionality defined by ISO 7816-4, along with
natural extensions for functionality such as file creation and deletion.
The file access interface defines mechanisms for the following tasks:
•Locating files by name
•Creating or opening files
•Reading and writing file contents
•Closing a file
•Deleting files
•Managing file attributes
The authentication interface defines mechanisms for the following tasks:
•Cardholder verification
•smart card authentication
•Application authentication to the smart card
The Cryptographic Service Provider
The cryptographic service provider is a sub-component of the service provider. In contrast to
the smart card service provider, the cryptographic service provider isolates cryptographic
services because existing regulations imposed by various governments affect import and
export. The cryptographic service provider allows applications to make use of cryptographic
services in a manner that compartmentalizes the sensitive elements of cryptographic
support into a well-defined and independently installable software package.
The cryptographic service provider encapsulates access to cryptographic functionality
provided by a specific smart card through high level programming interfaces. Its purpose is
to expose available cryptographic functions to applications running on a PC. All other
functionality should be implemented in the smart card service provider.
Interfaces are defined in this specification for the following general-purpose cryptographic
services:
•Key generation
•Key management
•Digital signatures
•Hashing (or message digests)
•Bulk encryption services
•Key import and export

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 16/129
The PC/SC Winscard API functions are listed the following tables:
Table 2 – Smart Card Database Query Functions
Smart Card Database Management Functions: Manage the smart card database
SCardAddReaderToGroup Add a reader to a reader group
SCardForgetCardType Remove a smart card from the system
SCardForgetReader Remove a reader from the system
SCardForgetReaderGroup Remove a reader group from the system
SCardIntroduceCardType Introduce a new card to the system
SCardIntroduceReader Introduce a new reader to the system
SCardIntroduceReaderGroup Introduce a new reader group to the system
SCardRemoveReaderFromGroup Remove a reader from a reader group
Table 3 – Smart Card Database Management Functions
Resource Manager Context Functions: Manage the context of the resource manager's
database operations
SCardEstablishContext Establishes a context for accessing the smart card
database
SCardReleaseContext Closes an established context
Table 4 – Resource Manager Context Functions
Resource Manager Support Function: Release allocated memory
SCardFreeMemory Release memory returned through the use of
SCARD_AUTOALLOCATE
Table 5 – Resource Manager Support Function
Smart Card Tracking Functions: Track smart cards within readers
SCardLocateCards Search for a card whose ATR string matches a
supplied card name
Smart Card Database Query Functions: Query the smart card database
SCardGetProviderId Retrieve the identifier (GUID) of the primary service
provider for the given card
SCardListCards Retrieve a list of cards previously introduced to the
system by a specific user
SCardListInterfaces Retrieve the identifiers (GUIDs) of the interfaces
supplied by a given card
SCardListReaderGroups Retrieve a list of reader groups that have previously
been introduced to the system
SCardListReaders Retrieve the list of readers within a set of named
reader groups

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 17/129
SCardGetStatusChange Block execution until the current availability of cards
changes
SCardCancel Terminate outstanding actions
Table 6 – Smart Card Tracking Functions
Smart Card and Reader Access Functions: Connect to and communicate with a smart
card, including transferring data using T=0, T=1, and raw protocols
SCardConnect Connect to a card
SCardReconnect Reestablish a connection
SCardDisconnect Terminate a connection
SCardBeginTransaction Start a transaction, blocking other applications from
accessing a card
SCardEndTransaction End a transaction, allowing other applications to
access a card
SCardStatus Provide the current status of the reader
SCardTransmit Requests service and receives data back from a
card using T=0, T=1, and raw protocols
Table 7 – Smart Card and Reader Access Functions
Direct Card Access Functions: Communicate with cards that may not conform to the ISO
7816 specifications
SCardControl Provide direct control of the reader
SCardGetAttrib Get reader attributes
SCardSetAttrib Set reader attribute
Table 8 – Direct Card Access Functions
The next paragraphs give more information about these commands (extracts from the
MSDN website: http://msdn.microsoft.com)
Most of the functions are defined in the “Part 5: Smart card resource manager definition” of
the PC/SC specification.

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 18/129
WinScard API
The next paragraph contains information retrieved from the http://msdn.microsoft.com web
site.
SCardGetProviderId Function
The SCardGetProviderId function returns the identifier (GUID) of the primary service
provider for a given card.
The caller supplies the name of a smart card (previously introduced to the system) and
receives the registered identifier of the primary service provider GUID, if one exists.
Syntax:
LONG WINAPI SCardGetProviderId(
__in SCARDCONTEXT hContext,
__in LPCTSTR szCard,
__out LPGUID pguidProviderId
);
Parameters:
hContext [in]
Handle that identifies the resource manager context for the query. The resource
manager context can be set by a previous call to SCardEstablishContext. This
parameter cannot be NULL.
szCard [in]
Name of the card defined to the system.
pguidProviderId [out]
Identifier (GUID) of the primary service provider. This provider may be activated
using COM, and will supply access to other services in the card.
Return Value:
This function returns different values depending on whether it succeeds or fails:
Success: SCARD_S_SUCCESS.
Failure: An error code. For more information, see Smart Card Return Values.
Remarks:
The SCardGetProviderId function is a database query function. For more information on
other database query functions, see Smart Card Database Query Functions.
Examples:
The following example shows how to get the provider ID for the specified card. The example
assumes that hContext is a valid handle obtained from a previous call to the
SCardEstablishContext function and that "MyCardName" was introduced by a previous call
to the SCardIntroduceCardType function.
GUID guidProv;
LONG lReturn;
lReturn = SCardGetProviderId(hContext,

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 19/129
L"MyCardName",
&guidProv);
if ( SCARD_S_SUCCESS != lReturn )
printf("Failed SCardGetProviderId - %x\n", lReturn);
else
{
// Use the provider GUID as needed.
// ...
}

PC/SC Guide
Prox–DU & Prox–SU
www.gemalto.com
DOC119811A Public Use Page 20/129
SCardListCards Function
The SCardListCards function searches the smart card database and provides a list of
named cards previously introduced to the system by the user.
The caller specifies an ATR string, a set of interface identifiers (GUIDs), or both. If both an
ATR string and an identifier array are supplied, the cards returned will match the ATR string
supplied and support the interfaces specified.
Syntax:
LONG WINAPI SCardListCards(
__in SCARDCONTEXT hContext,
__in_opt LPCBYTE pbAtr,
__in LPCGUID rgguidInterfaces,
__in DWORD cguidInterfaceCount,
__out LPTSTR mszCards,
__inout LPDWORD pcchCards
);
Parameters:
hContext [in]
Handle that identifies the resource manager context for the query. The resource
manager context can be set by a previous call to SCardEstablishContext.
pbAtr [in, optional]
Address of an ATR string to compare to known cards, or NULL if no ATR matching
is to be performed.
rgguidInterfaces [in]
Array of identifiers (GUIDs), or NULL if no interface matching is to be performed.
When an array is supplied, a card name will be returned only if all the specified
identifiers are supported by the card.
cguidInterfaceCount [in]
Number of entries in the rgguidInterfaces array. If rgguidInterfaces is NULL, then
this value is ignored.
mszCards [out]
Multi-string that lists the smart cards found. If this value is NULL, SCardListCards
ignores the buffer length supplied in pcchCards, returning the length of the buffer
that would have been returned if this parameter had not been NULL to pcchCards
and a success code.
pcchCards [in, out]
Length of the mszCards buffer in characters. Receives the actual length of the
multi-string structure, including all trailing null characters. If the buffer length is
specified as SCARD_AUTOALLOCATE, then mszCards is converted to a pointer to
a byte pointer, and receives the address of a block of memory containing the multi-
string structure. This block of memory must be deallocated with SCardFreeMemory.
Return Value:
This function returns different values depending on whether it succeeds or fails: