Unitech MR350 MKII Quick start guide

MR350MKII
Data Collection Terminal
Smart card reader programming Manual
Unitech Electronics Co., Ltd.
April 1999

2
Introduction:
Why this manual
It is not easy for users to develop their application program according ISO-7816 standard, user
should know detail command format, computing cryptography .. etc. That is why Unitech
provide this manual and utility library to help user to develop application program by simple API.
This utility library also include functions for decryption and encryption. We hope it can speed up
programmer’s developing time.
Objective of this manual
This manual introduces MR350MKII’s system function call and function library, user can use
them to control our Smart Card reader to access GEMPLUS’s PCOS-EMV card. So, our function
library is compliant to MPCOS-EMV administration command, it includes decryption,
encryption and accessing , creating and verifying different file structure. If user is skillful for
Smart Card reader program, he can skip our function library and directly use MR350MKII’s
system function call to develop their application program. Currently, MR350MKII supports T=0
and T=1 protocol
Programmer requirement
Before you use this manual, we presume that you are good at or you have studied below 3 items
1. C programming
2. MR350MKII programming
3. MPCOS-EMV
Main topic of this manual
1. System architecture –This chapter helps user to know the relationship between application
program, function library , system function call and Smart Card.
2. System call –This chapter introduces MR350MKII’s system function call for access generic
Smart Card.
3. Function library –This chapter introduces detail of Smart Card function libraries including
argument, parameter and data structure for ISO7816 standard or MPCOS-EMV card.

3
Demo disk
All necessary files are included into demo disk, you can find it from sub-directory Smart Card of
DEMO disk. It includes
1. SAMPLE01.c –sample program for issuing new Smart Card
2. SAMPLE02.c –sample program for reading / writing Smart Card
3. Function library
3.1 GEMSmart Card.LIB –C source code
3.2 GEMSmart Card.OBJ –object file
3.3 Smart CardINCL.h –C include file.
3.4 MAKE.BAT –batch file for compile and link user’s application
Further information please refer toChapter 3.
Notice :
Currently, MR350MKII only support T=0 and T=1 protocol and the function
library only provide GEMPLUS MPCOS-EMV format. If you need other format,
please contact us for further support.

4
Table of contents :
Introduction:...........................................................................................................................................2
Table of contents : .................................................................................................................................4
Chapter 1. System architecture......................................................................................................6
1.1 System diagram :............................................................................................................................. 6
1.2 Relationship between Smart Card function Library and System call :................................................7
1.3 Developing flow for user application program.................................................................................. 8
Chapter 2. System function call (Firmware function call):............................................................9
3.1 Check Smart Card............................................................................................................................9
2.2 Power-on Smart Card..................................................................................................................... 10
2.3 Power off Smart Card.................................................................................................................... 11
2.4 Exchange message......................................................................................................................... 11
Chapter 3. Function library...........................................................................................................12
3.1 Files description of Smart Card function library ............................................................................. 12
3.2 How to build-up application program............................................................................................. 12
3.2 F_APD_REC.................................................................................................................................13
3.3 F_CHK_ICC .................................................................................................................................14
3.4 F_CLOSE_ICC ............................................................................................................................. 14
3.5 F_CRT_DF ................................................................................................................................... 15
3.6 F_CRT_EF.................................................................................................................................... 16
3.7 F_ERR_MSG................................................................................................................................ 17
3.8 F_EX_APDU ................................................................................................................................ 18
3.9 F_INI_ACC................................................................................................................................... 19
3.10F_INI_APDU................................................................................................................................ 19
3.11 F_LD_KEY................................................................................................................................... 20
3.12 F_LD_SC...................................................................................................................................... 21
3.13 F_LIB_VER.................................................................................................................................. 22
3.14 F_OPEN_ICC ............................................................................................................................... 23
3.15 F_RD_BIN.................................................................................................................................... 24
3.16 F_RD_REC................................................................................................................................... 25
3.17 F_SEL_FKEY............................................................................................................................... 26

5
3.18 F_SEL_ID..................................................................................................................................... 27
3.19 F_SET_FKEY............................................................................................................................... 28
3.20 F_SET_SC .................................................................................................................................... 29
3.21 F_UPD_BIN.................................................................................................................................. 30
3.22 F_UPD_REC.................................................................................................................................31
3.23 F_VERIFY.................................................................................................................................... 32
3.24 F_WR_BIN................................................................................................................................... 33

6
Chapter 1. System architecture
1.1 System diagram :
The following diagram shows the Smart Card transaction system structure.
MR350MKII’s Smart Card reader can support T=0 and T=1 protocol. Users can directly use this
system function call to develop their application. Actually, system function only provides
primary command to access and control Smart Card reader. User should know detail control
register and data structure level when they directly use system function call to write their
application program.
Although, there are variety of smart cards on the market to provide a design reference, Unitech
develops an Smart Card library to provide all MPCOS-EMV command set, so user can directly
use those function libraries to develop their application program without knowing detailed low
level control register and data structure. Some of command sets (in our Smart Card function
library) are following ISO 7816 standard, so they are not dedicated for GEMPLUS
MPCOS-EMV. So, users can also use part of this Smart Card library to develop their application
program for other format card. In chapter 3, we will mark every function library to tell user
whether it is standard command or dedicated for GEMPLUS.
Smart Card MR350 MKII
Application
program
Smart Card
Function
Library
MR350MKII
System call T=0 or T=1 Smart card
GEMPLUS
MPCOS-EMV

7
1.2 Relationship between Smart Card function Library and System function call
Below diagram show relationship between Smart Card function library and system function call.
The function call inside the black frame are only available for MPCOS-EMV card, other function
library follow ISO 7816 standard. In this diagram, F/W means MR350MKII system function call.
Check Smart
Card
Power on Smart
Card
Power off Smart
Card
Exchange APDU
(AH=3)
Check Smart
Card
Power on Smart
Card
Power off Smart
Card
Exchange APDU
(AH=3)
F_CHK_ICC F_OPEN_ICC
S_CHK_ICC S_OPEN_ICC
F_CLOSE_ICC
No
F_EX_APDU
S_EX_APDU
F_SEL_ID
F_RD_BIN
F_WR_BIN
F_UPD_BIN
S_SEL_ID
S_RD_BIN
S_WR_BIN
S_UPD_BIN
F/W
Smart Card Fnction Library

8
1.3 Developing flow for user application program
Below diagram is a flow chart for developing Smart Card application program.
According above diagram, user should follow this flow chart to develop their application program.
Step 1: There is a detector in Smart Card reader to check whether Smart Card is inserted into
reader. MR350MKII also provides function call to get its status.
Step 2: According ISO standard, Smart Card reader will not always supply power to VCC pin,
application program should execute a special function call to inform Smart Card reader to
provide power to Smart Card
Step 3: After Smart Card are inserted into reader and reader feeds VCC to this card, application can
access this card by system function call or function library.
Step 4: Before removing Smart Card from reader, application program should power off Smart
Card to avoid possibly damaging Smart Card when user inserts or removes it.
Step 5: This step is the same with step 1. Application program can use function call to know
whether Smart Card still stays in reader.
Check Smart Card is inserted ?
(AH=0)
Power on Smart Card
(AH=1)
Exchange message
(AH=3)
Power off Smart Card
(AH=2)
Check Smart Card is
removed ?
Vcc output to Smart Card
This step is necessary before taking Smart
Card out, or the Smart Card may be
damaged.

9
Chapter 2. System function call (Firmware function call):
Below 3 system function calls are implemented on the Firmware of MR350MKII. Those function
call only support short format and protocol are available for T=0 and T=1. All of the system
function calls are implemented on system interrupt vector 06H (INT 06H)
3.1 Check Smart Card
In Smart Card reader, there is a detector to check whether Smart Card is inserted. After that,
reader will check whether card is shorted. This action can avoid accepting bad card to protect
reader itself.
Entry Parameter :
INT 06H
AH = 0
Return value :
AL =0 NO CARD PRESENT
1Smart Card SHORT
2Smart Card EXIST
If AL = 2 AH = 0 Smart Card isn’t power-on
1 Smart Card is already power-on

10
2.2 Power-on Smart Card
This function informs Smart Card reader to supply power to VCC pin on Smart card and it also
needs to send pointer of ATR (Answer to reset) structure to get its status
Entry Parameter
INT 06H
AH = 1POWER ON Smart Card
ES:DI= Buffer of ATR structure
Output Value
AH = 0 Successfully power-on
If AH=0 CX = ATR length
1 Time-out ( 1 Sec ,RETRY=1 )
2 No card present
4 Data pin not stable
5Parity error
Below is ATR structure
typedef struct
{
int Smart CardType; ; Reserve for Future Use
int AtrReady; ; 0 = OK
; 1 = Timeout
; 2 = No card
; 4 = data not stable
; 5 = Parity error
int AtrLen; ; holds ATR length ,from TS to TCK
unsigned char AtrBuf[MaxATR]; ; holds ATR char, at most 32
; character ( refer to ISO-7816-3,6.1.4)
int HistLen; ; holds the number of history char, from T1 to
; TK
int HistOffset; ; History char start from Atr_buf[Hist_offset]
} S_OPEN_ICC;

11
2.3 Power off Smart Card
Entry parameter
INT 06H
AH = 2 ; POWER OFF Smart Card
2.4 Exchange message
This function is used to send or receive data between MR350MKII and Smart Card
Entry parameter
INT 06H
AH = 3 ;SEND COMMAND TO Smart Card
DS:SI= buffer ; pointer of exchange command buffer(output)
CW = length ; Length of message excahnge buffer
ES:DI=buffer ; pointer of return message (input)
Return value
AH = 0 ; SUCCESS
If AH=0 CX=length of return message
1; timeout and deactive Smart Card
2; No card present deactive Smart Card
3 ; EDC error
4 ; Data not stable
5 ; Parity check error
6 ; Other error & deactive Smart Card

12
Chapter 3. Function library
This chapter introduces whole function library by function name sequence. It includes function
description, input/output parameter and data structure. This C function library can be included into
user’s application program and please use LARGE MEMORY MODEL to compile it.
3.1 Files description of Smart Card function library
There are 4 files in our function library. It shows as below
Smart CardINCL.H : C Include file for function library
GEMSmart Card.LIB : Library file of Smart Card function library
GEMSmart Card.OBJ ; Object file of Smart Card function library
MAKE.BAT; Batch file to compile and link user’s program
3.2 How to build-up application program
If user’s application program is SAMPLE01.C, just follow below steps to compile and link the your
program.
Step 1 : Compile the main program with Large memory model
Cl /AL /c SAMPLE01.c
Step 2 : User can use GEMSmart Card.LIB or GEMSmart Card.OBJ to link the program
Step 2.1 Use GEMSmart Card.LIB as library file
link /stack:0x1000 sample01
[.exe] enter
[.map] enter
[.lib] GEMSmart Card enter
[.def] enter
Note : stack size should be more than 0x1000.
Step 2.2 : Use GEMSmart Card.OBJ
link sample01+GEMSmart Card /stack:0x1000;

13
3.2 F_APD_REC
This function writes data and initializes a record EF. When secure messaging is used, the function
dose not accept this command of length greater than the communication buffer size(64 bytes).
Compatible with ISO7816 or Gemplus command set
IS7816 if class = normal
Genplus if class = secure
Function call
void F_APD_REC( S_APD_REC* );
Data structure of S_APD_REC
typedef struct
{
int Class;
unsigned char ShortId;
int RecLen;
unsigned char RecData[MaxDATA];
int IdOk;
unsigned char Sw12[2];
unsigned char CRYin[3];
unsigned char CRYout[3];
} S_APD_REC;
Input parameter :
Class : 0 = NORMAL
: 1 = SECURE
ShortId : short identifier if implicit select,0 for direct select.
RecLen : The length of record to be update.
RecData[] : data
Output parameter : This function updates the following parameters.
IdOk : 0 = OK 1 = Timeout 2 = No card
; 3 = EDC error 5 = Parity error 7 = see SW1-SW2
Sw12[] : SW1-SW2
CRYin[] : CRYcks 2,1,0 only for secure message
CRYout[] : CRYcks 7,6,5 only for secure message

14
3.3 F_CHK_ICC
This function is used to check Smart Card current stage.
Compatible with ISO7816 or Gemplus command set
No
Function call
void F_CHK_ICC( S_CHK_ICC* );
Data structure of S_CHK_ICC
typedef struct
{
int ChkPower;
int ChkPresent;
} S_CHK_ICC;
Input parameter :
No
Output parameter :.
ChkPower : currently power stage
; 0 = OFF
; 1 = ON
ChkPresent ; 0 = No card present
; 1 = card short
; 2 = card exist
3.4 F_CLOSE_ICC
This function closes previously opened session and power off the card.
Compatible with ISO7816 or Gemplus command set
no
Function call
void F_CLOSE_ICC( void );

15
3.5 F_CRT_DF
This function creates a dedicated File. User should use function F_INI_ACC
to load Access Condition before creates DF/EF.
Compatible with ISO7816 or Gemplus command set
Gemplus
Function call
void F_CRT_DF( S_CRT_DF* );
Data structure of S_CRT_DF
typedef struct
{
int Class;
unsigned char FileId[2];
int Opt;
int NameLen;
unsigned char DFName[16];
int IdOk;
unsigned char Sw12[2];
unsigned char CRYin[3];
unsigned char CRYout[3];
} S_CRT_DF;
Input parameter :
Class : 0 = NORMAL
; 1 = SECURE
FileId[] : DF identifier
Opt : RFU
NameLen : 0--16
DFName[] : store DF name
Output parameter :
IdOk : 0 = OK 1 = Timeout 2 = No card
; 3 = EDC error 5 = Parity error 7 = see SW1-SW2
Sw12[] :SW1-SW2
CRYin[] :CRYcks 2,1,0 only for secure message
CRYout[] :CRYcks 7,6,5 only for secure message

16
3.6 F_CRT_EF
This function creates an Elementary File. User should use function F_INI_ACC
to load Access Condition before creates DF/EF.
Compatible with ISO7816 or Gemplus command set
Gemplus
Function call
void F_CRT_EF( S_CRT_EF* );
Data structure of S_CRT_EF
typedef struct
{
int Class;
unsigned char FileId[2];
int FDB;
int RecLen;
int BodyLen;
int IdOk;
unsigned char Sw12[2];
unsigned char CRYin[3];
unsigned char CRYout[3];
} S_CRT_EF;
Input parameter :
Class : 0 = NORMAL
; 1 = SECURE
FileId[] : EF identifier
FDB : File descrirtion byte
RecLen : record length (for fix length structure only) 0:other
BodyLen : 0x0000--0xFFFF
Output parameter : This function updates the following parameters.
IdOk : 0 = OK 1 = Timeout 2 = No card
; 3 = EDC error 5 = Parity error 7 = see SW1-SW2
Sw12[] :SW1-SW2
CRYin[] :CRYcks 2,1,0 only for secure message
CRYout[] :CRYcks 7,6,5 only for secure message

17
3.7 F_ERR_MSG
Convert Smart Card reader return code to text description
Compatible with ISO7816 or Gemplus command set
Parital
Function call
void F_ERR_MSG( unsigned char* p_sw ,unsigned char* msg);
Input parameter :
P_sw : point to status word.
Output parameter :
Msg : string buffer of text description

18
3.8 F_EX_APDU
This function call exchanges APDU command with Smart Card and returns the card’s response.
Compatible with ISO7816 or Gemplus command set
No
Function call
void F_EX_APDU( S_EX_APDU* );
Data structure of S_EX_APDU
typedef struct
{
int InLen;
unsigned char InApdu[MaxAPDU];
int OutLen;
unsigned char OutApdu[MaxAPDU]; // header+MAX 255 byte
int OutReady;
int SwOffset;
} S_EX_APDU;
Input parameter :
InLen : holds the number of APDU byte to send to Smart Card.
InApdu[] ; APDU command to send to Smart Card.
Output parameter : This function updates the following parameters.
OutReady : 0 = OK 1 = Timeout 2 = No card
; 3 = EDC error 5 = Parity error
OutLen :The number of response byte.
OutApdu[] :Response data from Smart Card.
SwOffset :Status word(SW1,SW2) start from Out_apdu[Sw_offset].

19
3.9 F_INI_ACC
This function initializes the Access Conditions registers, which is pre-requisite for creation of EF or
DF. Before useing function “F_CRT_EF” or “F_CRT_DF”. User should initializes Access
Conditions registers. Access Conditions registers will reset to 0 when function “F_OPEN_ICC” or
“F_SEL_ID” is executed.
Compatible with ISO7816 or Gemplus command set
Gemplus
Function call
void F_INI_ACC( S_INI_ACC* );
Data structure of S_INI_ACC
typedef struct
{
int AccNum;
int Validity;
int KeyLevel;
unsigned char KeyId;
int Sc1Level;
int Sc1Num;
int Sc2Level;
int Sc2Num;
} S_INI_ACC;
Input parameter :
AccNum : 1~3 for access condition 1--3
Validity : 0 = unrestricted access 1 = SC1 protect
; 2 = SC1 & SC2 protect 3 = access never allowed
KeyLevel : 0 = EFkey is in grobal level 1 = local level
KeyId :KEY file short id
Sc1Level :first secret code level 0:grobal 1:local
Sc1Num :first secret code number from 0--7
Sc2Level :second secret code level 0:grobal 1:local
Sc2Num :second secret code number from 0--7
3.10 F_INI_APDU
Initialize structure S_EX_APDU.
Compatible with ISO7816 or Gemplus command set
No
Function call
void F_INI_APDU( S_EX_APDU* new );

20
3.11 F_LD_KEY
This function loads/updates a triple DES key into a key file.
Compatible with ISO7816 or Gemplus command set
Gemplus
Function call:
void F_LD_KEY( S_LD_KEY* );
Data structure of S_LD_KEY
typedef struct
{
int Class;
int Mode;
unsigned char ShortId;
int KeyNum;
int KeyType;
int KeyVer;
unsigned char KeyValue[16];
int IdOk;
unsigned char Sw12[2];
} S_LD_KEY;
Input parameter :
Class : 0 = NORMAL 1 = SECURE
Mode : 0 = direct select 1 = implicit select
ShortId : short EF identifier, This is needed if Mode=1.
KeyNum : key number 0,2,4,6 only.
KeyType : 0 = ADM 1 = pay 2 = Log
; 3 = Authen 16 = sign
KeyVer :key version for AP
KeyValue[] :holds key data,[0]=K15,[1]=K14,[15]=K0
Output parameter : This function updates the following parameters.
IdOk : 0 = OK 1 = Timeout 2 = No card
; 3 = EDC error 5 = Parity error 7 = see SW1-SW2
Sw12[] :SW1-SW2