Advanced Card ACR20 Bedienungsanleitung

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 1 of 34

CSR20

Application Programming Interface

Advanced Card Systems Ltd.

Room 302, 3/F., Shun Fat Industrial building,

17 Wang Hoi Road, Kowloon Bay,Kowloon, Hong Kong.

Tel: 852-2796 7873 Fax: 852-2796 1286

Website: www.acs.com.hk E-mail : [email protected]

ACR20 & ACR30 Smart Card Reader

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 2 of 34

TABLE OF CONTENT

1. INTRODUCTION ………………………………………………………………………. 4

2. ACSR20 ………………………………………………………………………………… 5

2.1 Overview ………………………………………………………………………… 5

2.2 Communication Speed …………………………………………………………. 5

2.3 ACSR20 API …………………………………………………………………….. 5

2.3.1 Interface Data Structure ……………………………………………… 5

2.3.1.1 AC_APDU ………………………………………………….. 6

2.3.1.2 AC_SESSION ……………………………………………... 6

2.3.1.3 AC_INFO …………………………………………………... 7

2.3.2 Interface Function Prototypes ……………………………………….. 8

2.3.2.1 AC_Open …………………………………………………... 8

2.3.2.2 AC_Close ………………………………………………….. 9

2.3.2.3 AC_StartSession ………………………………………….. 10

2.3.2.4 AC_EndSession …………………………………………… 11

2.3.2.5 AC_ExchangeAPDU ……………………………………… 12

2.3.2.6 AC_GetInfo ………………………………………………… 13

2.3.2.7 AC_SetOptions ……………………………………………. 14

2.3.3 ACI Commands ……………………………………………………….. 16

2.3.3.1 ACI_Read ………………………………………………….. 16

2.3.3.2 ACI_Write ………………………………………………….. 16

2.3.3.3 ACI_WriteCarry ………………………………………….… 17

2.3.3.4 ACI_WritePr………………………………………………… 17

2.3.3.5 ACI_Erase………………………………………………….. 17

2.3.3.6 ACI_ChangePIN…………………………………………… 18

2.3.3.7 ACI_Verify………………………………………………….. 18

2.3.3.8 ACI_Authenticate………………………………………….. 20

2.3.3.9 ACI_SetFuse……………………………………………….. 20

2.3.3.10 ACI_CardOptions………………………………………….. 21

2.3.3.11 ACI_ReadProtect………………………………………….. 21

2.3.3.12 ACI_SetProtect…………………………………………….. 23

2.3.3.13 ACI_ClearProtect……………………………………….…. 24

2.3.3.14 ACI_LockProtect…………………………………………… 24

2.3.3.15 ACI_WriteAll………………………………………………... 25

2.3.3.16 ACI_SetHE…………………………………………………. 25

2.3.3.17 ACI_BlowFuse……………………………………………... 26

2.3.3.18 ACI_EraseAll……………………………………………….. 26

2.3.3.19 ACI_Reactivate…………………………………………….. 27

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 3 of 34

2.4 Programmer Notes ………………………………………………………………. 28

2.4.1 The Xicor Card X76F041 ……………………………………………… 28

2.4.2 The Xicor Card X24645 and the IIC card ……………………………. 29

2.4.3 The AM221 (SLE4436, GAM226) type ………………………………. 30

2.4.4 Secret code verification ………………………………………………... 30

2.4.5 The Xicor Card X76F128 / X76F640 …………………………………. 31

2.4.6 The Xicor Card X76F100 ……………………………………………… 31

Appendix A : Table of error codes …………………………………………………………. 32

Appendix B : Supporting Memory Card Commands ……………………………………... 33

Appendix C : Table of card types compatibility …………………………………………… 34

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 4 of 34

1. INTRODUCTION

This manual describes the use of ACSR20 interface software to program the ACR20 &

ACR30 smart card readers. It is a set of library functions implemented for the application

programmers to operate the ACR20 & ACR30 smart card readers and the inserted smart

cards. It can be programmed using the popular development tools like Visual C/C++, Borland

C/C++, Visual Basic, Delphi, FoxPro, etc…

Depending on the reader model, ACR20 & ACR30 series of smart card readers can be

connected to the PC via the RS/232 interface or USB interface. The connecting interfaces of

different model of readers are summarized as follow:

Model Numbers Connecting interface

ACR20S, ACR20S-S, ACR30S, ACR30S-S

Serial RS/232

ACR20U,ACR20U-S, ACR30U, ACR20S-S

USB interface

Even though the hardware communication interface can be different, application programs

can still be using the same API (Application Programming Interface) for operating the smart

card readers. Actually, the purpose of using the ACSR20 library is to provide the programmer

with a simple and consistent interface over all possible hardware. It is the responsibility of the

ACSR20 library to handle the communication details, parameter conversions and error

handling. The architecture of the ACSR20 library can be visualized as the following diagram:

ACR10 / ACR20

Series of

Smart Card Reader

CardEasy

ACSR20

Windows

Application Program

Driver Program

Operating System

PCReader

RS-232 / USB

Figure 1.1

Layer

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 5 of 34

2. ACSR20

2.1 Overview

ACSR20 is a set of high level functions provided for the application software to use. It

provides a consistent application programming interface (ACSR20 API) for the application to

operate on the card reader and the corresponding inserted card. ACSR20 communicates with

the ACR10/ACR20 reader via the communication port facilities provided by the operating

system. ACSR20 is supposed to be platform independent provided that there is a minor

modification on the communication module of the ACSR20 to adapt to different operating

environment.

2.2 Communication Speed

The ACSR20 library controls the communication speed between the reader and the PC. For

those readers using the serial RS232 connection, the default communication baud rate

(factory setting) is 9600bps, no parity, eight bits and one stop bits. A higher speed of

115200bps can be achieved by using software command issuing from the host. If you are not

sure about the factory setting of your readers, you can always use the ACR_AUTODETECT

option in your AC_Open command for the driver to detect the communication speed

automatically. Please notice that the above communication speed setting apply only on those

readers using the RS232 connection. For the PS/2 type and the USB type of connection, the

speed is fixed at 9600bps and 1.5Mbps respectively.

2.3 ACSR20 API

The ACSR20 Application Programming Interface (API) defines a common way of accessing

the ACR10/ACR20 reader. Application programs invoke ACSR20 through the interface

functions and perform operations on the inserted card through the using of ACI commands.

The header file ACSR20.H is available for the program developer which contains all the

function prototypes and macros described below.

2.3.1 Interface Data Structure

The ACSR20 API makes use of several data structures to pass parameters between

application programs and the library driver. These data structures are defined in the header

file ACSR20.H and they are discussed below:

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 6 of 34

2.3.1.1 AC_APDU

typedef struct {

BYTE CLA;

BYTE INS;

BYTE P1;

BYTE P2;

INT16 Lc;

INT16 Le;

BYTE DataIn[256];

BYTE DataOut[256];

WORD16 Status;

} AC_APDU;

The AC_APDU data structure is used in the AC_ExchangeAPDU function for the passing of

commands and data information into the smart card. For memory card operation, please refer

to section 0for the definition of fields’ value. For MCU card (T=0,T=1) operation, these value

are specific to the smart card operating system. You must have the card reference manual

before you can perform any valid operations on the card. Please notice that Lc representing

the data length going into the card and Le representing the data length expecting from the

card.

Name Input/Output Description

CLA I Instruction Class

INS I Instruction Code

P1 I Parameter 1

P2 I Parameter 2

Lc I Length of command data (DataIn)

Le I/O Length of response data (DataOut)

DataIn I Command data buffer

DataOut O Response data buffer

Status O Execution status of the command

2.3.1.2 AC_SESSION

typedef struct {

BYTE CardType; // Card type selected

BYTE SCModule; // Selected security module.

//Use only when card type = AC_SCModule

BYTE ATRLen; // Length of the ATR

BYTE ATR[128]; // ATR string

BYTE HistLen; // Length of the Historical data

BYTE HistOffset; // Offset of the Historical data

// from the beginning of ATR

INT16 APDULenMax; // Max. APDU supported

} AC_SESSION;

The AC_SESSION data structure is used in the AC_StartSession function call for the retrieval

of ATR information from the smart card. Before calling AC_StartSession, the program needs

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 7 of 34

to specify the value of CardType. After calling the function, the ATR string can be found in

ATR field and the length is stored in ATRLen.

Name Input/Output Description

CardType I The card type selected for operation (refer to Appendix C for

CardType)

SCModule I The security module selected for operation. (The value is used only

when card type = AC_SCModule)

ATRLen O Length of the ATR string

ATR O Attention to reset (ATR) string

HistLen O Obsolete field – not used anymore

HistOffset O Obsolete field – not used anymore

APDULenMax O Obsolete field - not used anymore

2.3.1.3 AC_INFO

typedef struct {

INT16 nMaxC; // Maximum number of command data bytes

INT16 nMaxR; // Maximum number of data bytes that

// can be requested in a response

INT16 CType; // The card types supported by the reader

BYTE CStat; // The status of the card reader

BYTE CSel; // The current selection of card type

BYTE szRev[10]; // The 10 bytes firmware type and

// revision code

INT16 nLibVer; // Library version

Long lBaudRate; // Current Running Baud Rate

} AC_INFO;

The AC_INFO data structure is used in the AC_GetInfo function call for the retrieval of reader

related information. Their meaning are described as follow:

Name Input/Output Description

nMaxC O The maximum number of command data byte (DataIn) that can be accepted in

the ExchangeAPDU command

nMaxR O The maximum number of response data byte (DataOut) that will be appeared in

the ExchangeAPDU command

CType O The card types supported by the reader

(For details, please look at the ACR20 reference manual)

Cstat O The status of the card reader

Bit0 = card present (1) or absent (0)

Bit1 = card powered up (1) or powered down (0)

szRev[10] O The firmware revision code

nLibVer O Library version (e.g. 310 is equal to version 3.10)

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 8 of 34

2.3.2 Interface Function Prototypes

Generally, a program is required to call AC_Open first to obtain a handle. The handle is

required for subsequent calls to AC_StartSession, AC_ExchangeAPDU, AC_EndSession and

AC_Close. The inserted card can be powered up by using the AC_StartSession function and

card commands can be exchanged with the inserted card using the AC_ExchangeAPDU

function. Moreover, AC_SetOptions and AC_GetInfo are two commands that can be used to

set and read the various information of the reader.

2.3.2.1 AC_Open

This function opens a port and returns a valid reader handle for the application program.

Format:

INT16 AC_DECL AC_Open (INT16 ReaderType, INT16 ReaderPort);

Input Parameters:

The table below lists the parameters for this function (you can refer to ACSR20.H for the

corresponding value):

Parameters Definition / Values

ReaderType3Reader type and communication speed.

ACR10 = Target reader is ACR10 (9600bps)

ACR20 = Target reader is ACR20 (57600bps)

ACR20_57600 = Target reader is ACR20 (57600bps)

ACR20_19200 = Target reader is ACR20 (19200bps)

ACR20_115200 = Target reader is ACR20 (115200bps)

ACR20_9600 = Target reader is ACR20 (9600bps)

ACR_AUTODETECT1= Auto detect the target reader

ReaderPort The port that connected with the reader.

AC_COM1 = Standard communication port 1

AC_COM2 = Standard communication port 2

AC_COM3 = Standard communication port 3 (Valid only on the Win32 driver)

AC_COM4 = Standard communication port 4 (Valid only on the Win32 driver)

AC_USB = Using the USB communication port

AC_PCSC = Using the PCSC component to access the reader

Returns:

The return value is negative and contains the error code when the function encounters an

error during operation. Otherwise, it returns a valid reader handle. Please refer to appendix A

for the detailed description and meaning of the error codes.

Examples:

// open a port to a ACR10 reader connected to COM1

INT16 hReader;

hReader = AC_Open(ACR10,AC_COM1);

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 9 of 34

Remarks:

1. If the user select ACR_AUTODETECT to open a reader in the first time, the library will try to reset the reader

and wait for the response message from the reader. This may take some time (around 2-3 seconds) for the

library to complete this operation.

2. When an ACR20 is reset, the green LED will flash three times. There is no reset for an ACR10 reader.

3. When the application want to access the security module, it needs to open (use the AC_Open command) the

reader for the second time to get a different handler for the handling of the security module session.

4. The option of AC_USB is available only in the Windows 98 and Windows 2000 platform.

The option of AC_PCSC is available only in the platform with the Microsoft PCSC base components installed.

The driver will select the first available PCSC reader for operation. In order for the correct operation of the

reader, you need to make sure that the first available PCSC reader is a smart card reader from ACS.

2.3.2.2 AC_Close

This function closes a previously opened reader port.

Format:

INT16 AC_DECL AC_Close (INT16 hReader);

Input Parameters:

The table below lists the parameters for this function

Parameters Definition / Values

hReader A valid reader handle previously opened by AC_Open()

Returns :

The return value is zero if the function is successful. Otherwise, it returns a negative value

containing the error code. For the detailed meaning of the error code, please refer to

appendix A.

Examples :

// Close a previously opened port

INT16 RtnCode;

RtnCode = AC_Close(hReader);

Smart Card Reader Driver Program Reference Manual rev 1.1 Sept, 2003

Advanced Card Systems Ltd. Page 10 of 34

2.3.2.3 AC_StartSession

This function starts a session with a selected card type and updates the session structure with

the values returned by the card Answer-To-Reset (ATR). A session is started by a card reset

and it is ended by either another card reset, a power down of the card or the removal of a

card from the reader. Note that this function will power up the card and perform a card reset.

Format:

INT16 AC_DECL AC_StartSession (INT16 hReader, AC_SESSION FAR

*Session);

Input Parameters:

The table below listed the parameters for this function

Parameters Definition / Values

hReader A valid reader handle returned by AC_Open()

Session.CardType The selected card type for this session (please refer to Appendix C for card type

selection)

Session.SCModule The selected security module number

(Required only when card type =AC_SCModule)

Output Parameters:

The table below listed the parameters returned by this function

Parameters Definition / Values

Session.ATR Answer to Reset returned by the card

Session.ATRLen Length of the answer to reset

Session.HistLen Length of the historical data

Session.HistOffset Offset of the historical data

Session.APDULenMax Maximum length of APDU supported

Returns:

The return value is zero if the function is successful. Otherwise, it returns a negative value

containing the error code. For the detailed meaning of the error code, please refer to

appendix A.

Dieses Handbuch passt für folgende Modelle

Inhaltsverzeichnis

Andere Advanced Card Kartenleser Handbücher

Advanced Card

Advanced Card ACR35 Bedienungsanleitung

Advanced Card

Advanced Card ACR89U-A2 Bedienungsanleitung

Advanced Card

Advanced Card ACR100I Bedienungsanleitung

Advanced Card

Advanced Card ACR38U-I1 Bedienungsanleitung

Advanced Card

Advanced Card ACR88 Bedienungsanleitung

Advanced Card

Advanced Card ACR38 Bedienungsanleitung

Advanced Card

Advanced Card ACR128U Bedienungsanleitung

Advanced Card

Advanced Card ACR89U-A2 Bedienungsanleitung

Advanced Card

Advanced Card ACR39U-U1 Bedienungsanleitung

Advanced Card

Advanced Card ACR83 PINeasy Bedienungsanleitung

Advanced Card

Advanced Card ACR39x Bedienungsanleitung

Advanced Card

Advanced Card ACR122S Bedienungsanleitung

Beliebte Kartenleser Handbücher anderer Marken

Lindy

Lindy 43185 Bedienungsanleitung

Lindy

Lindy 43185 Bedienungsanleitung

ViziT

ViziT RD-4F Bedienungsanleitung

Jinmuyu Electronics

Jinmuyu Electronics MR811 Series Bedienungsanleitung

AVID ID

AVID ID AVID1043 Bedienungsanleitung

Conrad

Conrad PCMCIA Bedienungsanleitung

Rosslare

Rosslare DR-6255 Bedienungsanleitung

Lindy

Lindy 51541 Bedienungsanleitung

Diapro T?bbi Ürünler

Diapro T?bbi Ürünler Across System Bedienungsanleitung

Johnson Controls

Johnson Controls Kantech tyco ioSmart Bedienungsanleitung

ACS

ACS ACR122L Bedienungsanleitung

Secukey

Secukey S2-MF Bedienungsanleitung

Elecom

Elecom MR-SMC07 series Bedienungsanleitung

Alien

Alien ALR-9800 Bedienungsanleitung

ACS

ACS ACR310 Bedienungsanleitung

Datamars

Datamars R-IN1300 MID Bedienungsanleitung

Alarm Lock

Alarm Lock AL-PRE2 Bedienungsanleitung

xpr

xpr B100PROX-AH Benutzerhandbuch