Mx800 Series
Programmers Guide
Part Number 23753, Revision A
Mx800 Series Programmers Guide
© 2006 VeriFone, Inc.
All rights reserved. No part of the contents of this document may be reproduced or transmitted in any form without the written
permission of VeriFone, Inc.
The information contained in this document is subject to change without notice. Although VeriFone has attempted to ensure the
accuracy of the contents of this document, this document may include errors or omissions. The examples and sample programs are
for illustration only and may not be suited for your purpose. You should verify the applicability of any example or sample program
before placing the software into productive use. This document, including without limitation the examples and software programs, is
supplied “As-Is.”
VeriFone, the VeriFone logo, Omni, VeriCentre, Verix, and ZonTalk are registered trademarks of VeriFone. Other brand names or
trademarks associated with VeriFone’s products and services are trademarks of VeriFone, Inc.
All other brand names and trademarks appearing in this manual are the property of their respective holders.
Comments? Please e-mail all comments on this document to your local VeriFone Support Team.
VeriFone, Inc.
2099 Gateway Place, Suite 600
San Jose, CA, 95110 USA
www.verifone.com
Part Number 23753, Revision A
CONTENTS
CHAPTER 1
Introduction Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Modifications to this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Acronyms, Abbreviations, and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conventions Used in this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recommended LINUX Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
11
12
12
CHAPTER 2
Overview of Product Operating System and Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Deliverables
C Compiler and Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
CHAPTER 3
File Systems File Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Environment/Configuration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Format Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getEnvFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putEnvFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Configuration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getSysctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putSysctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syslog Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Downloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Downloaded Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Authentication and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building ipkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing ipkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
15
19
20
21
24
25
26
26
26
27
28
28
29
31
CHAPTER 4
Device Drivers Device Drivers for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . 33
Magnetic Stripe Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrMagneticCardPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrRaw. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrStructured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrEnableLicenseDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrDisableLicenseDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
msrClose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal PIN Pad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
int ippOpen(void). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
int ippClose(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
int ippRead(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Note on the PIN session timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
34
35
36
38
39
40
41
42
43
44
45
46
47
48
49
49
MX800 SERIES REFERENCE MANUAL
3
C ONTENTS
int ippWrite(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SetSecurePINDisplayParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
int ippPinEntryStatus(int *count, int *lastNonNumericKey) . . . . . . . . . . . . . .
ippTerminatePinEntry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPP Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPP Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GISKE Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VeriShield Security Scripts APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_DeleteKeys() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_LoadSysClearKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_LoadSysEncKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_LoadMasterClearKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_LoadMasterEncKey(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_CheckMasterKey(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SetSecurePINDisplayParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_SetPINParameter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_SelectPINAlgo(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_RequestPINEntry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_GetPINResponse() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_CancelPIN(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_InstallScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_GetScriptStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_UninstallScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iPS_ExecuteScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
pcPS_GetVSSVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security Services APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cryptoWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cryptoRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
rsa_calc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHA1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
generateRandom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isAttacked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
secVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
authFile(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
loadOSFiles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delta Smartcard Interface / CardSlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Serial Ports and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Serial Communication Control Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Packet_parms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Packet Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initialize Packet Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
endPktMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Packet Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COM Ports on the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . . . .
COM1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COM2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
MX800 SERIES REFERENCE MANUAL
50
51
54
55
56
57
57
57
57
57
59
60
61
62
63
64
65
66
68
69
70
73
74
75
76
77
79
80
81
82
83
84
85
86
87
88
89
90
91
92
92
93
93
94
94
94
95
96
97
98
98
99
C ONTENTS
COM3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
COM4 - Optional I/O Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
COM5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
IBM ECR Tailgate & Feature C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
ecrOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
ecrRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
ecrReadReject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
ecrStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
ecrWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
ecrClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
ecrDownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
ecrDnldCancel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
ECR Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
I4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
O4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
P4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
L4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
S4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
V4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
G4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Downloading Files from the ECR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Touch Panel / Signature Capture/TIFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
touchCmd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
touchCompNSave() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Signature Capture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
SigCapCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
SigCapGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
SigCapBoxApply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
TIFF API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
int SigCap2Tiff() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
dspSetBrightness() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Audio / Beeper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
soundCtrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
speaker(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
normalTone() / errorTone() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
LEDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
ledOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
ledOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Real-Time Clock (RTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
setRTC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
setDateTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
CHAPTER 5
Service Functions Service Functions for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . 143
svcCrcCalc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcDsp2Hex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcRestart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoKernel() / svcInfoEprom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoRFS() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
144
146
147
148
149
MX800 SERIES REFERENCE MANUAL
5
C ONTENTS
svcInfoSerialNum() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoPtid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoPlatform(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoDsp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoCard() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcInfoSerialNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcZontalkRcv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
zontalkCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcSetOpenBlock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcSetRxCallback(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcReleaseRxCallback(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcSetAlarmCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcReleaseAlarmCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcAlarm(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcGetPortStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcGetInQ(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcGetOutQ() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcExpand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcUsbStorPresent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COM3 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3SetMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3ReqExtStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3ReqTallyInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3ResTallyData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3ReqFirmVers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3SetDeviceAddr(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3SetECLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3SetHandshake() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3FlushRxBuf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3SetRxRecThresh() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3SetBufFlushInt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcCom3Polled(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svcGetSysMillisec(), svcGetSysMicrosec(). . . . . . . . . . . . . . . . . . . . . . . . .
enableProcessMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
disableProcessMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
enableButtonSig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
disableButtonSig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
150
151
152
154
155
156
157
158
159
161
162
163
164
165
166
167
168
170
171
172
173
174
175
176
178
179
180
181
182
183
185
186
187
188
189
190
191
192
193
CHAPTER 6
System Mode System Mode for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . 195
CHAPTER 7
Root File System Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Organization of Files in the Standard Directory Structure. . . . . . . . . . . . . . 198
User Space Base Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
User Space and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
CHAPTER 8
USB - Device / Host USB Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
USB Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
6
MX800 SERIES REFERENCE MANUAL
C ONTENTS
USB Mass Storage and Memory Devices. . . . . . . . . . . . . . . . . . . . . . . . . . 202
USB Human Interface Device (HID) Support . . . . . . . . . . . . . . . . . . . . . . . . . . 204
CHAPTER 9
TCP/IP Ethernet Network Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Network Configuration Environment Variables . . . . . . . . . . . . . . . . . . . . . .
netUP() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
netDown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
netGetConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
netLinkStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getSysctl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Network Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
netPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ftpGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ftpPut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
205
206
207
208
209
210
211
212
213
214
C H A P T E R 10
IPP Legacy Library IPP Support for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . . 215
ipp_getpin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ipp_read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ipp_mac() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ipp_abort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ipp_diag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select_key_mgmnt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
get_key_mgmnt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
217
219
222
224
225
227
229
C H A P T E R 11
Contactless RF Library API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
RFCRlibVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Card Reader Module
RFCRInit(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRGetVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRReset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRSetAntenna(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRSetIndicator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRGetCardPayload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRParseCardPayload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRUpdateFW() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRPurge() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRInputPending() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRRawWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRRawRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRAddCRC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRCheckCRC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRReceiveACKFrame(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCRReceiveDataFrame(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RFCR Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
C H A P T E R 12
Input Events inputOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
inputRead(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
inputClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
MX800 SERIES REFERENCE MANUAL
7
C ONTENTS
C H A P T E R 13
Visual Payments Visual Payments Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
vpInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
vpParseFields(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
vpSendPacket() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
vpExit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
vpVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Visual Payments Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
fnDownReq(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
fnDownFileStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
fnUpData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
fnUpDisconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
fnTimedOut(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Network/Ethernet Library Functions Required by Visual Payments . . . . . . . . . 267
ftpPut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
ftpGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
netLinkStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
netDown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
netUp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
netPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
XFTP Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
XFTPGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
XFTPPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
XFTPDEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
IPP MS and DUKPT Advanced Programming in IPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Minor Differences by Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Communications
<SI>0103<SO> PROM Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Packets
<SI>0108<SO> IPP ROM Version Number . . . . . . . . . . . . . . . . . . . . . . 275
<SI>13n<SO> Select Baud Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
<SI>15SPAIN<SO> Set IPP6 Key Management Mode . . . . . . . . . . . . . 276
<SI>17xyz<SO> Set IPP7 Key Management Mode . . . . . . . . . . . . . . . 276
<SI>02…<SO> Set Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
<STX>75..<ETX> DUKPT Accept and Encrypt PIN/Data Authentication
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Packets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Packet Acknowledgement and Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
MS Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
DUKPT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
NAKs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Time Outs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Key Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Master Key Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
DUKPT Initial PIN Encryption Key Insertion . . . . . . . . . . . . . . . . . . . . . 281
Entering a PIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Restrict the Speed of the PIN Encryption Operation. . . . . . . . . . . . . . . . . . 281
IPP7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
GISKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Key Management Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Using a Session Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Loading the Session Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8
MX800 SERIES REFERENCE MANUAL
C ONTENTS
Master Key for PIN Encryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Rules for Loading the Master Key
(MS only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
KLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
3DES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
1DES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Master Key Addressing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Clear Text GISKE Key Block Loading Rule . . . . . . . . . . . . . . . . . . . . . . . . 287
Common Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Packet 01: Interactive Diagnostic Routine . . . . . . . . . . . . . . . . . . . . . . . . . 289
Packet 05: Transfer Serial Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Packet 06: Request PIN Pad Serial Number . . . . . . . . . . . . . . . . . . . . . . . 290
Packets 09 and 14: Response Packet to Packet 01 . . . . . . . . . . . . . . . . . . 291
Packet 11: PIN Pad Connection Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Packets 7 and 12: Dummy Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Packet 13: Select Baud Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Packet 15: Set IPP Key Management Mode . . . . . . . . . . . . . . . . . . . . . . . 298
Packet 17: Set IPP7 Key Management Mode . . . . . . . . . . . . . . . . . . . . . . 300
Packet 18: Check IPP7 Key Management Mode . . . . . . . . . . . . . . . . . . . . 305
Packet Z60: Accept and Encrypt PIN (VISA Mode) . . . . . . . . . . . . . . . . . . 309
Errors returned by write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Packet Z63: Accept and Encrypt PIN–Custom PIN Entry Requirements
(VISA Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Errors returned by write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Packet M04: Read Permanent Unit Serial Number . . . . . . . . . . . . . . . . . . 313
MS-Specific Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Packet 02: Transfer Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Communication Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Key-only Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
GISKE Key Block Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Packet 04: Check Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Packet 04 Communication Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Packet 04 Key-only Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Packet 04 GISKE Key Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
MS Packet 08: Select a Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
MS Packet 71: Transfer PIN Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Packet 07: Dummy Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
DUKPT-Specific Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Packet 19: Select a DUKPT Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Packet 25: Check the DUKPT Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
DUKPT Packet 73: Transfer PIN Block (for Packets Z60 or Z63). . . . . . . . 327
DUKPT Packet 90: Load Initial Key Request . . . . . . . . . . . . . . . . . . . . . . . 328
DUKPT Packet 91: Load Initial Key Response . . . . . . . . . . . . . . . . . . . . . . 329
DUKPT Packet 76: PIN Entry Test Request . . . . . . . . . . . . . . . . . . . . . . . . 330
DUKPT Packet 71: Transfer PIN Block - (for Packet 76) . . . . . . . . . . . . . . 331
DUKPT Packets 92 and 93 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
DUKPT Z69 Packet: Accept and Encrypt PIN / Data Authentication Request .
332
Errors returned by write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
DUKPT Packet 75: DUKPT Accept and Encrypt PIN/Data Authentication
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MX800 SERIES REFERENCE MANUAL
9
C ONTENTS
Packet 78: DUKPT Accept and Encrypt PIN/Data Authentication Test Request
335
MAC-Specific Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
MAC Packet Z66: Request MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Rules of Request MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
MAC Packet Z67: Return MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Packet 72: Cancel MAC Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
MAC Module Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
ANSI (Standard) MAC Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
10
MX800 SERIES REFERENCE MANUAL
CHAPTER 1
Introduction
Scope
This document describes the programming environment for the Mx800 series of
terminals. This document lists or references all significant functions unique to the
terminal.
This document will not describe the Linux application API. There are many
good books on this topic. This document will list unsupported features and
any deviations from “standard” Linux.
Distinction will be drawn, where possible, between functions that are built into the
terminal and are available when no application is present and functions that only
become available if the application performs the correct programming operations.
Modifications to
this document
Acronyms,
Abbreviations,
and Definitions
This document may be changed or extended to include new product
requirements.
Table 1
Acronyms, Abbreviations, and Definitions
Abbreviation
Definition
ISR
Interrupt Service Routine
Firmware
Software in FLASH/ROM
JFSS2
Journaling Flash File System
NFS
Network File System
FTP
File Transfer Protocol
iPKG
The Itsy Package Management System
MSR
Magnetic Stripe Reader
IPP
Internal PIN Pad
PED
PIN Entry Device
VSS
VeriShield Security Scripts
FA
File Authentication
KLK
VSS Key Loading Key
KVC
Key Verification Code
SAM
Security Access Module
OSS
Open Sound System
LED
Light Emitting Diode
RTC
Real-time Clock
RRT
Receive Record Threshold
BFI
Buffer Flush Interval
RFCR
RF Card Reader
MX800 SERIES PROGRAMMERS GUIDE
11
I NTRODUCTION
Conventions Used in this Document
Table 1
Abbreviation
Definition
CRC
Cyclic Redundancy Check
bps
bits per second
MS
Master Session
KSN
Key Serial Number
PEK
PIN Encryption Key
GISKE
Global Interoperable Secure Key Exchange
Table 2
Conventions
Used in this
Document
Acronyms, Abbreviations, and Definitions
Major Hardware Devices
ARM9
ARM SoC
Graphic Display
Color (16 bpp) QVGA (320x234)
The following table describes the conventions used:
Table 3
Document Conventions
Convention
Meaning
Blue
Text in blue indicates terms that are cross referenced.
Courier
The courier typeface is used while specifying onscreen text, such
as text that you would enter at a command prompt.
Italics
Italic typeface indicates book titles or emphasis.
SCREENTEXT
This format is used while specifying on screen text, such as text
that you would enter at a command prompt, or to provide an
URL.
The pencil icon is used to highlight important information.
NOTE
CAUTION
The caution symbol indicates possible hardware or software
failure, or loss of data.
Recommended Beginning Linux Programming (3rd Edition)
LINUX Books
By: Neil Matthew, Richard Stones
See: http://www.wrox.com/WileyCDA/WroxTitle/productCd-0764544977.html
12
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 2
Overview of Product Deliverables
Operating
System and
Firmware
The Mx800 series terminal is the first VeriFone product to run ARM embedded
Linux. The initial kernel will be version 2.6.10.
Required libraries are described in the succeeding sections.
C Compiler and The GNU C compiler will be used to build Mx800 Series applications. The
Tools Software Development Kit will include a version of the GNU development tools
that will run under Windows (using Cygwin).
The Mx800 Series terminal will include gdbserver for use during application
debug.
VeriFone has created a "plug in" feature for the Eclipse IDE that simplifies
application project building and debug.
MX800 SERIES PROGRAMMERS GUIDE
13
O VERVIEW OF P RODUCT D ELIVERABLES
Operating System and Firmware
14
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 3
File Systems
The Mx800 series terminal file system uses the Journaling Flash File System or
JFFS2. JFFS2 is used to store application code and data as well as shared
libraries. JFFS2 supports wear leveling and power fail protection.
File
Compression
The Mx800 series of terminals will support GNU ZIP (.gz or .tgz or tar.gz)
compressed files. The system will support both creation and expansion of GNU
ZIP files. Downloaded files may be compressed. The TAR format is used to
combine multiple files into a single file. The resulting file may then be compressed.
This process produces a tar.gz file. Winzip can open a tar.gz file but it cannot
create one. There are a number of applications available to create tar.gz files on a
Windows platform.
Environment/
Configuration
Variables
Linux has long had the concept of environment variables (also called
configuration variables). Unfortunately, environment variables are not permanent
and Linux normally requires a shell script that sets the environment variables prior
to their use. The Mx800 series of terminals will augment this process by having
files in battery backed SRAM to store configuration variables.
getenv() and putenv() are native functions to Linux. Using putenv() will set/
change/delete an environment variable but the value will not persist if a power
failure occurs. The Mx800 series of terminals supports enhanced APIs
getEnvFile() and putEnvFile() to get or set environment variables in the
battery backed SRAM file system.
File Format Details The Mx800 series of terminals uses a standard file format to store configuration
variables. The file stores ASCII information in .ini format.
For example:
[perm]
i4683=R232
o4683=01234567
[reg]
store=sportworld
appid=1234
INI files consist of section headers (defined within [ ]) followed by keys (or
labels) and their associated values. For example, appid is a key with value 1234
and it resides under section reg.
MX800 SERIES PROGRAMMERS GUIDE
15
F ILE S YSTEMS
Environment/Configuration Variables
By default, all configuration files will have two sections, perm and reg. The perm
section is special in that entries under perm will not be deleted on a full download.
All other section entries will be deleted on a full download. To aid compatibility with
previous terminals, all keys that begin with “*” will automatically be placed in the
“perm” section provided the section parameter is a pointer to an empty null
terminated string. (i.e. empty quotes “”). The leading “*” character is not
actually stored in this case. It only indicates that the label field should be stored in
or retrieved from the perm section. If a section is specified then the value field is
stored as it is given to the function, including any ‘*’ character. This also applies
even if the section is specified to be the perm section. It is only if an empty, nullterminated string is specified for the section is any leading “*” character ignored.
All created sections, and label entries will be converted to lower case before being
stored to eliminate case sensitivity. The getEnvFile() and putEnvFile()
functions will always convert to lower case before searching or storing.
The value part of the environment variable is case-sensitive and will always be
stored as it is passed to the functions. There are certain reserved characters with
the INI parser library that cannot be used in section, label or value fields and there
are certain characters that are not accepted. All other characters can be used
including non-printable ASCII characters. Please refer to the INI parser html
document included in the SDK for basic explanation of how the INI parser works
and what is supported. In addition to that documentation, the following characters
are reserved and cannot be used within one or more of the fields of the
environment variable or have special rules concerning them:
Table 4
16
Character
Hex
Decimal
Usage
Null
0x00
0
Used to terminate string and cannot be
stored as part of section, label or value
field.
Space
0x20
32
Cannot be used in leading and trailing
position of section, label or value field.
Can only be used in non-leading and
trailing positions.
Equal (=)
0x3D
61
This is a reserved character and cannot
be used in any field. If used, unexpected
and unsupported results may occur.
Horizontal Tab
0x09
9
Cannot be used in leading and trailing
position of section, label or value field.
Can only be used in non-leading and
trailing positions.
Line Feed
0x0A
10
This is a reserved character and cannot
be used in any field. If used, unexpected
and unsupported results may occur.
Vertical Tab
0x0B
11
Cannot be used in leading and trailing
position of section, label or value field.
Can only be used in non-leading and
trailing positions.
MX800 SERIES PROGRAMMERS GUIDE
F ILE S YSTEMS
Environment/Configuration Variables
Table 4
NOTE
Character
Hex
Decimal
Usage
Form Feed
0x0C
12
This is a reserved character and cannot
be used in any field. If used, unexpected
and unsupported results may occur.
Carriage Return
0x0D
13
This is a reserved character and cannot
be used in any field. If used, unexpected
and unsupported results may occur.
Hash Sign (#)
0x23
35
This character is used for comments to
be inserted into configuration file. Any
section specified for a label starting with
the # character will be inserted into the
file and the line will be treated as a
comment.
Semi-colon (;)
0x3B
59
This character is used for comments to
be inserted into configuration file.
Anything after a “;” character is treated
as and inserted into the file as a
comment.
Forward Slash (/)
0x2F
47
This is a reserved character and cannot
be used within the section field.
Left Bracket ([)
0x5B
91
This is a reserved character and cannot
be used within any field. If used,
unexpected and unsupported results
may occur.
Right Bracket (])
0x5D
93
This is a reserved character and cannot
be used within the section field.
None of the environment variables in the configuration file actually reside in the
current shell environment.
Most shell environment variables in Linux/Unix systems are stored in upper case.
If an application expects an environment variable that resides in a configuration
file to use the current case-setting, the application must retrieve the environment
variable from the configuration file and then set it to use the current shell
environment using putenv().
For instance, if the environment variable “myfile=some_path” is stored in a
configuration file, the application must perform a getEnvFile() for “myfile” to
retrieve its value and then set it in the current shell environment with
putenv(“MYFILE=some_path”) as the application expects the case to be set.
Until a putenv() is performed with case-sensitivity in mind, the variable does not
reside in the current shell environment.
MX800 SERIES PROGRAMMERS GUIDE
17
F ILE S YSTEMS
Environment/Configuration Variables
There are also command line versions of these 2 functions below called
getEnvFile and putEnvFile that are mainly used for development purposes.
When these command line versions are used, it is necessary to double-quote
each part, label, and value fields separately to prevent the Linux shell from
interpreting the characters. Each part needs to be quoted separately.
For example: putenvfile “*dhcp” “1”. Also, these functions do not support
the creation of custom sections. For a custom section to be created, use the API
function putEnvFile with the label parameter set to an empty, null-terminated
string (i.e. “”) and the section parameter set to the desired new section name. The
custom section will not be created if the label parameter is not an empty string.
Each user will have its own configuration file called “config.usrx” where value
of x is 1-8. Root will have its own configuration file. The configuration files will be
stored in the file system at /mnt/sram directory. The system limits each
configuration variable to a maximum of 8KB, once reached, it is not possible to
add and modify configuration variables.
18
MX800 SERIES PROGRAMMERS GUIDE
F ILE S YSTEMS
getEnvFile
getEnvFile
Prototype
int result = getEnvFile(char *section, char *label, char *value, int
vlen);
Parameters
section
Points to a null terminated string containing the .ini file section
name. Maximum length of the section name is 32 bytes.
Note:
If section is a pointer to null, the system will
automatically read from with perm or reg. perm will be
selected if the first character of label is an “*” otherwise
section reg is used.
label
Points to a null terminated string containing the label (reference
name) of the entry. Maximum length of the label is 32 bytes and
will automatically be converted to lowercase before searching for
its value.
value
Points to an area where the value of the environment variable will
be copied. Maximum length is 512 bytes.
Value will be null terminated.
vlen
Maximum length of the value field. If the length of value is larger
than vlen-1 then only vlen-1 bytes will be copied to value.
Return Values
Greater than 0
Length of value
0
Entry not found
Less than 0
An error occured:
-ENOBUFS
Internal message error
MX800 SERIES PROGRAMMERS GUIDE
19
F ILE S YSTEMS
putEnvFile
putEnvFile
Prototype
int result = putEnvFile(char *section, char *label, char *value, unsigned
short vlen, unsigned short options);
Parameters
section
Points to a null terminated string containing the .ini file section
name. Maximum length of the section name is 31 bytes.
Note:
If section is a pointer to null, the system will
automatically read from with perm or reg. perm will be
selected if the first character of label is an “*” otherwise
section reg is used.
label
Points to a null terminated string containing the label (reference
name) of the entry. Maximum length of the label is 32 bytes and
will automatically be converted to lowercase before being stored.
To create a new section, pass a pointer to null (i.e. empty string
““) for the label parameter.
value
Points to a null terminated string containing the value associated
with the label. Maximum length is 512 bytes.
To delete an entry pass a pointer to null for the value parameter
(i.e. empty string ““).
Return Values
0
No error
Less than 0
An error occured:
-ENOBUFS
20
MX800 SERIES PROGRAMMERS GUIDE
No environment variable space
F ILE S YSTEMS
putEnvFile
System The following table of configuration variables are read by the system on power up/
Configuration reboot. These configuration variables must be set within the usr1 account.
Variables Table 5
Variable Name
Values
Definition
*GO
Executable name
The path /home/usr1 is
pre-pended to the value set
in *GO.
Example:
*GO=myapp
The system will attempt to
execute the file:
/home/usr1/myapp
Note that Linux is casesensitive.
*NETOFF
1
If *NETOFF exists (set to
any value), then TCP/IP
functions (*DHCP,
*IPCONFIG, *GATEWAY)
are disabled.
*DHCP
Non-zero
If *DHCP is present and the
system supports Ethernet,
then it will attempt to
initialize its connection via
DHCP.
*IFCONFIG
Per Linux – No need to
set MAC address as the
system will do this for
you. See Chapter 9.
Use either *DHCP or
*IFCONFIG.
*GATEWAY
IP Address in the form
xxx.xxx.xxx.xxx
Used to define the address
of the gateway (router).
*TELNET
1
If *TELNET is present and
the system supports
Ethernet, then it will start the
Telnet server daemon.
*DBG
1
If *DBG is present then the
Visual Esto debugger will be
enabled
*BACKLIGHT
1-31
Sets the display backlight
brightness. Default is 15.
*VOLUME
0-100
Sets the speaker volume.
Default is 50.
*MOUNT0 - *MOUNT9
Per Linux.
Allows up to 10 mount
points to be defined.
Example:
“-t nfs –o nolock
10.64.88.249:/nfs /mnt/
smfnfs”
MX800 SERIES PROGRAMMERS GUIDE
21
F ILE S YSTEMS
putEnvFile
Table 5
Variable Name
Values
Definition
*USB DEVICE
1
Enable USB serial device
mode. You must reboot after
setting this variable.
Remove variable and reboot
to disable.
*USBHOST
1
IF *USBHOST exists, USB
host (hotplug) will be
disabled.
*FTPHOST
xxx.xxx.xxx.xxx or ASCII
server DNS name
Either IP address or DNS
name of FTP server.
Max length = 96
characters
*FTPPORT
Default = 21
Port number for FTP
connection.
*FTPFILE
Default=app.tgz
Max length = 96
characters
Remote file name (and path)
of file to be retrieved from
the FTP server.
Default = Terminal S/N
FTP password
*FTPPWD
Max length = 32
characters
*FTPUSER
Default = anonymous
FTP User ID
Max length = 32
characters
*SYSLOG_MARK
Default = 30
Min = 10
Max = 1440
Specifies when a “MARK”
timestamp marker is placed
in the syslog messages file.
Off = 0
22
*SYSLOG_RHOST
Default = null
Specify a remote IP address
to send syslog messages
via a UDP network
connection.
*SYSLOG_RPORT
Default = 5140
Specify what port to use
when sending syslog
messages to remote UDP
network connection.
*SYSLOG_RLOG
Default = TRUE
Log syslog messages
remotely.
*SYSLOG_USRLOCAL
Default = FALSE
Log user log messages
locally (this option does not
affect OS or root generated
messages).
MX800 SERIES PROGRAMMERS GUIDE
F ILE S YSTEMS
putEnvFile
Table 5
Variable Name
Values
Definition
*VPAY
1
If * VPAY exist and there is
no application loaded, the
system will attempt to
contact the Visual Payments
host for an application
download.
*VPAYSERVERADDRESS
xxx.xxx.xxx.xxx
IP address of Visual
Payments server.
*VPAYSERVERPORT
xxxxx
Connection Port address on
Visual Payments server.
*VPDOWNPORT
xxxxx
Connection Port address on
the Mx800 series terminal.
MX800 SERIES PROGRAMMERS GUIDE
23
F ILE S YSTEMS
getSysctl()
getSysctl()
Reads the value of the kernel parameters in the /proc/sys directory using the
sysctl utility.
Prototype
int result = getSysctl(char *var, char *value, int vlen);
Parameters
var
Points to a null terminated string containing the kernel parameter to
reference. Maximum length of the label is 128 bytes and will
automatically be converted to lower case before searching for its value.
value
Points to an area where the value of the kernel parameter will be copied.
Maximum length is 128 bytes. Value will be null terminated.
vlen
Maximum length of the value field. If the length of value is larger than
vlen-1 then only vlen-1 bytes will be copied to value.
Return Values
>0
Len of value
=0
Entry not found.
<0
An error has occurred:
EINVAL = Invalid parameter
ENOENT = Invalid kernel parameter
ENOBUFS = Internal message error
24
MX800 SERIES PROGRAMMERS GUIDE
F ILE S YSTEMS
putSysctl()
putSysctl()
Dynamically modifies the value of the kernel parameters in the /proc/sys
directories using the sysctl utility. The changes are valid until the terminal reboots.
Currently, users are limited to change only the /proc/sys/net/ipv4 kernel
parameters.
Prototype
int result = putSysctl(char *var, char *value, int vlen);
Parameters
var
Points to a null terminated string containing the kernel parameter and
value setting, in the format “variable=value”. Maximum length of the label
is 128 bytes.
Return Values
=0
Success
<0
An error has occurred:
EINVAL = Invalid parameter
ENOENT = Invalid kernel parameter
ENOBUFS = Internal message error
MX800 SERIES PROGRAMMERS GUIDE
25
F ILE S YSTEMS
Syslog Messages
Syslog
Messages
The Mx800 series of terminals supports logging messages generated by
syslog() method calls. These messages are stored in chronological order in the
file system /mnt/sram/. This file system is located in the battery-backed SRAM.
There are up to four file messages that are dependent on the number of
messages that have been logged. When this file reaches the maximum size, the
files are rotated such that message is renamed to messages.1 and a new
messages file is started. If messages.1 already exists, it is renamed to
messages.2, if messages.2 already exists, it is renamed to messages.3, and
if messages.3 exists, it is removed.
NOTE
Log messages are maintained across boots and power down/up operations.
Remote Logging The syslog daemon on the terminal supports sending the logged messages to a
remote UDP network connection. To enable this feature, there are several
config.usr1 parameters that are required to be set, once the terminal is
rebooted, remote logging will be enabled. The config.usr1 parameters are
described in Chapter 5. The two parameters that must be specified are
SYSLOG_RHOST and SYSLOG_LOG.
Downloading
The Mx800 series will support the following methods for downloading files:
1 Zontalk – Included for compatibility only. The Linux concepts of file ownership,
privileges, and directory paths will not be fully supported under Zontalk. Files
must be converted to .TAR format in order to preserve path and user
information. Zontalk will be implemented in system mode as well as be
available through a shared library.
If files are downloaded without being converted to .tar format, then files with
the .SH, .EXE, and .OUT extensions will automatically have their permissions
set to executable. All other files will be read/write for the owner only. If a file
that is converted to .TAR format is downloaded, permissions will be set
according to what they were at the time the file was archived. After an
expansion of a .TAR file is completed, the ownership for all files contained
within the user’s home directory will be set to that users ownership, unless
they are already owned by root. Filenames of downloaded files are currently
limited to 60 characters or less.
2 NFS – The Network File System allows for seamless remote access to files.
The Mx800 series of terminals will act as a client and connect to an NFS
server. The server will control file access privileges. The files that the Mx800
series of terminals may access on the NFS server appear to be local, thus
allowing then to be executed, copied, etc. Windows PCs will require an NFS
server to be installed.
26
MX800 SERIES PROGRAMMERS GUIDE
F ILE S YSTEMS
Downloading
3 TCP/IP – System Mode supports initial application loading via FTP. A library is
provided to simplify FTP file transfers.
4 IBM ECR – The Mx800 series of terminals supports file download from an IBM
ECR. The download file will need to be properly formatted using VeriFone’s
PCLANCNV utility. The concatenation / compression facility in PCLANCNV
will no longer be supported. Instead, files may be converted to .TAR format
(concatenation) and GNU Zipped (compressed) and then passed through
PCLANCNV. Configuration variables will continue to be supported via
PCLANCNV.
5 USB Memory Device - System Mode supports OS and Application upgrade/
install via USB memory devices. Applications can access the USB memory
device via /mnt/usbstor1.
Downloaded Notes
•
The downloaded .TAR or .TGZ files expands automatically, ensure that the
standard GZIP Compressed .TGZ and .TAR extensions are used.
•
Users can create any directory structure provided that it is under the /home/
usr1 directory.
•
During .TAR file expansion, the system will automatically set owner/group
permission for each file. The default permissions are: owner=read/write/
execute, group=read and other=read.
•
Full downloads will delete all files in the directory including all hidden files and
their sub-directories located in /home/usr1.
•
It is understood that files may be transferred to a Mx800 series terminal by
means other than those defined by the operating system. If files are
transferred via custom/proprietary mechanisms, it is recommended that they
be sent in the form of a .TAR file and are placed in the base path of the user
(i.e. usr1 would be /home/usr1). After the file is transferred to the terminal, it
is important that the application calls svcExpand() and loadOSFiles() to
properly expand and install the files contained in the .TAR file.
MX800 SERIES PROGRAMMERS GUIDE
27
F ILE S YSTEMS
File Authentication and Certificates
•
If a .TAR file contains a special file named config.usrx (where x is 1 to 8)
the system will read the downloaded config.usrx file and update the users
configuration. This feature allows configuration variables to be added/deleted
or changed without using Zontalk, or ECR protocol that has built in support for
configuration variables. The content of the special config.usrx file is simple
ASCII with a <CR> character at the end of each line. An equal = character is
used to separate a variable from its value. To delete an entry, enter the
variable with an equal = character.
An example config.usr1 file:
*DHCP=
*GO=screen-demo.exe
In the example, the *DHCP variable will be deleted and *GO will be set/
changed.
NOTE
File
Authentication
and Certificates
Including the variable *usr1pwd, config.usr1 will set the System Mode /
login password for usr1 to its value. For example: *usr1pwd=123456 will set
usr1 password to 123456.
The Mx800 series implements VeriFone’s VeriShield File Authentication module.
All executable code must be authenticated prior to running. File authentication
authority is split in to two branches. One branch is owned by VeriFone and
encompasses Kernel / OS code. This includes driver modules. The second
branch is owned by the customer/VAR and encompasses applications.
All directories and files with root ownership are considered Kernel/OS owned and
must be authenticated by OS signing authority. Applications will reside in user
space directories and will require application signing authority.
Application authentication is performed each time an application is executed. The
system scans the directory where the application resides for a .p7s file that
contains the name of the application. This means that the .p7s and the
application do not need to have the same name. Remember that Linux is case
sensitive and it is important that the file named in the .p7s have the same case as
the application.
The system expects certificate files to be placed in a directory named: crt under
the base path for the user. For usr1, the path would be /home/usr1/crt. If a file
fails authentication, the system automatically scans the crt directory for a
certificate that may need to be installed.
Package
Management
28
The terminal supports the ability to group or package a collection of files as a
single package/file that can be downloaded and installed into the terminal. This
package management is called iPKG (The Itsy Package Management System).
iPKG is a very lightweight package management system that allows for dynamic
installation/removal of packages on a running system.
MX800 SERIES PROGRAMMERS GUIDE
F ILE S YSTEMS
Package Management
iPKG has an executable module called ipkg located on the terminal in /bin and a
Linux (or Cygwin) shell script called ipkg-build that is in the Mx870 SDK. The
terminal resident ipkg module is used to install and remove packages. All user
packages are installed with the user home directory (/home/usr1) as the root.
The module ipkg has numerous options, but the three that are applicable to the
terminal are:
install <file.ipk>
Install package <file.ipk>
remove <pkg>
Remove package <pkg>
list_installed
List all and only the installed packages and
description
Building ipkgs Here is a guide to building packages for the ipkg package management system:
1 Create the directory structure and files as you want them to appear on the
installed system.
2 Create a directory named \control at the top-level of this directory structure.
3 Inside \control create a file named "control" with lines of the form "Field:
value". Required fields are Package, Version, Architecture, Maintainer,
Section, Priority and Description. Optional fields include Depends. The
meaning of each of the fields will be given later in this document.
There are also a few optional script files. These are the pre and post
installation scripts, and pre and post uninstallation scripts. There is also one
other file called conffiles that can contain a list of configuration files used
by your program that should not be overwritten when your package is
upgraded.
•
opreinst - Pre-installation (before the actual program files are
extracted).
•
opostinst - Post-installation (after the program files have been
extracted).
•
oprerm - Pre-uninstallation (before your files are removed).
•
opostrm - Post-uninstallation (after files have been removed).
•
oconffiles - List of configuration files not to be overwritten during an
upgrade.
MX800 SERIES PROGRAMMERS GUIDE
29
F ILE S YSTEMS
Package Management
Below is an example of a control file:
Package: openssl
Source: ./openssl_0.9.8a_mx870.tar.gz
Version: 0.9.8a-mx870
Priority: optional
Section: libs
Maintainer: John Doe
<John_d1@verifone.com>
Architecture: arm
Description: SSL library
The library used for Secure Socket
Layer communication.
4 If your package has any configuration files, then create a file
\control\conffiles which lists the absolute path of each configuration
file. This will prevent the package management system from automatically
overwriting configuration changes when the user upgrades the package.
5 If needed, your package may include script files that are called by the package
maintenance system. There are four possible times a script file will be run: just
before your package is installed, just after your package is installed, just
before the package is removed, and just after the package is removed. These
script files are named preinst, postinst, prerm, and postrm and should be
located in the \control directory. The scripts should return 0 on success, (a
non-zero return value from preinst will prevent your package from being
installed -- this can be useful in some situations). The scripts can assume a tty
is available so they may prompt the user. Note that the variable PKG_ROOT is
set to the root of the package installation and can be used to refer to the
packages contents in their installed locations.
6 Now simply run:
ipkg-build directory [destination_directory]
where directory is the directory you have created. The
destination_directory is optional and defaults to the current directory.
The ipkg-build script peforms several sanity checks on the package directory
and should guide you through any problems.
The meaning of the various fields in CONTROL/control are as follow:
Package
30
MX800 SERIES PROGRAMMERS GUIDE
is the name of the package and should match the regular expression [az0-9.+-]\+
F ILE S YSTEMS
Package Management
Version
should have at least one digit and should match "[a-zA-Z0-9.+]*".
Version may also contain an optional trailing revision matching "-fam[09]\+". This revision should be incremented each time the package
changes but the version does not, (i.e. a packaging tweak). It may be
reset, (or simply omitted), each time the version is incremented.
Architecture
should specify the architecture for which the package is compiled. Valid
values currently include: arm, i386, m68k, ns32k, sh3, sparc, vax,
and all.
Maintainer
should be the name and email address of the person responsible for
maintaining the package, (not necessarily the author of the program).
Description
should be a short, (less than 80 characters) description of the program.
It may also include a long description on subsequent lines, (each
indented by a single space character). Blank lines in the long description
may be indicated by a line consisting of a space character followed by a
period, i.e. " ."
Priority
should be one of: required, standard, important, optional, or extra. Most
programs should use optional.
Section
can be one of the following: admin, base, comm, editors, extras,
graphics, libs, misc, net, text, web, x11.
Depends
indicates packages which must also be installed in order for this
package to work. The packages should be listed on a single line,
separated by commas.
Installing ipkgs The ipkg files (.pkg extension) can be placed in the terminal similar to how .TAR
files are placed. If the terminal is locked/deployed, the .PKG file is signed,
downloaded and installed in the same manner as an application .TAR file.
If the terminal is unlocked (such as during development), the user has the option
of manually installing/removing packages. Once the pkg file is in /home/usr1,
the user can execute: ipkg install package.PKG where package.PKG is
the file name of the package to be installed. To remove a previously installed
package, execute: ipkg remove package where package is the “name” of the
package as specified in the control file (to get a list of the installed packages,
execute: ipkg list_installed).
MX800 SERIES PROGRAMMERS GUIDE
31
F ILE S YSTEMS
Package Management
32
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 4
Device Drivers
Device Drivers
for the Mx800
series of
Terminals
The following device drivers are supported by Mx800 series of terminals:
Ethernet Port
Standard Linux support as /dev/eth0
Real Time Clock
Standard Linux support as /dev/rtc
4 Serial Ports
Standard Linux support as /dev/ttySAC0, ttySAC1,
ttySAC2
Note:
Requires Serial Port handshake enhancement
COM3 will be supported by the Wrenchman
module, device name /dev/ttyWR0
• COM1 = /dev/ttySAC0
• COM2 = /dev/ttySAC1
• COM3 = /dev/ttyWR0
• COM4 = /dev/ttySAC2
USB
Standard Linux support as /proc/bus/usb
USB device serial port is defined as:
COM5 = /dev/ttygser
Display
Standard Linux support as /dev/fb0
Sound
Standard Linux support as /dev/dsp
Magnetic Stripe Reader
VeriFone unique device /dev/msr
IPP
VeriFone unique device /dev/ipp
Delta
VeriFone unique device /dev/delta
Touch panel
Standard Linux /dev/input/mice
Details on the standard Linux drivers are available from the open source
community. The succeeding sections will detail the VeriFone specific drivers.
MX800 SERIES PROGRAMMERS GUIDE
33
D EVICE D RIVERS
Magnetic Stripe Reader
Magnetic Stripe
Reader
All Mx800 series of terminals include a triple track magnetic stripe reader.
Accessing the Magnetic Stripe Reader requires linking with the shared library:
libvfimsr.so. The header file msrDevice.h is used by the application to
access the library.
Example Using the Card Reader
// This program reads the card reader device and prints the result to
STDOUT
main()
{
int result;
charbuffer[200];
result = msrOpen( O_RDONLY, NULL );
while(1) /* infinite loop */
{
memset(buffer, 0, sizeof(buffer));
int = msrRead(buffer,sizeof(buffer));
/* wait for input from card reader */
printf("msrRead returned %d bytes of data", result);
}
}
34
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
msrOpen
msrOpen
This interface prepares the firmware to accept and store card reads. If the
programmer does not make this call, then the terminal will ignore all card reads.
The MSR device allows only one open at a time.
Prototype
int result = msrOpen(int flags, void *callback);
Parameters
Specify device access permissions for the MSR device. The
pertinent ones are:
flags
O_RDONLY
Read Only
O_RDWR
Read and Write
O_NONBLOCK
Read is non-blocking (default is
blocking)
Pointer to callback function. If available, this callback function will
be called when data is available.
callback
Return Values
0
Magnetic Stripe Reader is open and ready
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
35
D EVICE D RIVERS
msrRead
msrRead
Read the decoded and formatted MSR data. If the device is not opened with the
O_NONBLOCK flag set, this call will be blocked until data is available.
Prototype
int bytes_read = msrRead(char *buffer, int size);
Parameters
buffer
Pointer to data area
size
Maximum number of bytes to read. Each invocation of read will
transfer data from a card reader scan into the buffer.
The format of the buffer returned will be:
c1
s1
d1
c2
s2
d2
c3
s3
d3
where:
c1
a one byte size of c1+s1+d1
s1
a one byte status of reading track 1
d1
any data read in (might not exist)
c2
a one byte size of c2+s2+d2
s2
a one byte status of reading track 2
d2
any data read in (might not exist)
c3
a one byte size of c3+s3+d3
s3
a one byte status of reading track 3
d3
any data read in (might not exist)
The data includes the Start Sentinel, End Sentinel, and the LRC
characters. They were not included in the Omni 7xxx.
36
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
msrRead
The status byte (s1,s2,s3) can have one of the following values:
NOTE
0
valid data
1
no data
2
missing start sentinel or insufficient data
3
missing end sentinel or excessive data
4
missing BCC or BCC error
5
parity error
The returned error status may not reflect the exact cause because the algorithm
tries to decode data in both direction streams. An error in one direction stream
may not produce the same error as in the other.
The decode algorithm searches the entire data stream for the start sentinel.
Return Values
>=0
Total number of bytes read
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
37
D EVICE D RIVERS
msrWrite
msrWrite
This operation transfers data from an application buffer into the device driver's
buffer. The data is used for the next read operation.
Prototype
int bytes_written = msrWrite(char *buffer, int size);
Parameters
buffer
Pointer to data area
size
Maximum number of bytes to read. Each invocation of read will
transfer data from a card reader scan into the buffer.
Size is the maximum number of bytes to write and buffer is a pointer to the data
area.
Return Values
0
No data written
>0
Number of bytes written
NOTE
This call is placed to support test program development and debugging modes.
38
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
msrMagneticCardPresent
msrMagneticCardPresent
Prototype
int result = msrMagneticCardPresent(void)
Return Values
0
No data available
1
Data available
2
Magnetic field present
MX800 SERIES PROGRAMMERS GUIDE
39
D EVICE D RIVERS
msrRaw
msrRaw
Allows an application to retrieve the raw magnetic stripe data and perform a
custom decode.
Prototype
int result = msrRaw(MSR_DATA * msr);
Parameters
The MSR_DATA structure is as follows:
typedef struct {
unsigned char ucStatus; // status of track
unsigned char ucCount; // size in bytes of track data
char *cpData; // pointer to track data
} MSR_TRACK_DATA;
typedef struct {
MSR_TRACK_DATA stTrack1;
MSR_TRACK_DATA stTrack2;
MSR_TRACK_DATA stTrack3;
} MSR_DATA;
Return Values
40
0
Data available
-1
No data available
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
msrStructured
msrStructured
Allows an application to retrieve the decoded magnetic stripe data in a structure.
Prototype
int result = msrStructured(MSR_DATA * msr);
Parameters
The MSR_DATA structure is as follows:
typedef struct {
unsigned char ucStatus; // status of track
unsigned char ucCount; // size in bytes of track data
char *cpData; // pointer to track data
} MSR_TRACK_DATA;
typedef struct {
MSR_TRACK_DATA stTrack1;
MSR_TRACK_DATA stTrack2;
MSR_TRACK_DATA stTrack3;
} MSR_DATA;
Return Values
0
Data available
-1
No data available
MX800 SERIES PROGRAMMERS GUIDE
41
D EVICE D RIVERS
msrEnableLicenseDecode
msrEnableLicenseDecode
Enables the decoding of California Drivers License and American Association of
Motor Vehicle Administrators (AAMVA) Drivers License.
NOTE
By default, California Drivers Licenses will not be decoded. This is for
compatibility with existing terminals and tests.
Prototype
int msrEnableLicenseDecode(void);
42
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
msrDisableLicenseDecode
msrDisableLicenseDecode
Disables the decoding of California Drivers License and American Association of
Motor Vehicle Administrators (AAMVA) Drivers License.
NOTE
By default, California Drivers Licenses will not be decoded. This is for
compatibility with existing terminals and tests.
Prototype
int msrDisableLicenseDecode(void);
MX800 SERIES PROGRAMMERS GUIDE
43
D EVICE D RIVERS
msrVersion()
msrVersion()
Prototype
int result = msrVersion(char*version)
Parameters
version
Pointer to read in the MSR library version, in the form:
xx.yy.zz
Return Values
44
0
Successful execution
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
msrClose
msrClose
This function disables the card reader input, preventing the terminal from
recognizing card reads.
Prototype
int result = msrClose(void);
Return Values
0
Successful execution
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
45
D EVICE D RIVERS
Internal PIN Pad
Internal PIN Pad
In the Omni 7xxx platform, the IPP7 was implemented in hardware. In the Mx800
series of terminals, the IPP chip is emulated in software. The application interface
is similar to the one in the Vx family of terminals.
Applications access the IPP through a virtual communication port.
The Mx800 series terminal IPP emulation contains most IPP7/IPP8 features,
including 3DES master/session, multiple DUKPT, and MAC processing. It does
not support the Spain, Interac, or Secure Messaging modes.
For information on the supported IPP packets, refer to Appendix A.
All IPP functions are defined in the header file svcsec.h. Applications must link
with the libvfisec.so library by using -lvfisec.
46
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
int ippOpen(void)
int ippOpen(void)
ippOpen() takes ownership of the IPP and clears the internal IPP FIFO. This
function always returns 0.
Return Values
0
Successful execution
MX800 SERIES PROGRAMMERS GUIDE
47
D EVICE D RIVERS
int ippClose(void)
int ippClose(void)
ippClose() releases ownership of the IPP. All unread data is lost. This function
always returns 0.
Return Values
0
48
MX800 SERIES PROGRAMMERS GUIDE
Successful execution
D EVICE D RIVERS
int ippRead(char *buffer, int size)
int ippRead(char *buffer, int size)
ippRead() transfers data from the IPP FIFO to the application data buffer.
Parameters
buffer
Pointer to the data area
size
Maximum number of bytes to read
Return Values
>0
Number of bytes returned in buffer
0
No data to read
EBADF
The task does not own the IPP.
Note on the PIN session timeout
One of the requirements for application independence in the Payment Card
Industry PED (PIN Entry Device) specification is that there is a default timeout for
PIN entry function calls from the application.
Consequently, the OS implements a PIN session timeout of 5 minutes. This value
is not modifiable. Applications that require a shorter timeout can issue a call to the
following in order to terminate the PIN session earlier:
ippTerminatePinEntry()
in IPP PIN Entry
iPS_CancelPIN()
in VSS PIN Entry
After expiration of the OS timeout,
in IPP PIN Entry
the IPP sends an <EOT> (0x04) character
in VSS PIN Entry
the iStatus value returned by the
iPS_GetPINResponse() function will be set to 0x0C.
Subsequent call to iPS_GetPINResponse() will return
a iStatus value of 0x01 meaning "PINpad idle" (i.e. not
in a PIN session).
MX800 SERIES PROGRAMMERS GUIDE
49
D EVICE D RIVERS
int ippWrite(char *buffer, int size)
int ippWrite(char *buffer, int size)
ippWrite() transfers a single complete IPP packet or a single character from
the buffer into the IPP. Incomplete, incorrectly framed packets, overly large, or
multiple packets in a single write are rejected. The valid start-of-packet characters
are STX and SI. The valid end-of-packet characters are ETX and SO. The only
single characters accepted are ACK, NAK, and EOT.
Parameters
buffer
Pointer to the data area
size
Maximum number of bytes to write
Return Values
NOTE
=size
The packet was transferred to the IPP.
-EBADF
The task does not own the IPP.
-EACCES
Too may PIN sessions requested during a short period of time. Try
again in a few seconds. See note below.
-EINVAL
Buffer is too large to be a valid IPP packet, the buffer pointer is not
valid, the single character was not one of [ACK, NACK, EOT], the
packet has a bad LRC, or the packet is not framed correctly.
PIN encryption is limited to one per 30 seconds on average to deter an
exhaustive PIN search.
The algorithm is best explained in terms of tokens in a bucket. An encryption
request is only accepted if there is a token in a bucket. A token is placed in the
bucket every 30 seconds, with a maximum of 30 tokens allowed in the bucket.
The number of tokens in the bucket is limited to 2 on power up.
Every time a PIN is entered, a token is removed from the bucket. If there is no
token in the bucket, the PIN entry request returns an error:
• IPP PIN entry : ippWrite returns -EACCES.
• VSS PIN entry : iPS_RequestPINEntry returns E_KM_ACCESS_DENIED.
This allows an average of one PIN encryption per 30 seconds, but over a long
period of time. The intention is that under normal use, PIN entry is not denied.
50
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
SetSecurePINDisplayParameters()
SetSecurePINDisplayParameters()
setSecurePINDisplayParameters() sets the hot spot table and registers
the callback function for the upcoming PIN session. This function must be called
each time prior to requesting a PIN session either through an IPP packet (Z60,
Z63 or Z69) or through a VeriShield Security Script API
(iPS_RequestPINEntry()).
Prototype
void setSecurePINDisplayParameters(struct touch_hs_s *hotspot_table, void
*callback);
The touch_hs_s structure is as follows:
struct touch_hotspot_info
{
unsigned short
x1; /* starting x of hotspot */
unsigned short
y1; /* starting y of hotspot */
unsigned short
x2; /* ending x of hotspot */
unsigned short
y2; /* ending y of hotspot */
char result; /* ASCII value to return */
charoptions; /* RESERVED */
};
The purpose of the hotspot table is to define active display regions. A rectangular
region is defined by two points using display pixel coordinates.
The first point is the upper left corner and the second point is the lower right
corner of the active region.
The values for x are 0 to 319 and 0 to 233 for y.
For example, if x1=0, y1=0 and x2=49, y2=49, then the hotspot region is 50 pixels
in both height and width with the top left corner positioned on the display at pixel
location (0,0).
The value defined in result is the ASCII value that is returned when the hotspot is
activated.
MX800 SERIES PROGRAMMERS GUIDE
51
D EVICE D RIVERS
SetSecurePINDisplayParameters()
For PIN entry, the following hotspots must be defined.
CODE
Key
===============================
0x30
0
0x31
1
0x32
2
0x33
3
0x34
4
0x35
5
0x36
6
0x37
7
0x38
8
0x39
9
0x0D
ENTER
Optional keys are:
CODE
Key
=======================================================
0x30
BACKSPACE
- 0x?2
0x31
CLEAR
- 0x?3
0x32
OTHER1 - Defines OTHER key #1
- 0x75
0x33
OTHER2 - Defines OTHER key #2
- 0x76
0x34
CANCEL - End PIN Session
- 0x70
NOTE
The order in which the hotspot entries are defined is not important.
struct touch_hs_s
{
short
num_hotspots; /* the number of active hotspots */
struct
touch_hotspot_info
};
52
MX800 SERIES PROGRAMMERS GUIDE
touch_spot[MAX_NUM_HOTSPOTS];
D EVICE D RIVERS
SetSecurePINDisplayParameters()
With the callback function, the PIN entry process can control the audio and visual
aspects as each key press is detected, and its prototype is:
void callback(char value);
Table 6
Value
Action
Lower nibble:
0x?1
A numeric key was pressed. A PIN digit has been added to the
internal PIN buffer. Application should display an <echo>
character.
0x?2
BACKSPACE key was pressed. A PIN digit has been removed
from the internal PIN buffer. Application should display a
<default> character (e.g. space, ‘-‘ or ‘_’) in place of the last
<echo> character.
0x?3
CLEAR key was pressed. All PIN digits have been removed from
the internal PIN buffer. Application should replace all <echo>
characters with <default> characters.
0x?5
Other key #1 was pressed. Pin Entry will be aborted as if the
CANCEL key was pressed. The application can use this code to
define an option key such as a CREDIT button.
0x?6
Other key #2 was pressed. Pin Entry will be aborted as if the
CANCEL key was pressed. The application can use this code to
define an option key such as a CREDIT button.
Upper nibble:
0x7?
Play “normal“ sound
0xF?
Play "error" sound. This is sent when:
• BACKSPACE or CLEAR is pressed when there is no PIN digit
in the internal buffer.
• A numeric key is pressed when there is already the maximum
number of PIN digits in the internal buffer.
• ENTER is pressed when there is not the minimum number of
PIN digits in the internal buffer.
Example 1: when a valid numeric entry is detected, the function will be called
once:
callback(0x71); /* Tell the application to play normal sound and to
display <echo> character */
Example 2: when the backspace key is detected:
callback(0x72); /* Tell the application to play normal sound and that
BACKSPACE was pressed*/
Example 3: when a key is pressed to clear the line when 3 inputs are entered:
callback(0x73); /* Tell the application to play normal sound and that
CLEAR was pressed*/
MX800 SERIES PROGRAMMERS GUIDE
53
D EVICE D RIVERS
int ippPinEntryStatus(int *count, int *lastNonNumericKey)
int ippPinEntryStatus(int *count, int *lastNonNumericKey)
ippPinEntryStatus() returns the PIN entry status, the number of PIN digits
currently in the internal PIN buffer and the code of the last non-numeric key
pressed.
count
Pointer to an integer that will receive the current count of
PIN digits in the internal buffer.
lastNonNumericKey
Pointer to an integer that will receive the code of the last
non-numeric key pressed. It will receive 0 if no new nonnumeric has been pressed since last call.
Return Values
1
PIN entry in progress
0
No PIN entry in progress
<0
Error
-EBADF The task does not own the IPP
54
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ippTerminatePinEntry()
ippTerminatePinEntry()
Ends the PIN session, for example, for a time-out.
Prototype
int ippTerminatePinEntry(void)
Return Values
0
successful
<0
Error
-EBADF The task does not own the IPP
MX800 SERIES PROGRAMMERS GUIDE
55
D EVICE D RIVERS
IPP Differences
IPP Differences
<SI>0103 PROM Checksum
The value of the checksum does not
match IPP7 since it is based on the Mx800
series terminal code.
<SI>0108 IPP ROM Version Number
The return packet is:
<SI>14IPP8 EMULvvv mm/
yy<SO>{LRC}
where vvv is the version number, mm is
the release month, and yy is the release
year.
<SI>13 Select Baud Rate
There is no IPP UART so setting the baud
rate does nothing. However, the baud rate
is stored in non-volatile memory so it can
be returned in diagnostics packets.
In platforms with an IPP chip, the
application must determine the baud rate
of the IPP by sending a test packet at all
possible baud rates until the IPP
responded with an ACK. In Mx800 series
of terminals, there is no UART so baud
rate mismatch is not possible. Applications
that try all possible baud rates will get an
ACK on the first test packet. This speeds
up applications slightly.
56
<SI>15 Set IPP6 Key Management Mode
Spain mode is not supported but switching
to Spain mode will erase keys. This is
included because some test programs
depend on this behavior to erase keys
between tests.
<SI>17 Set IPP7 Key Management Mode
SM mode is not supported but switching to
SM mode will erase keys. This is included
because some test programs depend on
this behavior to erase keys between tests.
<SI>02 Set master key
IPP7 has limited RAM so it can hold at
most three triple length keys. In Mx800
series of terminals, all ten key locations
can hold a single, double, or triple length
key. This is a enhancement planned for
IPP8 so it has been implemented because
extra code would be required to enforce
the IPP7 key limitations.
Multiple DUKPT
IPP7 supports one DUKPT engine. The
Mx800 series terminal IPP emulation
supports three DUKPT engine the same
way the IPP8 does.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
References
References
IPP Specification Software Technical Specification IPP7 VDN 06xxx
Software Technical Specification PP1000se & IPP8 VDN 23143
Appendix 15 of the Verix V Programmer’s Guide, VDN 23230
GISKE Specification Global Interoperable Secure Key Exchange Key Block Specification V2.3.
ACI Worldwide, HP Atalla, Diebold, Thales e-Security, VeriFone, Inc.
Security Module
VeriShield
Security Scripts
APIs
This section describes Mx800 series of terminals function calls related to security
and cryptography. The functions are divided into two groups:
•
Verishield Security Scripts (VSS) functions that are related to the use of
scripts to support custom key managements beyond the usual DUKPT and
M/S schemes.
•
Generic functions that provided services related to security and
cryptography such as DES, AES, SHA-1, RSA computation support, file
encryption support, random generation, tamper detection status, file
authentication and OS file upgrades.
The Mx800 series of terminals support the VeriShield Security Scripts concept as
implemented in the SC 5000 PINpad and Verix V family of terminals. Existing
scripts will run on the Mx800 series terminal platform without requiring any
modifications. All VSS-related functions listed below are defined in the header file
svcsec.h. Applications must link with the libvfisec.so library by using lvfisec.
Refer to the document VeriShield Security Scripts, VDN 21883 for detailed
information on how to implement a security script.
In its default configuration, the unit supports two key management schemes
through the IPP emulation: DUKPT and Master/Session. Those two schemes
should meet the needs of most of the customers and since they are hard coded,
no customization of the security module is required.
For customers who need more flexibility, the VeriShield Security Script feature
provides support for:
•
different key management schemes,
•
different PIN block formats such as PVV, CVV, IBM3624,
•
different encryption algorithms such as triple-DES, AES, RSA.
All the information is written in a script file (ASCII) using a .VSS extension. This
script is processed by a PC tool and converted into a downloadable file (*.VSO).
The download is protected by the PEDguard File Authentication (FA) module.
Therefore, the VeriShield Security Script file will have to be downloaded along
with its signature file generated with the VeriShield File Signature Tool.
MX800 SERIES PROGRAMMERS GUIDE
57
D EVICE D RIVERS
VeriShield Security Scripts APIs
Up to eight VeriShield Security Scripts can coexist in the unit at a same time. Each
script defines its independent key space and defines whether or not those keys
can be loaded using the generic key loading functions
(iPS_LoadMasterClearKey() and iPS_LoadMasterEncKey()).
The VSS Key Loading Key (VSS_KLK) is a double-length key. It is loaded in the
clear, but can also be loaded encrypted under its previous value. Since there is no
default value in the firmware for the VSS_KLK, the first time it must be loaded in
the clear. In that case, other keys in the unit will be erased, so it must be loaded
before all other keys. This must be done in a secure environment before
deployment.
The security script’s master keys can be loaded in the clear or encrypted under
VSS_KLK. Loading additional keys without erasing the keys previously loaded
must be done in encrypted form and therefore requires the knowledge of
VSS_KLK.
Each script defines its own set of keys and also defines if the keys may be loaded
with those generic key-loading functions. Some scripts may disallow their use and
implement custom macro commands for key loading.
58
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
iPS_DeleteKeys()
iPS_DeleteKeys()
This function deletes the specified set of keys.
Prototype
int iPS_DeleteKeys (unsigned long ulKeyType)
Parameters
ulKeyType
Indicates which set of keys are to be erased. Each bit corresponds
to a set of keys, meaning that several sets can be erased in one
function call.
DEL_SYSTEM
System key (VSS_KLK)
DEL_VSS0
Keys associated to VeriShield Security
Script loaded in slot #0
DEL_VSS1
Keys associated to VeriShield Security
Script loaded in slot #1
DEL_VSS2
Keys associated to VeriShield Security
Script loaded in slot #2
DEL_VSS3
Keys associated to VeriShield Security
Script loaded in slot #3
DEL_VSS4
Keys associated to VeriShield Security
Script loaded in slot #4
DEL_VSS5
Keys associated to VeriShield Security
Script loaded in slot #5
DEL_ALL
Delete all keys in the unit.
For instance, iPS_DeleteKeys(DEL_VSS2 | DEL_VSS3) deletes only keys
belonging to the Security Scripts loaded in slot #2 and #3.
Return Values
0
Successful execution
E_KM_SYSTEM_ERROR
MX800 SERIES PROGRAMMERS GUIDE
59
D EVICE D RIVERS
iPS_LoadSysClearKey()
iPS_LoadSysClearKey()
This function loads the VSS_KLK (i.e. system keys). The values are presented in
the clear. Before writing the new value of the key, all other keys in the terminal are
erased.
This function should be exclusively used in a secure environment.
Prototype
int iPS_LoadSysClearKey(unsigned char ucKeyID, unsigned char *
pucINKeyValue)
Parameters
ucKeyID
The key identifier.
0x00
pucINKeyValue
VSS_KLK (16 bytes)
16-byte buffer containing the clear-text key
Return Values
0
Successful execution
E_KM_NO_KEY_LOADED
VSS_KLK is absent. No encrypted loading
possible
E_KM_KEY_INTEGRITY_ERROR
VSS_KLK is corrupted
E_KM_SYSTEM_ERROR
60
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
iPS_LoadSysEncKey()
iPS_LoadSysEncKey()
This function loads the system keys. The new values must be presented
encrypted under the current value of VSS_KLK.
Contrary to the clear text loading, this encrypted loading does not erase all other
secrets in the unit.
An error code will be returned if the VSS_KLK is not present.
Prototype
int iPS_LoadSysEncKey(unsigned char ucKeyID, unsigned char *
pucINKeyValue)
Parameters
ucKeyID
The key identifier.
0x00
pucINKeyValue
VSS_KLK (16 bytes)
16-byte buffer containing the clear-text key
Return Values
0
Successful execution
E_KM_NO_KEY_LOADED
VSS_KLK is absent. No encrypted loading
possible
E_KM_KEY_INTEGRITY_ERROR
VSS_KLK is corrupted
E_KM_SYSTEM_ERROR
MX800 SERIES PROGRAMMERS GUIDE
61
D EVICE D RIVERS
iPS_LoadMasterClearKey()
iPS_LoadMasterClearKey()
This function loads the master key of the security script. The values are sent in the
clear, but must be all loaded in a same session. Before loading the first key after a
power cycle, all keys previously loaded (including the system keys) are erased.
This means that loading additional keys in a different session must be done in
encrypted form.
This function can be used to load the keys defined by the Security Scripts if the
option has not been disabled in the script.
This function should be exclusively used in a secure environment.
Prototype
int iPS_LoadMasterClearKey(unsigned char ucKeySetID,unsigned char
ucKeyID, unsigned char * pucINKeyValue)
Parameters
ucKeyID
The key set identifier.
00
Key set defined in VeriShield Security Script #0
01
Key set defined in VeriShield Security Script #1
...
07
ucKeyID
Key set defined in VeriShield Security Script #7
The key identifier.
Master key number / Key index in the selected set
pucINKeyValue
pointer to the 8-byte buffer containing the cleartext value Master
Key.
Return Values
0
Successful execution
E_KM_OUT_OF_RANGE
ucKeySetID or ucKeyID is out of range or
script is not loaded.
E_KM_FEATURE_DISABLED
Master/Session support disabled by a script
E_KM_SYSTEM_ERROR
62
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
iPS_LoadMasterEncKey()
iPS_LoadMasterEncKey()
This function loads the security script’s master keys without deleting the keys
already loaded. The new values must be presented encrypted under the current
value of VSS_KLK.
This function can be used to load the keys defined by the Security Scripts if the
option has not been disabled in the script.
An error code will be returned if the VSS_KLK is not present.
Prototype
int iPS_LoadMasterEncKey(unsigned char ucKeySetID, unsigned char
ucKeyID, unsigned char * pucINKeyValue)
Parameters
ucKeyID
The key set identifier.
00
Key set defined in VeriShield Security Script #0
01
Key set defined in VeriShield Security Script #1
...
Key set defined in VeriShield Security Script #7
07
ucKeyID
The key identifier.
Master key number / Key index in the selected set
pucINKeyValue
pointer to the 8-byte buffer containing the cleartext value Master
Key.
Return Values
0
Successful execution
E_KM_NO_KEY_LOADED
VSS_KLK is absent. No encrypted loading
possible
E_KM_KEY_INTEGRITY_ERROR
VSS_KLK is corrupted
E_KM_OUT_OF_RANGE
ucKeySetID or ucKeyID is out of range or
script is not loaded.
E_KM_FEATURE_DISABLED
Master/Session support disabled by a script
E_KM_SYSTEM_ERROR
MX800 SERIES PROGRAMMERS GUIDE
63
D EVICE D RIVERS
iPS_CheckMasterKey()
iPS_CheckMasterKey()
This function indicates whether a key is present in the specified location.
The Key Verification Code (KVC) argument is irrelevant in Mx800 series of
terminals because this function is used only for security script keys. The key may
be part of a double or triple length DES key, so for security reasons we cannot
return the KVC of a portion of the key.
Prototype
int iPS_CheckMasterKey(unsigned char ucKeySetID, unsigned char ucKeyID,
unsigned char * pucINKVC)
Parameters
ucKeyID
The key set identifier.
00
Key set defined in VeriShield Security Script #0
01
Key set defined in VeriShield Security Script #1
...
ucKeyID
07
Key set defined in VeriShield Security Script #7
08
PIN Master Key (Master/Session)
09
MAC Master Key (Master/Session)
The key identifier.
Master key number / Key index in the selected set
pucINKVC
not used
Return Values
0
Successful execution
E_KM_NO_KEY_LOADED
The key is not loaded
E_KM_KEY_INTEGRITY_ERROR
The key is corrupted
E_KM_OUT_OF_RANGE
ucKeySetID or ucKeyID is out of range
E_KM_SYSTEM_ERROR
64
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
SetSecurePINDisplayParameters()
SetSecurePINDisplayParameters()
setSecurePINDisplayParameters() sets the hot spot table and registers
the callback function for the upcoming PIN session. This function must be called
each time prior to requesting a PIN session either through an IPP packet (Z60,
Z63 or Z69) or through a VeriShield Security Script API
(iPS_RequestPINEntry()). See SetSecurePINDisplayParameters().
Prototype
void setSecurePINDisplayParameters(struct touch_hs_s *hotspot_table, void
*callback);
MX800 SERIES PROGRAMMERS GUIDE
65
D EVICE D RIVERS
iPS_SetPINParameter()
iPS_SetPINParameter()
This function configures several parameters for the upcoming VSS PIN session.
This function has not effect on IPP PIN sessions.
Prototype
int iPS_SetPINParameter( PINPARAMETER * psKeypadSetup)
Parameters
psKeypadSetup
typedef struct {
unsigned char ucMin,
unsigned char ucMax,
unsigned char ucEchoChar,
unsigned char ucDefChar,
unsigned char ucOption,
} PINPARAMETER;
where:
66
ucMin
Minimum number of PIN digits. It must be in the range [4..12].
ucMax
Maximum number of PIN digits. It must be at least equal to
Min but not greater than 12.
ucEchoChar
Not used on Mx800 series. The characters echoing PIN digits
are displayed by the
SetSecurePINDisplayParameters()’s callback
function.
ucDefChar
Not used on Mx800 series of terminals. The default field fill
characters are displayed using the
SetSecurePINDisplayParameters() callback function.
ucOption.bit0
=1 turns Auto Enter feature O
ucOption.bit1
=1 accepts NO PIN entry (pressing ENTER before any digit).
ucOption.bit2
RFU - Must be 0
ucOption.bit3
=1 makes the <CLEAR> key behave like a backspace key.
Only one digit is deleted instead of all the digits entered so
far.
ucOption.bit4
=1 cancels the PIN session when the <CLEAR> key is
pressed with no PIN in the buffer (The user has not entered
any PIN digit, or has already cleared out all the PIN digits).
When the PIN session is cancelled this way, the *piStatus
value returned by iPS_GetPINResponse is 0x0A.
ucOption.bit5..7
RFU - Must be 0
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
iPS_SetPINParameter()
Return Values
0
Successful execution
E_KM_OUT_OF_RANGE
At least one of the parameters is out of range
E_KM_SYSTEM_ERROR
MX800 SERIES PROGRAMMERS GUIDE
67
D EVICE D RIVERS
iPS_SelectPINAlgo()
iPS_SelectPINAlgo()
This function selects the PIN algorithm to be used during the next VSS PIN
session. The PIN algorithm cannot be changed during a PIN session
In the Mx800 series of terminals, the only supported mode is 0Bh for use with
VeriShield Security Scripts. In this mode, the PIN will be saved internally and will
be retrieved by a Security Script command for post-processing.
Prototype
int iPS_SelectPINAlgo(unsigned char ucPinFormat)
Parameters
ucPinFormat
0Bh
Store the PIN internally for post-processing by a
VeriShield Security Script command.
All other modes are not supported in the Mx800 series of
terminals.
Return Values
0
Successful execution
E_KM_OUT_OF_RANGE
ucPinFormat is out of range or unsupported
E_KM_BAD_SEQUENCE
PIN algorithm cannot be changed during a PIN
session
E_KM_SYSTEM_ERROR
68
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
iPS_RequestPINEntry()
iPS_RequestPINEntry()
This function initiates the PIN collection. Once the PIN entry is completed, the PIN
is formatted and encrypted according to the algorithm specified by the previous
function iPS_SelectPINAlgo. The encrypted PIN block is then placed in a
buffer and made available for the iPS_GetPINResponse function. This function
is not “blocking”, this allows the unit to perform other tasks while the customer is
entering his PIN.
Prototype
int iPS_RequestPINEntry( unsigned char cPANDataSize, unsigned char *
pucINPANData)
Parameters
ucPANDataSize
RFU – this parameter is ignored in Mx800 series of
terminals.
pucINPANData
RFU – this parameter is ignored in Mx800 series of
terminals.
Return Values
0
Successful execution
E_KM_ACCESS_DENIED
You requested too many PIN sessions in a short
period of time. Try again in few seconds. See
Note on the PIN session timeout.
E_KM_BAD_SEQUENCE
A PIN session is already started
E_KM_SYSTEM_ERROR
MX800 SERIES PROGRAMMERS GUIDE
69
D EVICE D RIVERS
iPS_GetPINResponse()
iPS_GetPINResponse()
This function checks the status of the PIN session. It will typically be used by the
application in a loop to poll the system until the PIN session ends. The information
returned by this function during the PIN session can be used in conjunction with a
timer to implement an inter-character timeout as required in certain countries The
functions returns the number of PIN digits entered and the last non-numeric
pressed.
Prototype
int ippGetPINResponse (int * piStatus, PINRESULT * pOUTData)
Parameters
piStatus
70
MX800 SERIES PROGRAMMERS GUIDE
OK
(0x00)
Done. Data contains the result of the comparison/
encryption.
0x01
Unit is idle
0x02
Collecting PIN
0x05
Aborted by user: The <CANCEL> key has been pressed.
0x06
NO PIN entered (Only if this option is turned on)
0x0A
Aborted by user: The <CLEAR> key has been pressed
with no PIN digit in the buffer (The user had not entered
any PIN digit, or had already cleared out all the PIN
digits). This value can be obtained only if ucOption.bit4
has been set using function ippSetPINParameters().
0x0C
The PIN session timed out. See Note on the PIN session
timeout.
D EVICE D RIVERS
iPS_GetPINResponse()
pOUTData
Pointer to an object of the following type:
typedef struct {
unsigned char nbPinDigits;
unsigned char encPinBlock[8];
} PINRESULT;
This structure will return different information depending on the status of
the PIN session. If *piStatus is equal to:
OK(0x00)
0x01
Done.
pOUTData
->nbPinDigits
Number of PIN digits
entered (PIN length).
pOUTData
->encPinBlock
contains no relevant
information.
Unit is idle
pOUTData
->encPinBlock
0x02:
contains no relevant
information.
Collecting PIN
pOUTData
->nbPinDigits
Number of PIN digits entered
so far.
pOUTData
->encPinBlock
The first byte of the buffer
contains the value of the last
non-numeric key pressed.
Values can be:
• 0x00: No non-numeric key
has been pressed since the
last call to
iPS_GetPINResponse().
• 0x0D: <ENTER> key
• 0x0D: <CLEAR> key
• 0xF9: The user attempted to
enter one more PIN digit
than the maximum number
allowed (ucMax)
• Any other non-numeric key
value defined in the hotspot
table.
MX800 SERIES PROGRAMMERS GUIDE
71
D EVICE D RIVERS
iPS_GetPINResponse()
0x05: or
Aborted by user
0x0A:
pOUTData
->nbPinDigits
0
pOUTData
The first byte of the buffer
contains the value of the last
non-numeric key pressed.
Values can be:
->encPinBlock
• 0x00: If the last key pressed
was a numeric key (PIN
digit).
• 0x1B: <CANCEL> key
• 0x08: <CLEAR> key
0x06
NO PIN entered (Only if this option is turned on)
- pOUT Data contains no relevant information.
0x0C
Timed out
- pOUT Data contains no relevant information.
Return Values
0
E_KM_SYSTEM_ERROR
72
MX800 SERIES PROGRAMMERS GUIDE
Successful execution
D EVICE D RIVERS
iPS_CancelPIN()
iPS_CancelPIN()
This function cancels the PIN processing.
Prototype
int iPS_CancelPIN(void)
Return Values
0
Successful execution
E_KM_SYSTEM_ERROR
MX800 SERIES PROGRAMMERS GUIDE
73
D EVICE D RIVERS
iPS_InstallScript()
iPS_InstallScript()
This function authenticates and installs VeriShield Security Script files in the
system.
The function attempts to authenticate all .VSO files in the vss/ subdirectory in the
current user’s home directory. Files must have been signed with a signer
certificate that has security script signing capabilities. The associated signature
file (.p7s) must reside in the same directory. The search for .VSO and .p7S
extension is not case sensitive.
Internally the system performs two attempts to authenticate each file. If after the
first attempt the file is not authenticated, the system searches the crt/
subdirectory in the current user’s home directory for .CRT files. It tries to add each
certificate file to the system certificate tree. Then a second attempt to authenticate
the file is performed.
Upon successful authentication, the system changes the owner of the .vso file and
installs it in the unit. The change of owner prevents further modification of the file
(The user can still delete the file). The function performs several verifications on
the script file during the install process, such as the compatibility between the
version of the tool that generated the file and the version of the internal script
interpreter.
This function always returns 0. The application can call
iPS_GetScriptStatus() to check the installation of the script file.
Prototype
int iPS_InstallScript(void)
Return Values
0
74
MX800 SERIES PROGRAMMERS GUIDE
Always
D EVICE D RIVERS
iPS_GetScriptStatus()
iPS_GetScriptStatus()
This functions checks if a VeriShield Security Script file is installed in the specified
script location and if it is the case, returns the name of the script.
Prototype
int ippGetScriptStatus(unsigned char ucScriptNumber, unsigned char
*pucINName )
Parameters.
ucScriptNumber
Script number. Range [0..7]
pucINName
The pointer to the application buffer where the 8-character name
of the VeriShield Security Script value will be transferred.
Return Values
0
Successful execution
E_VS_SCRIPT_NOT_LOADED
This script is not installed or not accessible from the
current application group.
MX800 SERIES PROGRAMMERS GUIDE
75
D EVICE D RIVERS
iPS_UninstallScript()
iPS_UninstallScript()
This function uninstalls the specified VeriShield Security Script from the unit. The
associated keys are deleted. The script file remains in the file system and can be
installed again later on.
Prototype
int ippGetScriptStatus(unsigned char ucScriptNumber)
Parameters.
ucScriptNumber
Script number. Range [0..7]
Return Values
0
Successful execution
E_VS_SCRIPT_NOT_LOADED
This script is not installed, not authenticated, or not
accessible from the current application group.
E_VS_SYSTEM_ERROR
76
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
iPS_ExecuteScript()
iPS_ExecuteScript()
This function spawns the execution of a given macro from a given loaded
VeriShield Security Script.
Prototype
int iPS_ExecuteScript(unsigned char ucScriptNumber, unsigned char
ucMacroID, unsigned short usINDataSize, unsigmed char * pucINData unsigned
short usMaximumOUTDataSize, unsigned short *pusOUTDataSize, unsigmed char
* pucOUTData)
Parameters.
ucScriptNumber
Script number. Range [0..7]
unsigned char ucMacroID
Number of the macro function to be executed.
usINDataSize
The size of the input data (in bytes).
pucINData
The pointer to the buffer containing the input data.
usMaximumOUTDataSize
The maximum size of the output data. This typically
will be the size of the output buffer.
pusOUTDataSize
Pointer to number of bytes returned by the macro in
the output buffer.
pucOUTData
The pointer to the output buffer. The number of
bytes returned in the output buffer is specified by
pusOUTDataSize. If the macro is returns more
data than the output buffer can contain, an error
E_VS_BAD_LENGTH is returned and nothing is
copied into the output buffer.
MX800 SERIES PROGRAMMERS GUIDE
77
D EVICE D RIVERS
iPS_ExecuteScript()
Return Values
0
Successful execution
Value in the range [0...255]
Macro execution error - The returned value is the
value of the opcode that caused the execution
error. Refer to VDN 21883 for the list of opcodes.
E_VS_SCRIPT_NOT_LOADED
This script is not loaded, not authenticated, or not
accessible from the current application group.
E_VS_MACRO_NOT_EXIST
This macro does not exist in this script.
E_VS_BAD_LENGTH
usINDataSize is less than the value expected by
the macro or usMaximumOUTDataSize is less
than the number of bytes that the macro is
attempting to return.
E_VS_BAD_CHAINING
Bad sequence of macro (see chaining mechanism
in VDN 25883).
E_VS_SYSTEM_ERROR
78
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
pcPS_GetVSSVersion()
pcPS_GetVSSVersion()
This function returns the version of the VeriShield Security Script interpreter.
Prototype
char* pcPS_GetVSSVersion (void)
Parameters.
ucScriptNumbe
r
Script number. Range [0..7]
Return Values
It returns a char pointer to the following NULL terminated string:
"PSVSSvX.Y"
X
Major version
Y
Minor version
MX800 SERIES PROGRAMMERS GUIDE
79
D EVICE D RIVERS
Security Services APIs
Security
Services APIs
80
The security device (/DEV/IPP) need not be opened to use the functions listed
below. All security services functions listed below are defined in the header file
svcsec.h. Applications must link with the libvfisec.so library by using
lvfisec.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
cryptoWrite()
cryptoWrite()
The File Encryption feature can be used in order to guarantee that the file content
will be lost if the unit is tampered with. The file is encrypted with a variant of a key
that is erased from the terminal in case of attack, making impossible to recover
the content of the encrypted file. The key is unique per terminal and is not known
outside the cryptographic unit of the terminal.
This feature can be used, for instance, when tamper detection must cause the
deletion the transaction batch file.
cryptoWrite() encrypts and writes count bytes of data from buffer to the open
file associated with handle. It returns the number of bytes actually written. All
writes must be done going forward in the file because data at one location affect
the decryption of the data further in the file. Another consequence is that the file
must be opened for both reading and writing (i.e. if the file was opened with flag
O_WRONLY set, the function returns –1 and errno set to EBADF).
Prototype
int cryptoWrite (int handle, const char *buffer, int count)
Parameters
handle
File handle
buffer
Pointer to the buffer holding the input data
count
Number of byes to write
Return Values
0
Successful execution
1
File Error, errno is set accordingly.
<1
System Error
MX800 SERIES PROGRAMMERS GUIDE
81
D EVICE D RIVERS
cryptoRead()
cryptoRead()
crypto_read reads a maximum of count bytes of encrypted data from the open
file associated with handle, decrypts the data and stores the result in buffer. It
returns the number of bytes actually read, which may be less than count if fewer
bytes are available.
Prototype
int cryptoRead (int handle, char *buffer, int count)
Parameters
handle
File handle
buffer
Pointer to the buffer holding the input data
count
Maximum number of byes to write
Return Values
82
0
Successful execution
1
File Error, errno is set accordingly.
<1
System Error
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
rsa_calc()
rsa_calc()
This function performs a public key RSA computation. It supports key lengths from
9 bits up to 2048 bits and exponent values that can be written as (2exp+1), for
instance 2, 3, 65537.
Prototype
int rsa_calc (unsigned char * msg,
unsigned char * mod,
int wds count, int exp,
unsigned char * result);
Parameters
msg
Pointer to the buffer holding the input data
mod
Pointer to the buffer holding the modulus
Note:
If count is odd, the first byte (leftmost) cannot be null, if count is
even the first two bytes (leftmost) cannot be both null. If it’s the
case, the function returns an error.
count
Length of the modulus and input data in bytes. Minimum 3. Max 256.
exp
Code for exponent: actual exponent is 2exp+1.
For instance, set exp to 17 for exponent 65537.
result
Pointer to the buffer receiving the result on exit.
Return Values
0
Successful execution
<0
Error - Invalid parameter
MX800 SERIES PROGRAMMERS GUIDE
83
D EVICE D RIVERS
SHA1()
SHA1()
This function performs a SHA-1 computation as described in FIPS PUB 180-2. It
returns a 20-byte message digest. Due to the underlying messaging interface, it
can process a maximum of 1024 bytes per call.
Prototype
int SHA1 (unsigned char * int option, unsigned char * input_buffer,
unsigned long nb, unsigned char * sha20)
Parameters
option
SHA1INIT
First call. The SHA-1 engine is initialized before
processing the data. No digest is returned.
SHA1BUFF
Intermediate call. It feeds the SHA-1 engine more
data. No digest is returned.
SHA1TERM
Final call. The 20-byte digest is returned after the
data is processed.
SHA1ALL
One-step operation combining all the options
above.
input_buffer
Pointer to the input buffer holding the message to be processed.
nb
Number of bytes in the buffer. Maximum value is 1024.
sha20
Pointer to the 20-byte buffer where the message digest will be
transferred.
Return Values
84
0
Successful execution
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
DES()
DES()
This function performs DES, DESX and Triple-DES computations. The operation
type and key length are specified using the parameter ucDeaOption.
Prototype
int DES (unsigned char ucDeaOption,
unsigned char *pucDeaKey8N,
unsigned char *pucInputData,
unsigned char *pucOutputData)
Parameters
ucDeaOption
Algorithm
DESX1KE(02h)
DEAX encryption with single-length key
DESX1KD(03h)
DEAX encryption with single-length key
DESX2KE(04h)
DEAX encryption with double-length key
DESX2KD(05h)
DEAX encryption with double-length key
DESX3KE(06h)
DEAX encryption with triple-length key
DESX3KD(07h)
DEAX encryption with triple-length key
DESE(08h)
DEA encryption with single-length key
DESD(09h)
DEA encryption with single-length key
TDES2KE(0Ch)
TDEA encryption with double-length key
TDES2KD(0Dh)
TDEA encryption with double-length key
TDES3KE(0Eh)
TDEA encryption with triple-length key
TDES3KD(0Fh)
TDEA encryption with triple-length key
pucDeaKey8N
Pointer to 8N-byte key block (N=1, 2 or 3)
pucInputData
Pointer to 8-byte input block
pucOutputDat
a
Pointer to 8-byte output block
Return Values
0
Successful execution
Less than 0
Error
MX800 SERIES PROGRAMMERS GUIDE
85
D EVICE D RIVERS
AES()
AES()
This function performs AES computations on 128-bit data block. The operation
type and key length are specified using the parameter ucAesOption.
Prototype
int AES (unsigned char ucAesOption,
unsigned char *pucAesKey8N,
unsigned char *pucInputData,
unsigned char *pucOutputData)
Parameters
ucAesOption
Algorithm
AES128E (04h)
AES encryption using a 128-bit key
AES128D (05h)
AES decryption using a 128-bit key
AES192E (06h)
AES encryption using a 192-bit key
AES192D (07h)
AES decryption using a 192-bit key
AES256E (08h)
AES encryption using a 256-bit key
AES256D (09h)
AES decryption using a 256-bit key
pucAesKey8N
Pointer to 8N-byte key block (N=1, 2 or 3)
pucInputData
Pointer to 16-byte input block
pucOutputData
Pointer to 16-byte output block
Return Values
86
0
Successful execution
Less than 0
Error
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
generateRandom()
generateRandom()
This function returns an 8-byte random value.
Prototype
int generateRandom (char*random8)
Parameters
random8
Pointer to the 8-byte buffer where the random value is
transferred.
Return Values
0
Successful execution
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
87
D EVICE D RIVERS
isAttacked()
isAttacked()
This function indicates if an attack occurred, causing the loss of the transaction
keys and/or encrypted files. It returns 0 if no attack occurred since the last key
loading or file encryption, otherwise, a value of 1 is returned. It also returns 1 if the
unit has never been loaded with a key and no encrypted file has been written.
Prototype
int isAttacked (void)
Return Values
88
0
No attack has occurred since keys have been loaded.
1
An attack has occurred. Keys and encrypted file have been lost.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
secVersion()
secVersion()
This function returns the version number strings for the security module and the
security library in the form “xx.yy.zz”.
Prototype
int secVersion(char *pchModVersion, char *pchLibVersion)
Parameters
pchModVersion
Pointer to the 9-byte buffer receiving the security module
version number.
Return Values
0
Successful execution
Less than 0
Error
MX800 SERIES PROGRAMMERS GUIDE
89
D EVICE D RIVERS
authFile()
authFile()
This function checks if the specified file is authenticated.
Internally, the function performs two attempts to authenticate the file. If after the
first attempt, the file is not authenticated, the system searches for .CRT files in the
crt/ subdirectory in the current user home directory. It tries to add each
certificate file to the system certificate tree. Then a second attempt to authenticate
the specified file is performed.
Prototype
int authFile(const char *filename)
Parameters
filename
Pointer to the name of file to authenticate.
Return Values
90
0
File is authenticated
<0
File failed authentication
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
loadOSFiles()
loadOSFiles()
This function attempts to authenticate all files in the os/ subdirectory in the current
user home directory. Files must have been signed with an OS signer certificate.
Internally the function performs two attempts to authenticate each file. If after the
first attempt the file is not authenticated, the system searches for .CRT files in the
crt/ subdirectory in the current user home directory. It tries to add each
certificate file to the system certificate tree. Then a second attempt to authenticate
the file is performed.
Upon successful authentication, the file and its signature file are moved into the
system directory according to its location in the user os/ subdirectory. For
instance, the file /home/usr1/os/lib/modules/DELTA.SCM and its signature
file /home/usr1/os/lib/modules/DELTA.SCM.p7s will be moved to system
directory /lib/modules/.
Prototype
int loadOSFiles(void)
Return Values
0
Successful execution
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
91
D EVICE D RIVERS
Delta Smartcard Interface / CardSlot
Delta Smartcard
Interface /
CardSlot
The VeriFone Delta Smartcard module will be used to interface the ARM CPU to
the customer smartcard and SAMs. For more details on Smartcard APIs, refer to
Serial Ports and
Protocols
The Linux operating system is divided into two spaces, the kernel space and the
user space. The kernel space is used for device drivers that must interact closely
with the hardware. This interaction includes handling interrupts, precise timing,
and hardware interfaces that require bit flipping. The user space code is easier to
debug, maintain, and provides superior protection from bugs. For these reasons,
the Mx CardSlot Library Programmer’s Guide, VDN 23992.
USER SPACE
the Mx800 series of terminals will perform most of its protocol processing in
libraries that reside in user space. Kernel drivers will implement the standard
open/close/read/write functions needed by the protocol libraries. The following
diagram is an overview of the three UARTs available on the multiport cable.
Feature C Protocol
(VISA layer)
Packet Mode Protocol
LINUX KERNEL
Character Device
Wrenchman Coprocessor
Driver (SPI) stty3
HARDWARE
UART Driver
stty1, stty2
Samsung ARM9 CPU
COM1
RTS/CTS,
DCD
Figure 1
92
MX800 SERIES PROGRAMMERS GUIDE
COM2
RTS/CTS,
DTR, DCD
LINUX operating system structure
Wrenchman
Silicon Labs
Communication
Coprocessor
COM3
RTS/CTS
D EVICE D RIVERS
Serial Communication Control Structure
Serial
Communication
Control
Structure
The following are the structures defined for configuring serial ports on the Mx800
series of terminals. They contain all the necessary elements for defining the ports
into the different modes that each of them support.
typedef struct{
short status;
short comm_handle;
short visa_sel; /* 0 - visa not selected, 1 - visa selected */
int port;
void (*pEcrReceive) (void); /* ecr rx callback for application */
struct Opn_Blk openBlock;
}ECR_INFO;
/* --------------------- Packet Defines --------------------------*/
typedef struct
unsigned char stx_char;
unsigned char etx_char;
unsigned char count;
int max_pkt;
void (*pPktHandler) (char , int); /* rx callback for packet mode
*/
} packet_parm_t;
/* --------------------- ECR tailgate Defines ---------------------*/
typedef struct
{unsigned char poll_addr;
} ECRtailgate_parm_t;
/* -------------------- Open Block Structure ----------------------*/
struct Opn_Blk
{unsigned int rate;
unsigned int format;
unsigned int protocol;
unsigned int parameter;
packet_parm_t packet_parms;
union {
ECRtailgate_parm_t ECRtailgate_parms;
} trailer;
};
The structures defined above comprise the necessary settings needed to
configure a serial port for RS232/485, Tailgate, Visa, Packet mode or other
protocols.
Protocol The main structure is the Open Block structure (Opn_Blk), which contains an
element called protocol. The protocol variable indicates what mode the port
should be configured for and further defines what other fields are applicable for
that mode.
MX800 SERIES PROGRAMMERS GUIDE
93
D EVICE D RIVERS
Packet Mode
Trailer The value contained in the trailer field depends on the defined protocol.
Because the trailer field consists of different types, only one type is valid at
any time. If tailgate mode is selected as the protocol, then the
ECRtailgate_parms will be the valid field. All future mutually exclusive
protocols will be defined here.
Packet_parms The packet_parms field is used for Packet Mode. It is defined outside the trailer
field as it is valid for different types of protocols to work in conjunction with packet
mode. A serial port may be configured for RS232 packet mode or as tailgate with
Visa protocol enabled which uses packet mode. This structure must be filled in
prior to calling startPktMode().
Packet Mode
Packet mode protocol manages packet-based protocols over any of the serial
ports. It supports the definition of a packet start and end character as well as error
detection characters (such as LRC/CRC). The packet mode library will buffer
incoming data until a complete packet is received. Once a complete packet is in
the receive buffer, the library will call a callback function to deliver the message to
the application. Outgoing message must be fully defined including start, end, and
error detection characters before writing to the packet library.
Packet mode protocol has been implemented as a static library named:
libvfiprot.a
94
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
Initialize Packet Mode
Initialize Packet Mode
Prior to reading or writing messages in packet mode, startPktMode() must be
called to configure the packet mode parameters. The packet_parms structure
(in struct Opn_Blk) must be correctly completed before calling
StartPktMode(). Opening the ECR using ecrOpen() is automatically set. If
packet mode is required on a port that is not opened with ecrOpen(), then the
application is required to fill in this structure.
/* --------------------- Packet Defines --------------------------*/
typedef struct
{
unsigned char stx_char; // Define start character
unsigned char etx_char; // Define end character
unsigned char count; // Define number of characters for error
check
int max_pkt; // Maximum message length in bytes
void (*pPktHandler) (char *, int); // RX message callback function
} packet_parm_t;
Prototype
int startPktMode(int hCom, struct Opn_Blk *openBlock);
Parameters
hCom
Handle of a previously opened serial port
openBlock
Serial communication control structure
Return Values
0
Successful execution
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
95
D EVICE D RIVERS
endPktMode()
endPktMode()
endPktMode() is used to free packet mode buffers once a packet mode session
is completed.
Prototype
void endPktMode(void);
96
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
Receiving Packet Messages
Receiving Packet Messages
Calling startPktMode() configures a callback function that will be executed
upon receiving a message.
Prototype
void packetRX(char * rxBuffer, int rxLength);
Parameters
rxBuffer
Pointer to a char buffer with received message
rxLength
Length of received message
MX800 SERIES PROGRAMMERS GUIDE
97
D EVICE D RIVERS
COM Ports on the M x 800 series of Terminals
COM Ports on
the Mx800 series
of Terminals
There are 4 COM ports on the Mx800 series of terminals labeled COM1 – COM4
plus an additional USB device serial port, COM5. They are referenced in software
as the following devices:
•
COM1 = /dev/ttySAC0
•
COM2 = /dev/ttySAC1
•
COM3 = /dev/ttyWR0
•
COM4 = /dev/ttySAC2
•
COM5 = /dev/ttygser
Some ports are optional depending on the specific Mx800 series of terminals
configuration. All ports can be used as a general RS232 port which can be
configured for different baud rates, character sizes, parity, and stop bits using
either standard Linux calls or the svcSetOpenBlock() call. They can also be
configured to work in character or packet mode, such as the Visa protocol, and
with or without flow control if that port supports it. The baud rates supported on all
ports are: 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. COM5 is a
special USB port that acts as a serial port and baud rate settings do not apply.
Unlike other VeriFone terminals, the serial port devices can be opened for control
by more than one process at a time. To prevent others from using the port at the
same time, use the following ioctl() calls to have exclusive access to the
opened port.
TIOCEXCL
Put the ttySACx into exclusive mode, where no further open()
operations are permitted. They will fail with EBUSY, except for
root.
TIOCNXCL
Disable exclusive mode.
Due to the limitations of the ARM processor, the Mx800 series of terminals COM
ports do not support the detection of parity errors and BREAK conditions.
It is the responsibility of the application to know which control and status lines are
supported by each COM port, as stated below. Control lines not supported by the
hardware will report the last status set by the application, and unsupported status
lines will report as being asserted.
COM1 COM1, or device /dev/ttySAC0, supports the following hardware lines: RTS,
CTS, and DCD.
The RTS/CTS flow control uses the Samsung S3C2410 UART’s Auto Flow
Control. In this mode, the UART will control the RTS line automatically, and cannot
be set by the application.
98
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
COM Ports on the M x 800 series of Terminals
COM2 COM2, or device /dev/ttySAC1, supports the following hardware lines: RTS,
CTS, DTR, and DCD.
The RTS/CTS flow control is under the device driver control, and the RTS line
must be controlled by the application.
COM3 COM3, or device /dev/ttyWR0 has the additional ability to communicate with an
Electronic Cash Register utilizing the tailgate protocol. This is the only port that
can communicate using this protocol. As shown in the architecture diagram
above, COM3 is directly connected to another hardware device called a
Wrenchman F331 8051 device controller, which handles all of the tailgate
protocol. A special driver allows this port to function either as a generic RS232,
RS485, or SIO Tailgate device. It also allows special ioctl() commands to be
issued for configuration and obtaining information on the status of the port. Ioctl’s
for this port are also available with the SVC COM3 service functions and are
discussed later in this document.
NOTE
Due to limitations in the firmware, this port does not support “true” full duplex
mode and as a consequence, NO full duplex protocols should be used with this
port. If this port is connected to a full duplex device and a full duplex protocol is
used in communication, this port may not be able to transmit and received data
without any loss, depending on the amount of data and baud rate it is configured
for. If this port is connected to any device that is capable of full duplex mode but
uses a half duplex protocol in its communication (i.e. packet is sent, waits for
response such as Ack/Nak, packet is sent), then there is no problem of data loss.
Protocols and devices that do not use full duplex and can safely be connected to
this port are: ECR, Zontalk, DL, DL5, DDL, most COM devices, printers, and
check readers.
NOTE
All configuration of baud rates (listed in COM Ports on the Mx800 series of
Terminals section), character sizes, parity and stop bits are supported except for
7 bits, No Parity, and 1 stop bit (7N1). This specific setting is not supported on
COM3. If it is desired to have the port configured for 7 bit character sizes with no
parity bit, then 2 stop bits (7N2) MUST be used instead.
MX800 SERIES PROGRAMMERS GUIDE
99
D EVICE D RIVERS
IBM ECR Tailgate & Feature C
COM4 - Optional I/O COM4, or device /dev/ttySAC2, is available only to the I/O Module and is
Module dedicated for RFID capability. A physical serial port connector maybe available as
a future enhancement to this module so that it may be connected to a variety of
devices.
COM5 COM5, or device /dev/ttygser, is actually a serial device that transmits and
receives data over a USB cable using the USB “Gadget” technology. This allows
the Mx800 series of terminals to act like any other serial port when connected to a
USB host port. The Mx800 series of terminals can be configured to become a USB
device that can emulate being a serial port and be connected to a USB host. The
Mx800 series terminal’s USB device cable can be connected to a Windows or
Linux based OS machine and look like another COM port to that machine. This
allows serial transfer of data back and forth between the Mx800 series terminal
and a PC.
Serial Gadget uses the “bulk” transfer method as defined in USB 2.0 specification.
This transfer method is fixed to a 512 byte maximum packet size. The user/
application should be aware of this limitation when using this COM port to transfer
data making sure that any remote communication program does not set its packet
size greater than this maximum size.
IBM ECR
Tailgate &
Feature C
100
The succeeding section lists the IBM ECR APIs used both in Tailgate and Feature
C mode.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrOpen
ecrOpen
This function opens the port and initializes it according to the I4683 variable. If the
visa_sel is non zero, the port is configured for VISA 2 processing. If port_name
is specified, then it overrides the setting in the L4683 environment variable. If
port_name is not specified, then a null terminated string (“”) should be passed and
the value in the L4683 environment variable will be used. The function returns the
handle to the port. or a negative value upon error and errno set.
Prototype
short hEcr = ecrOpen(char *port_name, short visa_sel);
Return Values
Negative return values are defined as follows:
-0
I4683 environment variable NOT found.
erno = -EINVAL
-1
Device driver not installed
errno = -ENXIO
-2
L4683 environment variable NOT found.
erno = -EINVAL
-3
Invalid port number in L4683.
erno = -EINVAL
-4
Invalid port name argument.
erno = -EINVAL
-5
Invalid L4683 environment variable length.
erno = -EINVAL
-6
Invalid I4683 slot specified or not initialized.
erno = -EBADSLT
-7
Visa protocol NOT started.
erno = -EPROTO
-8
Initialization failed of Polling semaphore.
erno = -EPERM
MX800 SERIES PROGRAMMERS GUIDE
101
D EVICE D RIVERS
ecrRead
ecrRead
Prototype
short bytes_read = ecrRead(char *buffer, short size);
Size is the maximum number of bytes to read, and buffer is a pointer to the data
area. Each invocation of ecrRead() will transfer data from the port into the
buffer, and return the number of bytes actually read or a negative value if an error
occurred.
102
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrReadReject
ecrReadReject
Prototype
short bytes_read = ecrReadReject(char *buffer, short size);
Size is the maximum number of bytes to read, and buffer is a pointer to the data
area. Each invocation of ecrReadReject() will transfer the rejected data from
ecrWrite() into the buffer, and return the number of bytes actually read or zero
if no data is available.
MX800 SERIES PROGRAMMERS GUIDE
103
D EVICE D RIVERS
ecrStatus
ecrStatus
The information returned from ecrStatus() varies depending on whether the
port is in Tailgate or Feature C mode and if VISA is enabled.
If in Tailgate mode and VISA is enabled:
Prototype
struct vficomErrCounts *result = ecrStatus(int *buf);
Copy current status information to caller’s 4-integer buffer.
1st
Input messages pending
A value of 0 means no message pending.
A value of greater than 0 means that a message is pending.
2nd
The number of bytes available (free) in the output buffer.
3rd
Indicates if ECR is online. A non-zero value indicates the ECR is
online (default is 0x37). A value of zero indicates ECR is offline.
4th
Status of ecrWrite() message:
0
message ACKed
1
message pending
2
message rejected
Return Values
The result return code is a pointer to vficomErrCounts structure which is
defined as:
struct vficomErrCounts {
int frame_err;
int over_err;
int parity_err;
};
The pointer to this structure will contain the error counts for the port described by
the file descriptor passed into the function. The error counts provided are for
framing, overrun and parity errors detected for that port. The counts provided are
always total errors counted for that port since it was opened which allows the
application to track if any new errors were detected for that port since the last time
this function was called.
If in Tailgate mode and VISA is not enabled:
104
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrStatus
Prototype
struct vficomErrCounts *result = ecrStatus(int*buf);
Copy current status information to caller’s 4-byte buffer.
1st
The number of bytes pending in the input buffer.
2nd
The number of bytes available (free) in the output buffer.
3rd
Indicates if ECR is online. A non-zero value indicates the ECR is
online (default is 0x37). A value of zero indicates ECR is offline.
Return Values
The result return code is a pointer to vficomErrCounts structure which is
defined as:
struct vficomErrCounts {
int frame_err;
int over_err;
int parity_err;
};
The pointer to this structure will contain the error counts for the port described by
the file descriptor passed into the function. The error counts provided are for
framing, overrun and parity errors detected for that port. The counts provided are
always total errors counted for that port since it was opened which allows the
application to track if any new errors were detected for that port since the last time
this function was called.
If in Feature C mode and VISA is enabled:
Prototype
struct vficomErrCounts *result=ecrStatus(int*buf);
MX800 SERIES PROGRAMMERS GUIDE
105
D EVICE D RIVERS
ecrStatus
Copy current status information to caller’s 4-integer buffer.
Input messages pending
1st
A value of 0 means no pending message.
A value of greater than 0 means that a message is pending.
2nd
The number of bytes available (free) in the output buffer.
3rd
Current signal information for port:
(all bits for corresponding signals are set if hardware supports
signal for that port and the signal is detected to be asserted.
Otherwise bit is not set.)
0x80
set if DTR detected
0x40
set if RTS detected
0x20
set if CTS is detected
0x10
set if Ring Indicator is present
0x08
set if Carrier Detect (CD)
0x04
set if DSR detected
0x02
Reserved
0x01
Reserved
Status of ecrWrite() message:
4th
0
message ACKed
1
message pending
2
message rejected
Return Values
The result return code is a pointer to vficomErrCounts structure which is
defined as:
struct vficomErrCounts {
int frame_err;
int over_err;
int parity_err;
};
The pointer to this structure will contain the error counts for the port described by
the file descriptor passed into the function. The error counts provided are for
framing, overrun and parity errors detected for that port. They counts provided are
always total errors counted for that port since it was opened which allows the
application to track if any new errors were detected for that port since the last time
this function was called.
106
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrStatus
If in Feature C mode and VISA is not enabled:
Prototype
struct vficomErrCounts *result = ecrStatus(int*buf);
Copy current status information to caller’s 4-byte buffer.
1st
The number of bytes pending in the input buffer.
2nd
The number of free bytes available in the output buffer.
3rd
Current signal information for port:
(all bits for corresponding signals are set if hardware supports
signal for that port and the signal is detected to be asserted.
Otherwise bit is not set.)
0x80
set if DTR detected
0x40
set if RTS detected
0x20
set if CTS detected
0x10
set if Ring Indicator is present
0x08
set if Carrier Detect (CD) present
0x04
set if DSR detected
0x02
Reserved
0x01
Reserved
MX800 SERIES PROGRAMMERS GUIDE
107
D EVICE D RIVERS
ecrStatus
Return Values
The result return code is a pointer to vficomErrCounts structure which is
defined as:
struct vficomErrCounts {
int frame_err;
int over_err;
int parity_err;
};
The pointer to this structure will contain the error counts for the port described by
the file descriptor passed into the function. The error counts provided are for
framing, overrun and parity errors detected for that port. The counts provided are
always total errors counted for that port since it was opened which allows the
application to track if any new errors were detected for that port since the last time
this function was called.
108
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrWrite
ecrWrite
Prototype
short bytes_written = ecrWrite(char *buffer, short size);
short bytes_written, size;
char *buffer;
Size is the number of bytes to write, and buffer is a pointer to the data area. This
operation transfers data from an application buffer into the driver's buffer, only if
the latter has adequate space, and control is returned to the application
immediately. The actual transmission occurs at a later time. Status of the
ecrWrite can be monitored using the ecrStatus() command (in VISA2
mode). ecrWrite() returns FAILURE if the current message is pending or
rejected.
Return Values
On error, a negative code will be returned:
-1
With errno set to specific error
-ENOBUF
Message too big or driver busy sending last message
-EBUSY
A rejected message must be read before sending another
message. Use: ecrReadReject()
Any other negative errno
error code
Specific error that occurred
MX800 SERIES PROGRAMMERS GUIDE
109
D EVICE D RIVERS
ecrClose
ecrClose
This function closes the ECR port. Returns 0 if successful. Returns a negative
errno error code if an error occurred.
Prototype
short result = ecrClose();
NOTE
110
The port must be closed in order for it to be returned to a known good state. If the
process is killed that opened the port, it is the responsibility of that process to trap
on the necessary signals to perform all desired cleanup prior to calling
ecrClose().
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrDownload
ecrDownload
This function downloads the APP/OS (uncompressed or compressed ECR format)
from the ECR.
short result = ecrDownload(char *version, void (*dspCallback) (char *),
void (*ecrDnldEnd) (int));
The ECR download functionality operates as a separate thread as its own process
after the ecrDownload() function is called. This function call will return
immediately after the process is started so the application can perform other tasks
and System Mode is still functional.
The version argument contains the application and parameter versions in the form
of 8 characters (4 for application and 4 for parameter) AAAAPPPP. The operating
system uses the version information to set the O4683 configuration variable upon
completion of a successful download. A TO4684 variable is created at the
beginning of the download. Upon completion of a successful download, the
O4683 variable is created with the value of the TO4683 variable and TO4683 is
deleted.
If the application passes a NULL or a NULL terminated string for version, the
operating system will wait for an ONLINE message from the ECR before starting
the download.
The (*dspCallback)(char *) argument is a pointer to a function that is a
callback. It is utilized whenever there is data to be displayed on the Mx800 series
terminal screen. The application can pass in a callback function pointer that will
handle how the data is displayed.
This function has the capability to expand any file downloaded that may have
been archived or compressed with the Linux “tar” command prior to ECR
conversion with the “pclancnv” utility. The expand utility checks if the download file
is of a tar format. If so, then it expands the archive in the users home directory.
Permissions and ownership are then changed on every file and directory
contained within the archive that are not owned by “root – userid 0”.
This function calls the application’s callback specified in the
(*ecrDnldEnd)(int) function pointer argument, with the return code. It is
required that the application pass in a valid callback function pointer to be called
when the download ends. This is the only way the application gets notification of a
successful or unsuccessful download.
The application can call the function ecrDnldCancel() anytime to cancel the
current download.
Prototype
ecrDownload()
MX800 SERIES PROGRAMMERS GUIDE
111
D EVICE D RIVERS
ecrDownload
Return Values
0
download started successfully
-1
the download process failed to start
-EBUSY
an ECR download process is already running
-EINVAL
invalid ECR Download End callback specified
Callback Return Values
112
1
download completed successfully
0
never received an Online packet from the ECR or abort download
-1
download type not recognized
-2
expansion of archived/expressed file, failed
A negative
errno value
specific error that occurred
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ecrDnldCancel()
ecrDnldCancel()
This function allows the application to cancel a current download by calling this
function anytime. If a download is not currently running then the function will return
a –ESRCH (No such process). Otherwise, it will return 0 upon success.
Prototype
int ecrDnldCancel(void)
MX800 SERIES PROGRAMMERS GUIDE
113
D EVICE D RIVERS
Signals
Signals
Signals are present in practically all Unix/Linux systems and are a mechanism to
inform processes of an event that has occurred. Signals have default behavior
and documentation on all the signals available and their default actions can be
found in practically any Linux/Unix programming book. If an application would like
to be informed of an event that there is a signal available for, then the application
can define a handler that would be executed upon receipt of that particular signal.
This allows the application to “trap” on events and handle them as desired. The
Mx800 series of terminals has the ability to use signals. As long as that event is
triggered by the OS or any application, then an application can define a handler to
trap on the desired signal. An example of this would be the SIGINT signal which is
issued whenever an interrupt is received. A common way to receive an interrupt is
when the user presses Ctrl-C on the keyboard. A way to trap on this event would
be to add the following code to the application:
void sigHandler(void)
{
printf("Got Interrupt Signal!\n");
…do desired cleanup stuff here…
exit(0);
}
int main(void)
{
struct sigaction mySig;
int i;
mySig.sa_handler = (void *)sigHandler;
sigemptyset(&mySig.sa_mask);
mySig.sa_flags = 0;
i = sigaction(SIGINT, &mySig, 0);
}
One of the restrictions of using signals is that there can only be one handler per
process and all of its child process’ – this includes processes created by fork()
and any thread that is spawned with pthread_create(). The application
programmer should be aware that any handler that they create for a particular
signal would also have to handle that signal issued by any threads created by that
application. Likewise, there are also Mx800 series terminal libraries that use
signals. If an application links with this library and also wants to use the same
signal then there has to be a mechanism to determine which process sent the
signal and what action to take. The Mx800 series of terminals OS has
implemented two such mechanisms for the SIGIO and SIGALRM signals. These
signals inform an application when any I/O of data has occurred on a particular
device and when an Alarm event has occurred, respectively.
114
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
Signals
The SIGIO signal is issued by the OS whenever any hardware device detects data
I/O has occurred. For example, an application may like to know when data is
available on a serial port. The application could create a signal handler for the
SIGIO signal associated with the file descriptor (handle) of the open port.
However, if any other process (thread, linked library) would also like to know of
this event, then a common handler must be used.
The Mx800 series of terminals OS provides the svcSetRxCallback() function
to manage all handlers for the SIGIO signal for any open device. This function
allows a callback function to be called whenever data is available for a particular
device. It determines this by the file descriptor (handle) of the device and the
function pointer passed into the function. svcSetRxCallback() should be used
whenever the application would like to be notified of data available on a particular
device. More detailed explanation of the function call can be found under the
svcSetRxCallback() section.
When the application wants to close the port or does not need to know of a SIGIO
event any longer, then a call to the function svcReleaseRxCallback() should
be used prior to closing of the port/device. This function will unregister the
callback function associated with that device. More information about this function
can be found under the svcReleaseRxCallback() section.
The SIGALRM signal is currently being used by the ECR library to set a timer that
is used in the retransmit logic of an ECR packet. Since this library uses this signal,
it is required that any application that links with this library to use the common
function call svcSetAlarmCallback() if it also wants to utilize the Alarm
signal. Even if the application does not link with the ECR library, this function call
can still be used to manage all handlers defined within a process and its child
processes for the SIGALRM signal. There is a restriction, however, in using
multiple handlers for the SIGALRM signal in an application. When the
svcSetAlarmCallback() function is called, it registers what handler should be
called by the process id of the process that will issue the signal. This means that
when the SIGALRM signal is issued it must do so by providing the process id
number.
In Linux, this is done with the kill() command. The kill() command takes two
arguments, the process id to send the signal to and the signal to issue. In this
case it would be: kill(getpid(), SIGALRM). Another way for an application
to issue a SIGALRM signal is to use the command alarm(). This command
automatically sets a timer for the number of seconds passed into it and then when
that timer expires, it will send the SIGALRM signal. However, alarm() does not
send the process id and should never be used. An application must create their
own timer by using a combination of sleep() and kill() commands to issue a
SIGALRM signal.
MX800 SERIES PROGRAMMERS GUIDE
115
D EVICE D RIVERS
ECR Environment Variables
The Mx800 series of terminals OS has provided a function that conveniently does
this for the application called svcAlarm(). This function must be used in
conjunction with the svcSetAlarmCallback() function. When the application
no longer needs to be notified of an Alarm signal, it must unregister its callback
function with using svcReleaseAlarmCallback().
ECR
Environment
Variables
There are required environment variables set when the ECR connection is
established. They reside in config.usrx (where x is number of user account 18) and they follow INI parser rules. Some are set in the terminal’s System Mode
and others are set by the Operating System. All environment variables can be set
or retrieved using the putEnvFile() and getEnvFile() function calls
respectively. The definition and implications of each environment variable are as
follows:
I4683
Indicates the port selected. If the terminal is configured in tailgate mode, then this
corresponds to the port of the poll address that the terminal responds to. If the
terminal is configured in feature C mode, then it is set to RS232.
The legal values are summarized below:
NOTE
2A23
tailgate port responding to poll address 0x68.
2B23
tailgate port responding to poll address 0x69
2A25
tailgate port responding to poll address 0x64
2B25
tailgate port responding to poll address 0x65
R232
Feature C (rs232) port communications with ECR
This environment variable can be set in system mode when configuring the ECR
connection. It must be set by the application if it is opening the ECR connection.
O4683
Indicates the application and parameter ID numbers. These numbers are sent
during a download in the online packet (01.XXXXYYYY). It is an 8 byte string
where XXXX and YYYY are defined as follows:
116
XXXX
YYYY
Application Version
Parameter ID
Application Version
is 4 bytes, which can contain any 4 byte alphanumeric string.
Parameter ID
is 4 bytes, which can contain any 4 byte alphanumeric string.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ECR Environment Variables
A4683
Indicates the application id number. This is copied from the application id field of
O4683 after a successful download.
P4683
Indicates the parameter id number. This is copied from the parameter id field of
O4683 after a successful parameter download.
L4683
Indicates the RS232 port configuration. This is known as the line configuration for
the port and is only valid if I4683 is set to R232. It is a 13 byte string with the
following format
COM port
B
Baud Rate
Word Size
Parity
Stop Bits
Auto Enable
RTS
COM port
1 byte RS-232 port, either: ‘1’ ‘2’ ‘3’ or ‘4’
B
1 byte pad (space character) that is mandatory
Baud Rate
6 bytes which can be set to 1200, 2400, 4800, 9600, 19200, 38400,
57600, or 115200
Word Size
1 byte which can be set to either 7 or 8
Parity
1 byte which can be set to Even, None, or Odd, as E, N, or O
respectively
Stop Bits
1 byte, which can be set to either 1 or 2
Auto Enable
1 byte which can be set to A, to enable RTS/CTS flow control
RTS
1 byte which can be set to R, to hold RTS in enabled state
NOTE
L4683 must be set if I4683 is configured for R232.
All padding bytes should be spaces (0x20). If the baud rate is less than 6 bytes,
then it should be followed by padding bytes. Auto Enable and RTS should be set
to uppercase “A” and “R”, respectively. Parity should also be signified with an
uppercase letter of “E”, “N” or “O”. The entire string must be a minimum of 11
bytes – the Auto Enable and RTS are optional. However, if RTS is specified and
Auto Enable is not, then there should be a pad byte (space – 0x20) for Auto
Enable before the RTS “R” is specified. COM 1, 2 and 3 all have flow control
capability.
MX800 SERIES PROGRAMMERS GUIDE
117
D EVICE D RIVERS
ECR Environment Variables
COM4 can also be available if the Mx800 series terminal custom optional module
is present with a physical serial connector. This module may be available as a
future enhancement. Whenever flow control is enabled via the
svcSetOpenBlock() function, then RTS is also asserted and held, regardless if
“R” is specified in the setting. See svcSetOpenBlock() for further description.
Some valid settings are:
2 1152008N1
this string is 11 bytes in length and Auto Enable and RTS are not set.
3 2400 7E1A
this string is 12 bytes in length and Auto Enable (flow control) is
enabled. RTS is held asserted whenever flow control is enabled.
1 9600 7E1 R
this string is 13 bytes in length and Auto Enable is not set and RTS is
set. There is a pad byte for the “A”.
S4683
Indicates the Lane Identification number. This value is set in system mode and the
legal values are any 8 byte numeric value.
V4683
Indicates the VISA communication parameters. It is 2 bytes with each byte set to a
numeric value between 0 and 9. The first byte indicates the retry count and the
second byte indicates the timeout value in seconds. The retry count specifies how
many times a packet should be retransmitted after the initial packet transmission
was not acknowledged (ACK’ed). The timeout value indicates how much time
should lapse between retransmissions. Setting the retry count to 0 or the timeout
value to 0 will cause no retransmissions.
The default value is: 39 (3 retries and 9-second timeout)
NOTE
If the application does not want the default value, then it must be set either in
system mode, downloading its value or setting this environment variable to the
desired value following INI parser rules.
G4683
Set via a System Mode ECR download. If a Full download is selected then G4683
is set to FULL. If a Partial download is selected then G4683 is set to PART. This
variable is not read by the operating system and exists so that the application can
determine the download mode. When the download starts either by System Mode
ECR/Serial download or a call to the ecrDownload() function, the G4683
variable is read. If its value is set to FULL, then all files and sub-directories will be
deleted.
118
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
Downloading Files from the ECR
Downloading IBM ECRs support downloading of the following files to terminals connected to it
Files from the via Tailgate /Feature C:
ECR 1 Program File named EFTLxxxx , xxxx represents the program version number.
2 Parameter File named EFTPyyyy, yyyy represents the parameter version
number.
The Program file and Parameter file are stored in the ECR. ECR supports only
ASCII files for download. “PCLANCNV” is used to convert the TXO application
program, data files, environment variables, and others into a compressed ASCII
file suitable for ECR download. This file is copied into the ECR following the
naming conventions of the ECR.
When the clerk signs on, ECR sends an ONLINE request to the terminal that
contains xxxx and yyyy version numbers. Based on these version numbers, the
Application decides whether to request a new download or not. If an Application is
not present, the OS always requests a new application download. Applications
can also request Parameter download at any time.
The following are the message formats:
ONLINE request
<STX>01.xxxxyyyy<ETX><LRC>
PROGRAM LOAD REQUEST
<STX>02.nnnnnnnn<ETX><LRC>
nnnnnnnn is the Terminal Serial Number
PROGRAM LOAD RESPONSE
<STX>02.nnnnnnnn<data ><ETX><LRC>
PARAMETER LOAD REQUEST/CONFIRMATION
<STX>59.<ETX><LRC>
PARAMETER LOAD RESPONSE
<STX>9XX<data ><ETX><LRC>
MX800 SERIES PROGRAMMERS GUIDE
119
D EVICE D RIVERS
Touch Panel / Signature Capture/TIFF
Touch Panel /
Signature
Capture/TIFF
The touch panel is calibrated (also called compensated) at the factory. The factory
calibration is used by the system until it is periodically updated. VeriFone strongly
recommends that the touch panel be calibrated daily during a period of inactivity.
During calibration, the unit must not be touched. VeriFone also recommends that
the display backlight be turned off during calibration. Use the
setDspBrightness() function to turn off the backlight. Use the
touchCompNSave() function to perform the daily touch panel calibration.
Touch Panel Specifications
•
X-axis values are 0 – 2047 (460 DPI)
•
Y-axis values are 0 – 1535 (460 DPI)
•
Z-axis values are 0 – 127 (0 = Max force)
•
Sample rate is 100 per second
•
The maximum active area is: 113mm x 85mm
Linux interface is via: /dev/input/mice - The touch panel emulates a PS2
mouse. Use FancyPants GUI API to access touch activity and position.
120
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
touchCmd()
touchCmd()
touchCmd() is used to set and get touch panel functionality per the following
table:
Table 7
cmd
value
return
Notes
2
N.A
Bit values
Returns the status of the stylus.
Bits 1 or 2 = 1 if a stylus is attached
All other bits reserved.
Example:
If (touchCmd(2,0) & 0x06)
printf(“Stylus Attached”);
4
0 or 1
N.A
Set input method:
0 = Finger or Stylus (Automatic)
1 = Stylus only
X
N.A
N.A
All cmd values not listed are RESERVED
Prototype
int touchCmd(int cmd, int value)
MX800 SERIES PROGRAMMERS GUIDE
121
D EVICE D RIVERS
touchCompNSave()
touchCompNSave()
touchCompNSave() is used to perform a touch panel calibration. The terminal
must not be touched between the time this function is called and the time it
returns. VeriFone recommends that touchCompNSave() be called once per day.
VeriFone also recommends that the backlight be turned off during touch panel
calibration.
Prototype
int touchCompNSave(void)
Return Values
122
0
Success
1
Error
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
Signature Capture
Signature
Capture
NOTE
Signature Capture is implemented as a widget at the FancyPants GUI level. The
widget supports the definition of a signing region as well as the ability to track
stylus movement. Note that the strokes returned by the Signature Capture widget
are scaled to 320x234 (72dpi). If a higher resolution image is desired, use the API
defined below to read and process the raw data.
During signature capture, the unit will switch to stylus only mode only if there is
one attached.
#include “svc.h”
#include “sig.h”
typedef struct {
long x : 12; // X co-ordinate 0…2047 of touched point
long y : 12; // Y co-ordinate 0…1535 of touched point
long z :
8;
//
Z co-ordinate/pressure 0…127 of touched point
} __attribute__((packed)) xyz_t;
This is a representation of the x,y,z value of a single touched point packed into a
single 32 bit long - x,y and z are all signed quantities.
Also defines PENUP which is the special value {.x = -1, .y = -1, .z = -1}.
On error the functions all return -1 with the reason for the error in errno.
MX800 SERIES PROGRAMMERS GUIDE
123
D EVICE D RIVERS
SigCapCount()
SigCapCount()
Returns the number of signature points that are currently available.
Prototype
int SigCapCount(void)
124
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
SigCapGet()
SigCapGet()
Copies up to maxPoints of data from the kernel buffer to the user buffer. Returns
the number of points actually copied, which would be less than maxPoints if
fewer points are available. Use SigCapCount() to retrieve the number of points
captured. Be sure to allocate a buffer large enough to hold the number of points
captured.
For example, if SigCapCount returns 1000 then the buffer must be size of
(xyz_t)*1000 bytes.
Prototype
int SigCapGet(void *data, int maxPoints)
MX800 SERIES PROGRAMMERS GUIDE
125
D EVICE D RIVERS
SigCapBoxApply()
SigCapBoxApply()
This function takes the results of SigCapGet() and applies a signature box to
the data. Data outside the box is replaced by PENUP. The data is also
compressed to remove adjacent duplicate points and adjacent PENUPs. The
function returns the new number of unique points. It is up to the application to
supply the signature box to the function call. The box coordinates are in screen
form, i.e. x 0…319 and y 0…239. Signature data is in touchpad coordinates
0…2047 and 0…1535 to maintain best resolution. It is not necessary to call this
function before calling SigCap2Tiff().
NOTE
Extra notes on using this function with SigCapGet and SigCapCount:
• By design, a single pen up (-1,-1,-1) is inserted at the beginning of the buffer as soon
as signature capture is started. That is why a count of 1 is returned and the point is
returned as (-1,-1,-1). As long as the pen stays up, no further points are inserted. Once
the pen goes down, new data (x,y,z) are added. A pen up is also always inserted at the
end of the buffer so that if the pen were able to go down and up again fast enough for
just one down point to be registered, the count would be 3 (initial pen up, the down
point, and another pen up). This mimics Omni 7X00 behavior and is not a bug.
• SigCapGet and SigCapCount always return the total number of raw points collected.
The longer the pen is in contact with the keypad, the higher the count will be -- it does
not matter if the points are in the box or not. Part of this count will be the residue from
the initial pressing of the STROKES button in the test program. Those points will be
replaced by -1,-1,-1 when SigCapBoxApply is called — refer to the next bullet item.
The positive result of the above function should be passed as the count parameter to
SigCapBoxApply.
• SigCapBoxApply does two things on the fly:
- It replaces all points outside the box by -1,-1,-1
- It compresses (shuffles toward the beginning of the buffer) the data so that all
adjacent duplicates (for example several -1,-1,-1 in a row after applying the box)
are replaced by a SINGLE copy of the data (in this case a single -1,-1,-1).
This function returns the new total number of points after compression.
• The original and compressed counts will almost certainly differ.
• When displaying the compressed data, the return value of SigCapBoxApply should
be used as the new size unless one deliberately wants to display the raw data.
Prototype
int SigCapBoxApply(xyz_t *Sig, int count, SigCapBox_t *box);
126
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
TIFF API
TIFF API
The TIFF API allows the application to generate a TIFF file from previously
captured signature data. It is normally called after the call to SigCapGet().
The API requires the presence of libtiff.so which is built and distributed by
Verifone from a publicly available library distribution. The library distribution files
are not changed in any way by Verifone; we simply run a special configuration and
build to reflect the functionality we need extracted from the library. This allows us
to easily take advantage of new releases of the library.
The library comes with 4 application header files: tiffvers.h, tiffconf.h,
tiffio.h, and tiff.h which are built when the library gets configured and built
and should not be altered in any way as any rebuilds of the library might invalidate
or overwrite them. Applications using libtiff uses #include tiffio.h, which
automatically includes the other 3 files.
We have enabled the main features such as the CCITTFAX4 compression which
is currently used in previous Verifone products. Enabling every feature would have
resulted in a much larger libtiff file. JPEG, for example, is not included.
Verifone also supplies libvfisigtiff.so to provide a wrapper allowing easy
use of the library for typical Verifone applications. The functionality provided in
libvfisigtiff is as follows:
#include “sigtiff.h” which prototypes the following:
typedef struct {
short x;
short y;
} __attribute__((packed)) xy_t;
It continues with:
typedef struct
{
short left,upper,right,lower;
} SigCapBox_t;
typedef struct
{
long joinPoints: 1;
long trimWidth: 1;
long trimHeight: 1;
long unused: 29;
} SigCapOptions_t;
MX800 SERIES PROGRAMMERS GUIDE
127
D EVICE D RIVERS
int SigCap2Tiff()
int SigCap2Tiff()
This function creates a file fname in TIFF format. Setting fname to 0 is an error.
Prototype
int SigCap2Tiff
(
char *fname,xyz_t *sig, int count,short compression_scheme,
xy_t *dpi,SigCapBox_t *box, SigCapOptions_t *options,
void (*setTiffUserTags)(TIFF *)
);
Parameters
128
sig
is a pointer to the user’s signature data buffer consisting of
points of type xyz_t. The z data is currently ignored but
may be processed in some way (yet to be defined) in future
releases. Setting sig to 0 is an error.
count
is the number of signature points in the caller’s buffer. A
negative value is an error.
compression_scheme
defaults to COMPRESSION_CCITTFAX4 if the caller sets the
parameter to 0. Otherwise the scheme specified by the
parameter is used. The compression schemes are
#defined in tiff.h.
dpi
is a pointer to an xy_t structure (prototyped in ps2.h) that
specifies the desired x and y TIFF image resolution in dots
per inch. Set to 0 to force maximum resolution to be used.
box
is a pointer to a signature box specified in QVGA display
coordinates {.x=0…319, .y=0…239). Data outside the box is
interpreted as PENUP. Set to 0 to make the box be the
entire screen.
Options
is a pointer to a structure that specifies whether points are
joined (using Bresenham’s algorithm) and whether trimming
is applied to the width and height of the image. Trimming is
removing any empty space at the left and right, or top and
bottom of the image. This generally results in a smaller
image and image file. The pointer may be set to 0 to get the
default options, which are to join the points and to trim along
both axes.
setTiffUserTags
is an optional pointer to a user function, described further
below, that may be used to set various user tags. Set to 0 if
not used.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
int SigCap2Tiff()
Return Values
NOTE
0
Success
<0
Error
The setTiffUserTags function can override the default date/time tag that is
automatically inserted into the file.
This is an optional user-supplied function that can over-ride standard tags (but be
careful or the TIFF image may be affected or unusable) and can also define and
specify new user tags in the range MIN_TIFFTAG_USER to MAX_TIFFTAG_USER
(both defined in sigtiff.h.)
An example of the setTiffUserTags function calling the structure containing
the user-specified tags. The example TIFFTAG_GEO… user defined tags below
should be given values in the range MIN_TIFFTAG_USER to
MAX_TIFFTAG_USER. Consult the tiffio.h header file for a summary of the
meanings of the fields in the TIFFFieldInfo structure used in the table below.
CAUTION The open source TIFF library does not implement complete error checking. Be
careful to use only TIFF tag values within the range defined above. Unpredictable
results will occur with other tag values.
static const TIFFFieldInfo xtiffFieldInfo[] =
{
/* XXX Insert Your tags here */
{ TIFFTAG_GEOPIXELSCALE,-1,-1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE,
"GeoPixelScale" },
{ TIFFTAG_GEOTRANSMATRIX,-1,-1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE,
"GeoTransformationMatrix" },
{ TIFFTAG_GEOTIEPOINTS,-1,-1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE,
"GeoTiePoints" },
{ TIFFTAG_GEOKEYDIRECTORY,-1,-1,TIFF_SHORT,FIELD_CUSTOM,TRUE,TRUE,
"GeoKeyDirectory" },
{ TIFFTAG_GEODOUBLEPARAMS,-1,1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE,
"GeoDoubleParams" },
{ TIFFTAG_GEOASCIIPARAMS,-1,-1,TIFF_ASCII,FIELD_CUSTOM,TRUE,FALSE,
"GeoASCIIParams" },
};
static void setTiffUserTags(TIFF *tif)
{
TIFFMergeFieldInfo(tif,xtiffFieldInfo,N(xtiffFieldInfo));
TIFFSetField(tif,TIFFTAG_GEOASCIIPARAMS,"Geo ASCII Params
(Custom)Field");
TIFFSetField(tif,TIFFTAG_DOCUMENTNAME,"Document Name Field");
}
MX800 SERIES PROGRAMMERS GUIDE
129
D EVICE D RIVERS
Display
Display
130
The user interface is managed by the FST FancyPants GUI.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
dspSetBrightness()
dspSetBrightness()
Allows the display brightness to be adjusted. If direction is 1, the brightness will be
increased. If direction is 0 the brightness will be decreased. There are 32 discrete
brightness settings. The brightness can be adjusted significantly by repeated calls
to dspSetBrightness. On power up, the brightness is set to 16 (of 32 steps).
The environment variable, *BACKLIGHT should be set (value: 1-32) if the
backlight is to be permanently changed from default.
NOTE
When the brightness is set to 0, the backlight will turn off.
Prototype
short dspSetBrightness(short direction);
Return Values
0
OK
<0
Brightness at max/min setting
MX800 SERIES PROGRAMMERS GUIDE
131
D EVICE D RIVERS
Audio / Beeper
Audio / Beeper
At the lower level, the Mx800 series terminal kernel will implement a sound device
using the Open Sound System (OSS) specification. See: http://
www.opensound.com/
Applications written to the OSS specification should run on the Mx800 series of
terminals. The sound device is located at: /dev/dsp
The FancyPants GUI will include a media player widget that supports the .WAV
audio format.
132
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
soundCtrl()
soundCtrl()
The VeriFone supplied library (libvfisvc.so) contains support for controlling
the audio volume, bass, and treble via the following API:
Prototype
int soundCtrl(int volume, int bass, int treble)
Parameters
Accepted values: 0-100
volume
0
Sound off
100
Maximum volume
bass
Accepted values: 50-100
treble
Accepted values: 50-100
Return Values
0
No error
Less than 0
Error occurred
MX800 SERIES PROGRAMMERS GUIDE
133
D EVICE D RIVERS
speaker()
speaker()
The VeriFone supplied library (libvfisvc.so) contains support for enabling /
disabling the built in speakers. Disabling the built in speakers may be desirable if
external speakers are connected to the Audio lineout connector on the multi-port
cable.
Prototype
void speaker(int mode)
Parameters
mode
0
Disbale Internal Speakers
1
Enable Internal Speakers
All other values are not supported and will give unexpected
results.
134
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
normalTone() / errorTone()
normalTone() / errorTone()
Prototype
normalTone()
errorTone()
NOTE
Some Mx800 series terminals may lack sound capability and will only support a
traditional beeper. In this case, the legacy API will be supported.
MX800 SERIES PROGRAMMERS GUIDE
135
D EVICE D RIVERS
LEDs
LEDs
136
One of the features of the Mx800 series of terminals are the three blue LEDs
located in Magnetic Stripe Reader. The purpose of these LEDs is to inform the
user that they can swipe their card. More complex use of the LEDs will require a
thread or timer for synchronization. It is recommended to use the ecore timers
available in the GUI library.
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
ledOn
ledOn
ledOn() is used to turn 1 or more of the LEDs on.
A bit mask is used to select the LED(s) to turn on.
Prototype
void ledOn(int parm)
Parameters
parm
LED1
Top LED
LED2
Middle LED
LED3
Bottom LED
To turn on all three LEDs,
set PARM = LED1|LED2|LED3
MX800 SERIES PROGRAMMERS GUIDE
137
D EVICE D RIVERS
ledOff
ledOff
ledOff() is used to turn 1 or more of the LEDs off.
A bit mask is used to select the LED(s) to turn off.
Prototype
void ledOff(int parm)
Parameters
parm
LED1
Top LED
LED2
Middle LED
LED3
Bottom LED
To turn off all three LEDs,
set PARM = LED1|LED2|LED3
138
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
Real-Time Clock (RTC)
Real-Time Clock
(RTC)
Linux has a rich API to support RTC functionality, so we will not be supplementing
or modifying that API. The Mx800 series of terminals include VeriFone specific
RTC hardware required to keep the time accurate when the unit is turned off.
On power up, the operating system will automatically set the Linux (soft) RTC
from the Mx800 series terminal RTC hardware.
The setRTC() function must be called immediately after any call that sets the
time/date of the Linux RTC or the updated time/date will be lost when the unit is
turned off.
MX800 SERIES PROGRAMMERS GUIDE
139
D EVICE D RIVERS
setRTC()
setRTC()
Used to set the RTC hardware to the Linux RTC time/date. This function must be
called immediately after any function that sets the Linux RTC time/date. There are
no parameters or return codes from setRTC().
Prototype
void setRTC(void)
140
MX800 SERIES PROGRAMMERS GUIDE
D EVICE D RIVERS
setDateTime()
setDateTime()
As user processes are not allowed to set the Linux RTC, applications must call
setDateTime() passing the date and time in the same format used in the shell
command date.
Format: MMDDhhmmYYYY.ss
NOTE
•
MM = Month
•
DD = Day
•
hh = Hour (24-hour format)
•
mm = Minute
•
YYYY = Year
•
ss = Seconds
setDateTime only sets the Linux RTC. To set the H/W RTC, application must
follow setDateTime with a call to setRTC.
Prototype
int setDateTime(char *dateTime)
Return Values
0
Success
Less than 0
Error
MX800 SERIES PROGRAMMERS GUIDE
141
D EVICE D RIVERS
setDateTime()
142
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 5
Service Functions
Service
Functions for
the Mx800 series
of Terminals
This chapter lists the service function APIs used in the Mx800 series of terminals.
MX800 SERIES PROGRAMMERS GUIDE
143
S ERVICE F UNCTIONS
svcCrcCalc()
svcCrcCalc()
Prototype
checksum = svcCrcCalc(type, buffer, size)
int checksum, type, size;
char*buffer;
Parameters
This routine returns the cyclic redundancy check for a string contained in buffer
of a length specified by size. Each type is now specified by referring to a
standard CRC description model which can be found by searching the Internet for
“A Painless Guide to CRC Error Detection Algorithms” (August 1993) by Ross N.
Williams.
The model has the following description parameters: width (of CRC/LRC in bits),
poly(nomial), (init)ialization value generally 0 or -1, refin (whether each input byte
is reflected about its center before being applied to the algorithm), refot (whether
the calculated CRC gets reflected about its center), xorot (the value generally 0 or
-1 that gets exclusive-ored to the final result before being returned to the caller,
check (the CRC/LRC produced by applying this algorithm to the 9-character ascii
string “0123456789”.
The type parameter specifies what type of calculation is to be employed:
0
Longitudinal Redundancy Check. This is simply the exclusive OR'ing of all
bytes in the string. The result of the LRC will be stored in the lower byte. The
upper byte will be set to zero.
Model: width=8,poly=0x01,init=0,refin=0,refot=0,xorot=0,check=0x31.
1
Cyclic Redundancy Check, based on the standard CRC16 polynomial,
X^16+X^15+X^2+1. Bits are read least-significant-bit first, as is traditional in
hardware implementations. The CRC1 value is returned in the low byte and
the CRC2 value is returned in the high byte.
Model: width=16,poly=0xA001,init=0,refin=0,refot=0,xorot=0,check=0xA47b
2
CRC16, most-significant-bit first, as is often used in software implementations.
The CRC1 value is returned in the high byte and the CRC2 value is returned in
the low byte.
Model: width=16,poly=0x8005,init=0,refin=0,refot=0,xorot=0,check=0xFEE8
3
CCITT polynomial, X^16+X^12+X^5+1, lsb-first
Model: width=16,poly=0x8408,init=-1,refin=0,refot=0,xorot=0,check=0x0520
4
CCITT, msb-first
Model: width=16,poly=0x1021,init=-1,refin=0,refot=0,xorot=0,check=0x29B1
144
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCrcCalc()
5
CRC32, lsb-first, reflected input and output
Model: width=32,poly=0x04C11DB7,init=0,refin=1,refot=1,xorot=0,
check=0x2DFD2D88
6
CRC32, lsb-first, reflected input & output, inverted result
Model: width=32,poly=0x04C11DB7,init=-1,refin=1,refot=1,xorot=-1,
check=0xCBF43926
7
CRC16, msb-first, reflected input and output
Model: width=16,poly=0x8005,init=0,refin=1,refot=1,xorot=0,check=0xBB3D
8
CCITT16, msb-first, reflected input and output
Model: width=16,poly=0x1021,init=0,refin=1,refot=1,xorot=0,check=0x6F91
NOTE
For both CRC16 computations, the initial value used for the checksum will be
reset to all zeros (0x0000). For both CCITT computations, the initial value used
for the checksum will be set to all ones (0xFFFF).
Please note that the programmer has to decide in each application whether to
swap the bytes of the final CRC result to comply with little or big end requirements
of any earlier code that is being ported. Little versus big end is not part of the CRC
model spec.
Algorithms 6, 7, and 8 were added during driver and application development to
try and ensure that existing porting needs were met. The model code was
downloaded, compiled and run against each of the algorithms to produce the
above check results.
MX800 SERIES PROGRAMMERS GUIDE
145
S ERVICE F UNCTIONS
svcDsp2Hex()
svcDsp2Hex()
This command causes the data at dsp to be converted and stored at location
hex. The presumption is that the input (at dsp) consists of count pairs of bytes,
with each byte in the range of 30h-90h (ASCII 0-9) or 42h-46h (ASCII A-F). Each
byte will then be converted to the corresponding hexadecimal nibble (hex 0-9, AF).
This function will convert up to a long hex value for the corresponding ASCII array.
It will only convert up to the number of pairs specified even if the ASCII string is
longer. This function is a void function and does not return any error or success
code. It expects all values to be legal hex values.
Prototype
void svcDsp2Hex(dsp, hex, count)
Example
Suppose dsp contains ASCII array “12345F” and we execute
SVC_DPS_2_HEX(dsp, hex, 3). Then the value of hex will be 12345h.
146
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcRestart()
svcRestart()
This routine will reboot the terminal. The terminal will shut down and then start up
as if it has just been started initially at power on.
NOTE
Set the configuration variable *GO if you wish to restart and begin execution of a
specific application.
Prototype
void svcRestart(void);
MX800 SERIES PROGRAMMERS GUIDE
147
S ERVICE F UNCTIONS
svcInfoKernel() / svcInfoEprom()
svcInfoKernel() / svcInfoEprom()
This function fills buffer with the current firmware ID in null-terminated string
format.
Prototype
svcInfoKernel(buffer);
svcInfoEprom(buffer);
char
*buffer;
The Mx800 series of terminals has been assigned the identifier, Mx. Released OS
versions will be MxXxYyAa.
Parameters
Xx
reserved (00)
Yy
Version Number
Aa
Country Code
The length will always be eight characters.
148
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcInfoRFS()
svcInfoRFS()
This function fills buffer with the current version of the root file system. The eight
character string is null-terminated.
Prototype
SvcInfoRFS(buffer);
char*buffer;
MX800 SERIES PROGRAMMERS GUIDE
149
S ERVICE F UNCTIONS
svcInfoSerialNum()
svcInfoSerialNum()
This function fills buffer with the unit’s serial number in the form: xxx-xxx-xxx.
The 11-character string is null terminated. The serial number returned will match
the serial number sticker on the bottom of the unit.
Prototype
SvcInfoSerialNum(buffer);
char
150
MX800 SERIES PROGRAMMERS GUIDE
*buffer;
S ERVICE F UNCTIONS
svcInfoPtid()
svcInfoPtid()
This function fills buffer with the UNIT ID in null-terminated string format.
Prototype
svcInfoPtid(buffer);
char*buffer;
Default value
12000000
MX800 SERIES PROGRAMMERS GUIDE
151
S ERVICE F UNCTIONS
svcInfoPlatform()
svcInfoPlatform()
This function provides information about the terminal running the application.
feature can be one of the following values:
Table 8
Feature
Definition
0
Unit Configuration
1
Lithium Battery Status
2
Lithium Battery Voltage in tenths of a Volt
3
SDRAM size in KB
4
Multi-port Cable Status
5
I/O Module Configuration
6
Smart Card Version
7-15
Reserved
Prototype
result = svcInfoPlatform(feature);
int result, feature;
Return Values
The information is returned in result.
If feature = 0, then the following bit values are returned for unit configuration:
Table 9
Bits
Definition
Value
0
Ethernet
1 = installed
1
Smartcard
1 = installed
2
Audio
1 = installed, 0 = buzzer
3-15
Reserved
If feature = 1, then the value in result for the lithium battery status will be:
NOTE
1
If the lithium battery is OK
0
If the lithium batter is bad
The lithium battery is used to preserve the SRAM on the Mx800 series terminal
when the power is off.
If feature = 2, then the value in result will be the lithium battery voltage, in tenths of
a Volt (0.1V).
152
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcInfoPlatform()
If feature = 3, then the value in result will be the amount of static RAM currently
installed in kilobytes.
If feature = 4, then the following bit values are returned, for multi-port cable status:
Table 10
Bits
Definition
Value
0
Multi-port cable type*
0 = Everest
1 = Mx800 series
1
USB Type**
0 = Host
1 = Client
2
COM1 Configuration
0 = RS-232
1 = RS-485 (LAN)
3
COM3 Configuration
0 = RS-232
1 = RS-485 (ECR Tailgate)
4
COM1 Connection Detected**
1 = YES
5
COM2 Connection Detected**
1 = YES
6-15
Reserved
NOTE
If Everest type multi-port, then USB and Ethernet ports are not available.
NOTE
Connection to a powered DTE or DCE. These bits are valid only if the Mx800
series terminal multi-port cable is detected.
If feature = 5, then the following bit values are returned, for I/O module
configuration:
Table 11
Bits
Definition
Value
0
Contactless/RFID
1 = YES
1
802.11
1 = YES
2
Biometrics
1 = YES
3-14
Reserved
15
O7xxx I/O module
1 = YES
If feature = 6, then the following bit values are returned, for smart card version:
Table 12
Bits
Definition
Value
0
Smart Card Version 1 (Delta)
1 = YES
1
Smart Card Version 1 (Delta2)
1 = YES
2-15
Reserved
MX800 SERIES PROGRAMMERS GUIDE
153
S ERVICE F UNCTIONS
svcInfoType()
svcInfoType()
This function provides more information about the terminal running the
application. feature can be one of the following values:
0
Processor type:
6 = S3C2410
1
Platform:
1000 = Mx800 series of terminals
Prototype
result = svcInfoType(feature);
int result, feature;
Return Values
The information is returned in result.
154
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcInfoDsp()
svcInfoDsp()
This function provides information about the physical characteristics of the display
on the terminal running the application. feature can be one of the following
values:
0
Characters / row (0 if variable)
1
Characters / column (0 if variable)
2
Pixels / row (0 if not pixel variable)
3
Pixels / column (0 if not pixel variable)
4
Packed tail characters (0=no, 1=yes)
5
Number of fonts supported
6
Display type (0=segmented, 1=pixel)
7
Contrast adjustable (0=no, 1=yes)
Prototype
result = svcInfoCard(feature);
int result, feature;
Return Values
The information is returned in result.
0
0
1
0
2
320
3
240
4
0
5
0
6
1
7
1
MX800 SERIES PROGRAMMERS GUIDE
155
S ERVICE F UNCTIONS
svcInfoCard()
svcInfoCard()
This function provides information about the type of card reader supported by the
terminal on which the application is running. feature must be a value of 0.
feature = 0
Bit map of supported track options
0x01
Dual track
0x02
track 1
0x04
track 2
0x08
track 3
0x10
Triple track
Prototype
int return = svcInfoCard(int feature);
Return Values
The information returned in result will be the OR’ed value of all tracks
supported. Since all Mx800 series terminals support triple track reading, the value
returned is the OR’ed value of track 1, track 2, track 3, and triple track support
which is 0x1E.
156
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcInfoKey()
svcInfoKey()
This function provides information about the type of keyboard supported by the
terminal on which the application is running. feature can be one of the following
values:
0
number of standard keys: returns 0
1
number of non-screen-addressable function keys: returns 0
2
number of screen-addressable function keys: returns 0
3
keypad layout (0=telco, 1=calculator, 2=Touch): returns 2
4
If return value is >0 then a touch panel is installed: returns 1
Prototype
result = svcInfoKey(feature);
int result, feature;
Return Values
The information is returned in result.
MX800 SERIES PROGRAMMERS GUIDE
157
S ERVICE F UNCTIONS
svcInfoSerialNum
svcInfoSerialNum
Returns the serial number of the unit. This is the same serial number that is on the
unit’s label. The returned string is null-terminated.
Format of buf: xxx-xxx-xxx
xxx-xxx-xxx is an ASCII 11-digit string. (e.g. 000-012-030)
Return Values
result = svcInfoSerialNum(char *buf);
158
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcZontalkRcv()
svcZontalkRcv()
svcZontalkRcv() allows an application to perform a LOCAL DL/Zontalk/
VeriTalk download. The application must open and configure the port prior to
calling this function.
NOTE
svcZontalkRcv()is a threaded function and will return immediately. The return
code will be < 0 if the download could not be initialized.
The application will receive a callback when the download has completed (on
success of failure). Another callback is provided to pass messages from the
server. The function zontalkCancel() can be called at any time to cancel the
download.
Prototype
result = svcZontalkRcv(int port, void(*dspCallback)(char *msg), unsigned
char type, void(*endCallback)(inti result);
int result;
Parameters
port
Communication port where the download will be received.
COM1,COM2 or COM3 may be specified.
dspCallback
Callback function that will be called when an information/status
message is received from the Zontalk/DL server. A string will be
passed to the callback function with the null terminated server.
type
endCallback
F
Full download
P
Partial download
Callback function that will be called when the download has
completed successfully or failed. An integer will be passed to the
callback function with the result code. Values < 0 indicate failure.
svcZontalkRcv() supports and will process three environment variables when
performing a download. They are:
ZT
Specifies the terminal ID. Will be set to the terminal id specified and will
be used in the client sign-on packet with the server. Only the first eight
characters are valid and used in the sign-on packet.
ZA
Specifies the application ID. Will be set to the application ID specified
and will be used in the client sign-on packet with the server. Only the
first eight characters are valid and used in the sign-on packet.
MX800 SERIES PROGRAMMERS GUIDE
159
S ERVICE F UNCTIONS
svcZontalkRcv()
If the server application supports embedding environment variables in the
download stream, then svcZontalkRcv() will set these environment variables
in the users configuration file. If any of the above two environment variables are
already set prior to initiating a download, then their values will be used as
described above. If these environment variables are not present, then the terminal
and application ID will default to the strings “DEFAULT” and “1”, respectively.
This function is the same function used in a System Mode download. A System
Mode download will display DOWNLOAD SUCCESSFUL, DOWNLOAD FAILED, or
DOWNLOAD CANCELLED message indicating the completion of the download and
its status.A user can cancel the download by touching the System Mode screen
before the download is completed. Filenames of downloaded files are limited to 60
characters or less.
NOTE
160
The port should be configured for character mode and 8 bit, no parity, 1 stop. The
baud rate may be any rate supported.
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
zontalkCancel
zontalkCancel
Cancels a Zontalk/DL download (initiated by svcZontalkRcv).
In System Mode, the user can cancel the download by touching the System Mode
screen before the download is completed. The message, DOWNLOAD CANCELLED,
will then be displayed on the screen.
Prototype
result = zontalkCancel();
int result;
Return Values
Returns 0 on success and < 0 if an error occurred or a download is not in
progress.
MX800 SERIES PROGRAMMERS GUIDE
161
S ERVICE F UNCTIONS
svcSetOpenBlock()
svcSetOpenBlock()
The svcSetOpenBlock() function accepts a pointer to an Open Block structure
that has been populated by the application to the desired port settings. This
function then takes the open block settings and properly maps them to Linux serial
port settings and sets the port to these values. The port to be set is described by
the fd parameter. The function will automatically configure the port according to
the open block structure values passed in. If the open block format variable is set
to Fmt_auto, then the port is automatically configured to use RTS/CTS flow
control and will also hold the RTS line asserted. All ports configured with
Fmt_auto will hold the RTS line asserted regardless if the Fmt_RTS value is
specified or not. This is required for all ports to transmit and receive data correctly.
The application is not required to specifically set Fmt_RTS if Fmt_auto is
specified. However, if this function is not used to configure a COM port on the
Mx800 series terminal and the application wants to enable flow control, it is the
responsibility of the application to issue the proper Linux calls to set flow control
AND assert RTS in order for COM port communication to function properly. If RTS
is not asserted when flow control is desired, the port will not work. If flow control is
not desired, but RTS asserted is, then Fmt_RTS should only be specified. It is
highly recommended that applications use this function to configure a COM port to
desired settings.
Prototype
short svcSetOpenBlock(int fd, struct Opn_Blk *pOpenBlock)
Parameters
fd
File descriptor returned when opening a serial port with either
open() or ecrOpen().
*pOpenBlock
Pointer to Open Block structure that has been populated with
desired settings.
Return Values
The function returns 0 on success or a negative errno value if unsuccessful.
162
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcSetRxCallback()
svcSetRxCallback()
The svcSetRxCallback() function is used to specify a function that an
application wants to be called whenever data is received on a particular device
designated by the file descriptor parameter. When the svcSetRxCallback()
function is called it checks to determine if the ECR has been opened.
If Visa mode is enabled then the callback function will be called when a complete
Visa packet is available. If Visa mode is not enabled, then the application's
callback will be called when data I/O has occurred on that device, such as a
character is received on the open port. This is also true if this function is used to
set a callback function for any device (not just using ecrOpen).
Prototype
int svcSetRxCallback(int fd, void (*rxfp)(void))
Parameters
fd
File descriptor returned when opening a device, with either
open() or ecrOpen().
(*rxfp) (void)
Function pointer which points to function to be called when data
is available.
Return Values
The function returns 0 on success or a negative errno value if unsuccessful.
MX800 SERIES PROGRAMMERS GUIDE
163
S ERVICE F UNCTIONS
svcReleaseRxCallback()
svcReleaseRxCallback()
The svcReleaseRxCallback() function must be used when the application no
longer needs to know if data I/O has occurred on a particular device associated
with the file descriptor (handle) given. The file descriptor (fd) passed to this
function should be the same one that was used to register a callback function for
the device with svcSetRxCallback().
Prototype
short svcReleaseRxCallback(int fd)
Parameters
fd
File descriptor returned when opening a device, with either open()
or ecrOpen().
Return Values
The function returns 0 on success or a negative errno value if unsuccessful.
164
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcSetAlarmCallback()
svcSetAlarmCallback()
The svcSetAlarmCallback() function is used to specify a function that an
application wants to be called whenever the SIGALRM signal is issued by that
process. The application should call this function whenever it wants to register a
callback function to be called when the SIGALRM signal is issued and it should
provide the process ID of the process that will issue the signal. The process ID
can be determined by issuing the command getpid() as long as
svcSetAlarmCallback() is called in the same process as the one issuing the
signal. If the application creates any threads that will issue the SIGALRM signal,
the process ID of that thread must be registered with the
svcSetAlarmCallback(). If svcSetAlarmCallback() is always called from
the same process/thread as the one issuing the signal, there is never a problem.
However, if the svcSetAlarmCallback() is called from a different process/
thread than the one that will issue the SIGALRM signal, then it is the responsibility
of the application to manage this. When an application wants to issue the
SIGALRM signal, the function svcAlarm() can be used to conveniently
sleep() for the specified amount of seconds and issue the SIGALRM signal.
Prototype
int svcSetAlarmCallback(int pid, void (*rxfp)(void))
Parameters
pid
Process ID of the process that will issue the SIGALRM signal.
(*rxfp) (void)
Function pointer which points to function to be called when
SIGALRM signal has been issued.
Return Values
The function returns 0 on success or a negative errno value if unsuccessful.
MX800 SERIES PROGRAMMERS GUIDE
165
S ERVICE F UNCTIONS
svcReleaseAlarmCallback()
svcReleaseAlarmCallback()
The svcReleaseAlarmCallback() function must be used when the
application no longer needs to know if the SIGALRM signal has been issued for a
particular process. The process ID (pid) passed to this function should be the
same one that was used to register a callback function for the device with
svcSetAlarmCallback().
Prototype
short svcReleaseAlarmCallback(int pid)
Parameters
pid
Process ID that was used to register the callback with
svcSetAlarmCallback().
Return Values
The function returns 0 on success or a negative errno value if unsuccessful.
166
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcAlarm()
svcAlarm()
The svcAlarm() function can conveniently be used to set the number of
seconds to wait before a SIGALRM signal is issued to the current process. This
function can only be used if the SIGALRM signal is to be issued to the current
process. It assumes when a callback was registered with
svcSetAlarmCallback(), that it was within the same process (not thread or
child process of any kind) as the current process calling svcAlarm(). If this
function is not used, it is the application’s responsibility to create its own alarm by
issuing sleep() and kill() commands to the correct process ID.
Prototype
void svcAlarm(unsigned int secs)
Parameters
secs
Number of seconds to wait before SIGALRM signal is issued.
MX800 SERIES PROGRAMMERS GUIDE
167
S ERVICE F UNCTIONS
svcGetPortStatus()
svcGetPortStatus()
The svcGetPortStatus() function returns the following information regarding
the port:
NOTE
The Mx800 series terminal does not support the detection of parity errors on the
COM ports due to the limitations of the ARM processor.
Prototype
struct vficomErrCounts *svcGetPortStatus(int inFd, int *buf)
Parameters
inFd
The file descriptor associated with the open port device.
buf
4 integer buffer used to return the port signal status information
Return Values
buf[0]
Number of received bytes pending in its input queue.
buf[1]
Number of available (free) bytes in its output queue. This is different
than the function svcGetOutQ() where it returns the number of bytes
pending in the output queue.
buf[2]
Signal information as defined as follows:
(all bits for corresponding signals are set if hardware supports signal for
that port and the signal is detected to be asserted. Otherwise, bit is not
set.)
buf[3]
168
MX800 SERIES PROGRAMMERS GUIDE
0x80
set if DTR detected
0x40
set if RTS detected
0x20
set if CTS detected
0x10
set if Ring Indicator present
0x08
set if Carrier Detect (CD) present
0x04
set if DSR detected
0x02
Reserved
0x01
Reserved
Reserved
S ERVICE F UNCTIONS
svcGetPortStatus()
The return value of svcGetPortStatus() is a pointer to vficomErrCounts
structure which is defined in vficom.h as the following:
struct vficomErrCounts {
int frame_err;
int over_err;
int parity_err;
};
The pointer to this structure will contain the error counts for the port described by
the file descriptor passed into the function. The error counts provided are for
framing, overrun and parity errors detected for that port. The counts provided are
the total errors counted for that port since it was opened which allows the
application to track if any new errors were detected for that port since the last time
this function was called.
MX800 SERIES PROGRAMMERS GUIDE
169
S ERVICE F UNCTIONS
svcGetInQ()
svcGetInQ()
The svcGetInQ() function returns the number of bytes pending in the port’s
input queue.
Prototype
int svcGetInQ(int inFd)
Parameters
inFd
170
MX800 SERIES PROGRAMMERS GUIDE
The file descriptor associated with the open port device.
S ERVICE F UNCTIONS
svcGetOutQ()
svcGetOutQ()
The svcGetOutQ() function returns the number of bytes pending in the port’s
output queue.
Prototype
int svcGetOutQ(int inFd)
Parameters
inFd
The file descriptor associated with the open port device.
MX800 SERIES PROGRAMMERS GUIDE
171
S ERVICE F UNCTIONS
svcExpand()
svcExpand()
Prototype
int svcExpand(char *inFile, int keepinFile, char *uowner)
Parameters
inFile
Pointer to a string containing the name of the file to expand. This file
should be in a tar format with or without either GNU zipped or binary
zipped compression. The file should be named appropriately with the
correct extension following customary Linux naming conventions
regarding tar files. Either .TAR for a regular tar archive or .TGZ or
.GZ for a GNU zipped format. For a binary zipped format, it should
have the extension .BZ2. These are the only formats supported at
this time. The file extension is not case sensitive.
keepinFile
A flag to indicate whether to keep the tar file after expansion takes
place. Default is to delete the tar file.
uowner
Pointer to a string containing the name of the user that the expansion
is taking place for. If an application calls this function, then it should
be set to the user name of the user that the application is running
under. If this file is called from System Mode via a download, then
currently, the user will be set to the primary user: usr1.
The svcExpand() function first checks if the inFile parameter contains a valid
TAR formatted file as described above under inFile description. If it does, then
all files are extracted in the users home directory for the user specified in the
uowner parameter. After all files are extracted, all non-root owned files and
directories within the user’s home directory are set to the user’s ownership.
Permissions are set for each file to what they were at the time the file was
archived.
172
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcUsbStorPresent()
svcUsbStorPresent()
The svcUsbStorPresent() function determines how many USB storage/
memory devices are currently plugged into the USB host port, mounted properly
and ready for access. If so, then it sets a value of 1 in each byte of the array
pointed to by usbStorDevPresent. A value of 1 indicates that a device is
mounted on that particular directory and ready for access. Each byte of the array
corresponds to the directories as follows:
/mnt/usbstor1 = usbStorDevPresent[0]
/mnt/usbstor2 = usbStorDevPresent[1]
/mnt/usbstor3 = usbStorDevPresent[2]
/mnt/usbstor4 = usbStorDevPresent[3]
The files can be accessed at these mount points if there is a value of 1 in the
corresponding array byte.
Prototype
int svcUsbStorPresent(char *usbStorDevPresent)
Parameters
usbStorDevPresent
Pointer to char of at least 4
allocated bytes
Return Values
Return value is 0 on success, -EINVAL if invalid parameter passed.
MX800 SERIES PROGRAMMERS GUIDE
173
S ERVICE F UNCTIONS
COM3 Service Functions
COM3 Service
Functions
The COM3 service functions are for tuning and configuring the communication
processor used on the COM3 port. These functions were brought up to the API
level in case there is a need to use them directly in an application for a special
architecture/configuration. Otherwise, the following COM3 service functions
should not have to be used directly by an application. All other API calls that
require COM3 configuration/tuning, use these functions and do the necessary
work for the application.
Depending how the COM3 port is opened, the required configuration is done
automatically as long as the Mx800 series of terminals API functions are utilized. It
is only a rare occasion or special architecture that may require special tuning
where the default settings may have to be changed directly by the application
using these service functions.
All COM3 service functions operate strictly on the communication processor and
from the perspective of the communication processor. These service functions
have nothing to do with the operating system. For instance, flushing the COM3
buffer using the svcCOM3FlushRxBuf() does not flush the operating system
buffer, it flushes the remaining data from the communication processor buffer into
the OS buffers.
174
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3SetMode()
svcCom3SetMode()
The svcCom3SetMode() function allows the application to manually set the
mode for the COM3 port according to what kind of port COM3 should function as.
If ecrOpen() is used, this is done automatically according to the ECR
environment variables. If open() is used, then this call should be used to set the
correct desired mode for the port. To change modes, it is required to first close the
channel with the MODE_CLOSE_CHANNEL setting and then set the mode to the
new desired mode.
Prototype
short svcCom3SetMode(int fd, char ioctlMode)
Parameters
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
ioctlMode
Value indicating the mode to set the port to as defined as follows:
MODE_CLOSE_CHANNEL
Port is set to not valid mode
MODE_R232_INT
RS232 mode
MODE_R485_INT
RS485 mode
MODE_SIO_INT
SIO Tailgate mode
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
MX800 SERIES PROGRAMMERS GUIDE
175
S ERVICE F UNCTIONS
svcCom3ReqExtStatus()
svcCom3ReqExtStatus()
The svcCom3ReqExtStatus() function will return the value of the extended
status report into the buffer pointed to by esBuf. The extended status report is a 2byte value that indicates the configuration and handshake settings for the port.
This function returns 0 upon success and a negative value if unsuccessful. The
Extended Status report is defined as follows:
Table 13
Status Record Structure: <DevStat1> <DevStat2>
Entry
Size
Description
<DevStat1>
byte
Configuration status
<DevStat2>
byte
Handshake status
Where: DevStat1 = Configuration Status
Where:
Table 14
Bit
Mnemonic Description
b7
FAM Access mode
b6
b5
b4
b3
176
0
Polled access mode
1
On Demand access mode
FWDS Watchdog Status
0
Disabled
1
Enabled
FOPEN Channel status
0
Channel is closed
1
Channel is active
FRST Reset path
0
Reset via Host control
1
Reset via Watchdog event
FXDR External Device reset status
0
No device reset received
1
Device reest received
b2
* Reserved
b1
* Reserved
b0
* Reserved
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3ReqExtStatus()
Where: DevStat2 = Handshake Status
Where:
Table 15
Bit
Mnemonic Description
b7
RE Receive enable
b6
b5
b4
b3
b2
b1
b0
0
Receive disabled
1
Receive enabled
FHW Trransmit wait status
0
Transmit wait on handshake disabled
1
Transmit wait on handshake enabled
FAO Auxiliary Out state
0
Aux Out is in idle state
1
Aux Out is in Asserted state
FCO Control Out state
0
Control Out is in Idle state
1
Control Out is in Asserted state
FRO Ready Out state
0
Ready Out is in Idle state
1
Ready Out is in Asserted state
AI Auxiliary In status: (N/A)
0
Aux In is in Idle state
1
Aux In is in Asserted state
CI Control In status: (CTS)
0
Control In is in Idle state
1
Control In is in Asserted state
RI Ready In status: (N/A)
0
Ready In is in Idle state
1
Ready In is in Asserted state
Prototype
short svcCom3ReqExtStatus(int fd, char *esBuf)
MX800 SERIES PROGRAMMERS GUIDE
177
S ERVICE F UNCTIONS
svcCom3ReqTallyInfo()
svcCom3ReqTallyInfo()
The svcCom3ReqTallyInfo() function allows the application to request the
Tally Information report which is comprised of a listing of counters that track ECR
events. This function returns 0 upon success and a negative value if
unsuccessful. The Tally Record report is defined as follows:
Tally Record Structure: <Ntallies> <Id> <Count> . . . <Id> <Count>
The tally record is a listing of the current tally counters. The record is open ended
and allows for additional tally counters to be added. Each tally count is uniquely
identified and is followed with a 16 bit binary value in MSB/LSB order. The tally
counters are up counters that increment with each detected event and will clamp
at 0xFFFF to indicate overflow.
Where:
Table 16
Tally Record
Entry
Size
Range
Description
<Ntallies>
byte
00 – FF
Number of tally entries in record. Current
firmware version limits this field to 5 and
always reports 5 entries. This field has a
range of 00-FF if needed to change
number of entries reported. A zero tally
count would indicate that no list follows.
<Id>
byte
00 – FF
FF Tally code identifier (see table below)
<Count>
word
0000 – FFFF
16 bit tally count. Order is MSB/LSB.
Table 17
<ID>
Mnemonic
Description
1
ODP
Number of other device polls.
2
LDP
Number of local device polls.
3
MSE
Number of message structure errors.
4
SCE
Number of sequence count errors.
5
POR
Number of power on reset commands
Prototype
short svcCom3ReqTallyInfo(int fd, char *tiBuf)
Parameters
178
fd
file descriptor returned when opening a serial port with either open()
or ecrOpen().
*tiBuf
pointer to a buffer that will hold the Tally Information report.
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3ResTallyData()
svcCom3ResTallyData()
The svcCom3ResTallyData() function resets all the tally counters to zero.
Prototype
short svcCom3ResTallyData(int fd)
Parameters
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
MX800 SERIES PROGRAMMERS GUIDE
179
S ERVICE F UNCTIONS
svcCom3ReqFirmVers()
svcCom3ReqFirmVers()
The svcCom3ReqFirmVers() function requests the current firmware version
within the communication processor. This call can be used to verify the current
firmware version. The function will write the firmware version string to the log file
and will also return the string in the buffer pointed to by *fwBuf. It is a null
terminated string that can be printed or displayed.
Prototype
short svcCom3ReqFirmVers(int fd, char *fwBuf)
Parameters
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
*fwBuf
Pointer to a buffer that is at least 16 bytes in size, that will hold the nullterminated current communication processor firmware version string.
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
180
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3SetDeviceAddr()
svcCom3SetDeviceAddr()
The svcCom3SetDeviceAddr() function allows the application to set the ECR
device address that the terminal is going to respond to. This is valid only in COM3
ECR tailgate mode: MODE_SIO_INT. The ECR device address must be set before
the Mx800 series terminal will respond to a poll from the ECR. If the terminal is not
in MODE_SIO_INT, the device address will still be set successfully, but will be
ignored.
Prototype
short svcCom3SetDeviceAddr(int fd, char da)
Parameters
fd
File descriptor returned when opening a serial port with ecrOpen().
da
A 1 byte value to set the ECR device address to. The legal values are
defined as follows:
SIO_DEVADDR_64
SIO_DEVADDR_65
SIO_DEVADDR_65
SIO_DEVADDR_69
Return Values
This function returns 0 upon success and a negative value if unsuccessful in
setting address.
MX800 SERIES PROGRAMMERS GUIDE
181
S ERVICE F UNCTIONS
svcCom3SetECLevel()
svcCom3SetECLevel()
The function svcCom3SetECLevel() function sets the ECR engineering change
level that is reported to the ECR in response to the Request EC command. This
value is logged by the ECR and may be used to invoke version specific drivers.
The legal values are 00-FF and the default is FF corresponding to an OEM
device.
Prototype
short svcCom3SetECLevel(int fd, char ec)
Parameters
fd
File descriptor returned when opening a serial port with ecrOpen().
ec
A 1 byte value to set the ECR engineering change level.
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
182
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3SetHandshake()
svcCom3SetHandshake()
The svcCom3SetHandshake() function sets the handshake byte to the value
indicated.
Return Values
This function returns 0 upon success and a negative value if unsuccessful. The
value of the handshake control byte can be read using the
svcCom3ReqExtStatus() function.
Each bit of the handshake value indicates a specific state defined as follows:
Where:
Table 18
Bit
Mnemonic Description
b7
RE Receive enable
b6
b5
b4
b3
0
Receive disabled
1
Receive enabled
HW Handshake wait
0
Transmit unconditionally
1
Transmit waits on Handshake
AO Auxiliary Out (N/A)
0
Aux Out is in Idle state
1
Aux Out is in Asserted state
CO Control Out
0
Control Out is in Idle state (RTS)
1
Control Out is in Asserted state (RTS)
RO Ready Out (N/A)
0
Ready Out is in Idle state
1
Ready Out is in Asserted state
b2
* Reserved
b1
* Reserved
b0
* Reserved
MX800 SERIES PROGRAMMERS GUIDE
183
S ERVICE F UNCTIONS
svcCom3SetHandshake()
Prototype
short svcCom3SetHandshake(int fd, char hs)
Parameters
184
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
ec
A 1 byte value that indicates the handshake control.
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3FlushRxBuf()
svcCom3FlushRxBuf()
The svcCom3FlushRxBuf() function allows the application to manually flush
the receive buffer internal to the communication processor. This command is
meaningful only in RS232 mode: MODE_R232_INT.
Prototype
short svcCom3FlushRxBuf(int fd)
Parameters
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
MX800 SERIES PROGRAMMERS GUIDE
185
S ERVICE F UNCTIONS
svcCom3SetRxRecThresh()
svcCom3SetRxRecThresh()
The svcCom3SetRxRecThresh() function allows the application to set the
receive record threshold (RRT). This threshold is used to set the minimum size of
receive records returned to the host from the communication processor. This
command is not valid in COM3 tailgate mode: MODE_SIO_INT and has no effect if
used in this mode. The value can be in the range of 01-FF and defaults to decimal
value of 96. If this value is set too large then a loss of data can occur due to the
time required to process the larger receive record. If the value is set too small,
then a contention for resources could occur due to the time required to process
the interrupt for each receive record. A value of 0 is not allowed as this would
effectively shut off reception of all data. This value, in conjunction with the Buffer
Flush Interval (BFI), controls how received data is released to host driver for
processing.
Prototype
short svcCom3SetRxRecThresh(int fd, char rrt)
Parameters
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
rrt
a 1 byte value that indicates the receive record threshold to be set.
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
186
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
svcCom3SetBufFlushInt()
svcCom3SetBufFlushInt()
The svcCom3SetBufFlushInt() function allows the application to manually
set the buffer flush interval. This value indicates when a record that is less in size
than the Receive Record Threshold is to be released to the host. It sets the
maximum latency, in milliseconds, for receive characters to reside in the
communication processor receive buffer before a record is released. This function
is not valid in tailgate mode: MODE_SIO_INT and will have no effect if used in this
mode. The BFI value is automatically set to the optimum value by the Mx800
series terminal according to the baud rate and the RRT values. This function
should only be used to manually override the automatically calculated value.
Prototype
short svcCom3SetBufFlushInt(int fd, char bfi)
Parameters
fd
File descriptor returned when opening a serial port with either open()
or ecrOpen().
rrt
A 1 byte value that indicates the buffer flush interval to be set.
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
MX800 SERIES PROGRAMMERS GUIDE
187
S ERVICE F UNCTIONS
svcCom3Polled()
svcCom3Polled()
The svcCom3Polled() function allows the application to check if the ECR
address the Mx800 series terminal is being polled by the ECR. The terminal must
be configured for tailgate mode and set to a particular address. This function when
called, will return the number of polls that occurred since the last time it was
requested. The internal poll count is only updated at most, once per second. So, if
this function is called more than that frequency, it will return the last value
reported. This same function is used during a System Mode ECR Download in
tailgate mode to check if the terminal is being polled. If the terminal is being polled
by the ECR, then the message POLLED will be displayed on the Mx800 series
terminal screen.
Parameters
int svcCom3Polled(int fd)
Parameters
fd
188
MX800 SERIES PROGRAMMERS GUIDE
File descriptor returned when opening a serial port with open() or
ecrOpen()
S ERVICE F UNCTIONS
svcGetSysMillisec(), svcGetSysMicrosec()
svcGetSysMillisec(), svcGetSysMicrosec()
Returns the number of time units (microseconds or milliseconds) elapsed since
the Epoch (Jan 1970 for Linux).
The functions may be used for general timing purposes and are accurate to well
under 1 millisecond. The return type is unsigned long long to avoid rollover
problems until the year 2037 (because the underlying Linux calls return seconds
in a signed long).
Prototype
unsigned long long microsecSince01Jan1970 = svcGetSysMicrosec();
unsigned long long millisecsecSince01Jan1970 = svcGetSysMillisec();
MX800 SERIES PROGRAMMERS GUIDE
189
S ERVICE F UNCTIONS
enableProcessMonitor()
enableProcessMonitor()
Enabling a process monitor causes the system to periodically check the health of
the calling process. If the process has exited, the system will detect the failure and
force a system reboot. The purpose of monitoring a process is to prevent the
terminal from hanging if a bug or unexpected event occurs causing a critical
process to exit.
NOTE
•
A maximum of 50 processes can be monitored at any time.
•
If a process spawns processes the new processes will need to register
themselves if it is desired that they also be monitored.
WARNING If a process naturally exits or is replaced, it is up to the application to call
disableProcessMonitor() prior to exiting. Otherwise, the system will
interpret that a failure has occurred and will force a reboot.
Prototype
void enableProcessMonitor(void)
190
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
disableProcessMonitor()
disableProcessMonitor()
Disabling the process monitor causes the system to stop the periodic check of the
health of the calling process. If the process has exited, the system will detect the
failure and force a system reboot. The purpose of monitoring a process is to
prevent the terminal from hanging if a bug or unexpected event occurs causing a
critical process to exit.
Prototype
void disableProcessMonitor(void)
MX800 SERIES PROGRAMMERS GUIDE
191
S ERVICE F UNCTIONS
enableButtonSig()
enableButtonSig()
Calling enableButtonSig() causes the signal SIGINT to be sent to the
registering process when the recessed button is pressed for less than two
seconds.
Sending a SIGINT to a process when the recessed button is pressed is done so
that the application can implement a setup/configuration mode. The application
receiving the SIGINT can drive the GUI as desired.
NOTE
192
If the user presses the recessed button for longer than two seconds, the normal
system mode password display will be called.
MX800 SERIES PROGRAMMERS GUIDE
S ERVICE F UNCTIONS
disableButtonSig()
disableButtonSig()
Calling disableButtonSig() disables the signal SIGINT from being sent to the
calling process when the recessed button is pressed for less than two seconds.
MX800 SERIES PROGRAMMERS GUIDE
193
S ERVICE F UNCTIONS
disableButtonSig()
194
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 6
System Mode
System Mode for
the Mx800 series
of Terminals
The Mx800 series of terminals’ System Mode will be a departure from previous
products in that a graphical user interface will be used for presentation. The
System Mode idle display will have pertinent terminal configuration and status
information on the top and bottom border of the display and task driven icons in
the center.
Title Area
Date / Time
The idle screen icons will be used to access critical features such as:
Information
Detailed Hardware / Software Configuration Display. Buttons
support the display of the current Cable, COM3 firmware and
Ethernet status.
Configure
Setup Communications, Environment variables, Set time & date.
ECR configuration allows Feature C or Tailgate configuration.
USB configuration allows the selection of USB device mode.
TTY enables a serial console on COM1 at 115200 baud. Audio
configuration allows the setup of the default volume, bass and
treble. Touch panel calibration and default backlight brightness
can also be configured.
Diagnostics
Refer to the Mx800 series Reference Manual, VDN 23754.
MX800 SERIES PROGRAMMERS GUIDE
195
S YSTEM M ODE
System Mode for the M x 800 series of Terminals
File Transfer
Direct load, ECR download, FTP.
File Manager
Supports launching the application associated with *GO and
rebooting the system.
Security
VeriShield Security, displays the certificate IDs and serial
numbers.
Key Status – Displays the status of the 10 master key and 3
DUKPT key slots, Key injection permits security key loading,
and password management allows the user and key loading
passwords to be changed.
196
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 7
Root File System
The Embedded Linux OS is much more than a kernel. A number of significant
applications and modules are required to complete the system. These
applications, libraries and driver modules reside in the root file system.
1 BusyBox - Combines tiny versions of many common UNIX utilities into a single
small executable. It provides replacements for most of the utilities you usually
find in GNU fileutils, shellutils, etc. The utilities in BusyBox generally have
fewer options than their full-featured GNU cousins; however, the options that
are included provide the expected functionality and behave very much like
their GNU counterparts. BusyBox provides a fairly complete environment for
any small or embedded system. BusyBox has been written with sizeoptimization and limited resources in mind. It is also extremely modular so you
can easily include or exclude commands (or features) at compile time. This
makes it easy to customize your embedded systems. To create a working
system, just add some device nodes in /dev, a few configuration files in /etc,
and a Linux kernel.
See: http://www.busybox.net/about.html
2 uClibc – A C library for embedded Linux. uClibc (aka µClibc/pronounced yewsee-lib-see) is a C library for developing embedded Linux systems. It is much
smaller than the GNU C Library, but nearly all applications supported by glibc
also work perfectly with uClibc. Porting applications from glibc to uClibc
typically involves just recompiling the source code. uClibc even supports
shared libraries and threading.
See: http://www.uclibc.org/about.html
MX800 SERIES PROGRAMMERS GUIDE
197
R OOT F ILE S YSTEM
Directory Structure
Directory
Structure
Linux / Unix has a long history with respect to the root file system directory
structure. This document will not attempt to explain this history. If you are
interested, see: http://www.pathname.com/fhs/.
/
bin
boot
dev
etc
home lib
mnt
proc root
initrd
usr1
Organization of
Files in the Standard
Directory Structure
198
usr
sbin
var
sys
usr2
bin
sbin
/bin
stores essential binaries (programs) needed when booting the
system or working in single user mode to maintain the system.
/boot
stores kernel images and boot configuration files.
/dev
stores device special files used to access hardware devices.
/etc
stores system configuration files.
/home
stores the home directories for the individual users.
/initrd
not used.
/lib
stores library modules used by the commands.
/mnt
a mount point for other storage devices.
/proc
a pseudo file system for conveying data about processes.
/root
home directories for root.
/sbin
stores commands required to administer the system.
/sys
system resource configuration.
/usr
used for programs, libraries, documentation, etc used by normal
users.
/var
stored system data that varies or changes frequently such as
system logs, etc.
MX800 SERIES PROGRAMMERS GUIDE
R OOT F ILE S YSTEM
Directory Structure
User Space Base User space directories will be placed under /home.
Directory Structure
/home
|
---- usr1
|
---- usr2
|
---- usr x
The following base directory tree will be defined under each /user:
/home
|
---- usr1
|
---- crt
|
---- vss
|
---- os
NOTE
Each user may define additional subdirectories for their use. All subdirectories
are created as needed and may not exist on a terminal by default
User Space and Similar to the Verix OS, the Mx800 series of terminals will support the concept of
Security directory ownership. On the Mx800 series of terminals, the primary application will
reside in the subdirectory: /home/usr1. Secondary applications will reside in /
home/usr2, /home/usr3, …
File signing limitations will exist such that each user space subdirectory requires
separate authority. The system will support up to eight users. Each user is allowed
multiple executables.
NOTE
Users will only have privilege to create/write files under their base directory. For
example usr1 will only have privilege to write files under /home/usr1.
MX800 SERIES PROGRAMMERS GUIDE
199
R OOT F ILE S YSTEM
Directory Structure
200
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 8
USB - Device / Host
The Mx800 series supports two USB ports. One port (on the multi-port cable)
supports either the host or device function. The multi-port cable determines the
type of USB port. The second USB port is always the host and is available on the
I/O module interface.
USB Device
When acting as a USB device, the Mx800 series of terminals conforms to the
Linux USB gadget framework. See http://www.linux-usb.org/gadget/
The two devices that the Mx800 series of terminals will emulate are:
Serial
This exposes a tty style serial line interface, usable with Minicom and
similar tools. (There’s no serial console support at this time.) Most Linux
hosts can talk to this using the generic usb-serial driver. The latest versions
of this driver implement the CDC ACM class, as might be implemented by
cell phones or other modems. This driver works with the MS Windows
usbser.sys driver, the Linux cdc-acm driver, and many other USB Host
systems.
The Mx800 series terminal SDK includes an .inf file and usbser.sys
required by Windows 2000/XP to interface with the USB serial device. On
the Mx800 series terminal, the application can open COM5 or /dev/ttygser
device. DDL supports application download over serial USB. To enable the
USB Serial driver on the Mx800 series terminal, use the System Mode
Configure USB display or set the environment variable *USBDEVICE=1.
RNDIS
When talking to MS Windows hosts, RNDIS is used. RNDIS is Microsoft’s
analogue of CDC Ethernet, with complex frame capsulation and its own
internal RPC protocol. (Clicking on this link, http://www.microsoft.com/
whdc/device/network/NDIS/usbrndis.mspx, may help you and a partial
protocol specification is available. For example, some requests from
Windows 2000 and XP are undocumented.) Use the Documentation/
usb/linux.inf file (convert to DOS CRLF format) to install the driver.
The driver is bundled in XP and the URL in linux.inf says where to get
Microsoft’s drivers for older Windows releases. For some step-by-step
instructions with WinXP screenshots, see http://
www.gumstix.org/tikiwiki/tiki-index.php?page=Windows_XP_usbn showing
one way to use that “linux.inf” file. Do not forget to read the comments there,
explaining how to shortcut past some needless complications in those
instructions.
MX800 SERIES PROGRAMMERS GUIDE
201
USB - D EVICE / H OST
USB Host
USB Host
The Mx800 series of terminals supports USB host functionality and can run
specific drivers for a multitude of different devices that can be plugged into the
Mx800 series terminal. Currently, the Mx800 series of terminals has been tested
with the following devices:
•
USB Keyboard and Mice (HID Class)
•
USB Memory Sticks and hard drives - Using MSDOS compatible FAT32/VFAT
format
Specific support for most USB devices requires the necessary drivers to be
manually loaded into the system and manually configured. Support for USB
memory and mass storage devices has been built into the Mx800 series unit and
requires little or no manual intervention. This described in more detail in the next
section.
IBM AT keyboard and scanners that use the AT keyboard scan codes are also
supported under the Mx800 series’ USB host. If a USB keyboard or a scanner is
plugged into the Mx800 series USB host port, the necessary HID drivers to
support the device are automatically loaded. To open and read data from these
devices, the API function calls: inputOpen(), inputRead() and
inputClose() should be used. Detailed explanation of these functions are
described in more detail under their respective sections. USB HID device support
is described below.
NOTE
USB host is only supported on specific Mx800 series cables. Currently, these
cables are the Mx800 series of terminals:
- Red cable P/N 23739-02
- Green cable P/N 23740-02
USB Mass Storage The Mx800 series of terminals has built-in automatic support for USB mass
and Memory storage and memory devices. The unit will support a single memory device
Devices plugged into the USB host port on a Mx800 series terminal cable or up to 4
memory devices at any one time plugged in via a USB hub. The Mx800 series
terminal does not support more than 4 USB memory/mass storage devices at this
time, but they can be plugged into the unit in any configuration of single or multiple
hubs. The Mx800 series of terminals will automatically detect any memory/mass
storage device plugged into the unit and will automatically mount the device on
one of the 4 directories located under the /mnt directory. The directory names for
the memory devices are:
• /mnt/usbstor1
• /mnt/usbstor2
• /mnt/usbstor3
• /mnt/usbstor4
202
MX800 SERIES PROGRAMMERS GUIDE
USB - D EVICE / H OST
USB Host
Each directory will be used in order as the devices are plugged into the unit. If a
device is removed, it is automatically unmounted from the directory mount point
and the data on it is no longer accessible. While the device is plugged in, the data
can be accessed by an application. The application can determine if a memory/
mass storage device has been detected, mounted properly, and is ready to be
accessed by making a call to the function svcUsbStorPresent().
This function call is described in greater detail in Chapter 5. It expects a pointer to
a char which can hold at least 4 bytes. When the function is called, it determines
which mount points have a device currently plugged in and mounted on its
directory and available for access. It will return the pointer with a value of 1 for
each device that is mounted and a 0 for each device that is not. All files located on
the device can be accessed at that mount point. For example, if the function
returns the values: 0, 1, 0, 1
then,
/mnt/usbstor1
does not have a usb memory/storage device plugged in and
mounted on this directory.
/mnt/usbstor2
does have a device plugged in and the files located on the
memory device can be accessed at this point.
/mnt/usbstor3
does not have a usb memory/storage device plugged in and
mounted on this directory.
/mnt/usbstor4
does have a device plugged in and the files located on the
memory device can be accessed at this point.
These directories exist on the terminal regardless if a device is detected and
mounted on them or not. The application must be aware not to write to a directory
without the device being present. If this is done then the files will remain on the
terminal in the directory written to instead of going to the memory device as the
application intended. It is only when the device is present as indicated by the
svcUsbStorPresent() function, that a file can be written to a memory device
correctly where the file will remain on the memory device and not the terminal.
NOTE
USB device detection is performed by plug and play hardware and software. It
typically takes approximately 10 seconds for all devices to be detected,
enumerated, and initialized before available for use. Applications and users
should be aware of this delay before a device can be accessed every time a
device is plugged in or removed from the Mx800 series terminal.
NOTE
USB host can be reset by removing all plugged in devices and waiting for
approximately 10-15 seconds. All entries, environment variables, and mounted
devices will be removed and cleared. USB host port will then be ready to accept
newly inserted devices at that point.
MX800 SERIES PROGRAMMERS GUIDE
203
USB - D EVICE / H OST
USB Human Interface Device (HID) Support
USB Human
Interface Device
(HID) Support
The Mx800 series terminal also has built in USB HID support for some devices
through the Linux kernel Input Event module. When a HID is plugged into the USB
Host port, it is automatically detected and the appropriate USB HID and event
drivers are loaded. It is then possible to open, read/write, and close these devices
from an application. Currently, the Mx800 series of terminals either partially or fully
supports HID’s:
204
USB Host Keyboard
This enables an event interface to capture keys pressed on a
USB host keyboard. The Mx800 series of terminals only
supports IBM AT keyboard scancode set 1 at this time. Other
scancode sets 2 and 3 are not supported. There is currently
full support for this device where it can be opened, read, and
closed using the Mx800 series of terminals’ Input Library API.
This library consists of functions: inputOpen(),
inputRead(), and inputClose(). These are further
described in Chapter 12.
USB Host Scanner
This enables an event interface to capture scanned data from
a USB handheld scanner. The scanner must utilize the IBM
AT keyboard scancode set 1. There is currently full support for
this device where it can be opened, read, and closed using the
Mx800 series Input Library API. This library consists of
functions: inputOpen(), inputRead(), and
inputClose(). These are further described in Chapter 12.
USB Host Mouse
This enables an event interface that an application can use to
capture events from a USB mouse. There is currently support
to open and close the event device, but is not fully supported
at this time. Further implementation of a complete API to read
events from the mouse may be done some time in the future.
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 9
TCP/IP Ethernet
The Mx800 series terminal supports TCP/IP networking on the Ethernet port. The
network configuration and program APIs are contained in this chapter. The Mx800
series fully support the Linux sockets interface for client and server network
programming. The networking API is contained in the svc.h header file and the
libvfisvc shared library.
Networking is currently supported only on the Ethernet port, the eth0 device.
Network
Configuration
Configuration variables are read for network configuration in bringing the interface
up at boot time and user control.
Network The following table of configuration variables is read by the system on power up/
Configuration reboot and in bringing the interface up. Either the *DHCP or *IFCONFIG
Environment environment variable must be defined to bring up the eth0 network interface.
Variables
These configuration variables must be set within the usr1 account.
Table 19
Variable Name
Values
Definition
*DHCP
1
If *DHCP is present and the system
supports ethernet, then it will attempt
to initialize its connection via DHCP.
*DNS1
IP Address in the form
xxx.xxx.xxx.xxx
If not DHCP, DNS1 is used as the
name server IP address.
*DNS2
IP Address in the form
xxx.xxx.xxx.xxx
If not DHCP, DNS2 is used as the
name server IP address.
*IFCONFIG
Per Linux – No need to
set MAC address as the
system will do this for
you.
If not DHCP, use *IFCONFIG to set
the following parameters:
Typically used:
• broadcast (optional)
• host static IP address
• netmask
“eth0 xxx.xxx.xxx.xxx
netmask xxx.xxx.xxx.xxx”
*GATEWAY
IP Address in the form
xxx.xxx.xxx.xxx
Use to define the address of the
gateway (router).
*TELNET
1
If *TELNET is present and the system
supports Ethernet, then it will start the
Telnet server daemon.
MX800 SERIES PROGRAMMERS GUIDE
205
TCP/IP E THERNET
netUP()
netUP()
Activates the Ethernet network interface eth0 for sending and receiving.
NOTE
This function uses the Network Configuration environment variables and either
the *DHCP or *IFCONFIG variable must exist. *DHCP takes precedence if both
variables exist
Prototype
int result= netUp(void)
Return Values
206
0
Success
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
TCP/IP E THERNET
netDown()
netDown()
Deactivates the Ethernet network interface eth0. This also deletes the routing
entries for this interface.
Prototype
int result= netDown(void)
Return Values
0
Success
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
207
TCP/IP E THERNET
netGetConfig()
netGetConfig()
Returns the network configuration parameters of the eth0 network interface. The
network interface must be up.
Prototype
int result = netGetConfig(net_conf_t *net)
Parameters
net
Pointer to the network configuration structure to be filled:
typedef struct {
int dhcp;
char MAC[18];
char ipaddr[16];
char netmask[16];
char gateway[16];
char dns1[16];
char dns2[16];
} net_conf_t;
net_conf_t members
Description
short dhcp
1=DHCP, 0=Static
char MAC[18]
format “xx:xx:xx:xx:xx:xx”
char ipaddr[16]
format “xxx.xxx.xxx.xxx”
char netmask[16]
format “xxx.xxx.xxx.xxx”
char gateway[16]
format “xxx.xxx.xxx.xxx”
char dns1[16]
format “xxx.xxx.xxx.xxx”
char dns2[16]
format “xxx.xxx.xxx.xxx”
Return Values
208
0
Succes, interface is up.
<0
Error, probably network interface is down.
MX800 SERIES PROGRAMMERS GUIDE
TCP/IP E THERNET
netLinkStatus()
netLinkStatus()
Returns the link status of the specified network interface.
Prototype
int result = netLinkStatus(void)
Return Values
1
Link is up.
0
Interface down or Ethernet cable is unplugged.
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
209
TCP/IP E THERNET
getSysctl()
getSysctl()
Returns the value of the specified kernel parameter.
Prototype
int result = getSysctl(char * varSysctl)
Return Values
210
1
Link is up.
0
Interface down or Ethernet cable is unplugged.
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
TCP/IP E THERNET
Supported Network Programs
Supported
Network
Programs
The Mx800 series of terminals API includes support for common networking
programs such as ping and FTP file transfers.
For FTP file transfers, the FTP server must support passive mode for the data
socket connection and the file transfers are always in binary mode. The FTP
server must support the following FTP commands:
•
USER
•
PASS
•
TYPE I
•
PASV
•
RETR
•
CWD
•
STOR
•
QUIT
MX800 SERIES PROGRAMMERS GUIDE
211
TCP/IP E THERNET
netPing()
netPing()
Tests whether the remote host is reachable.
NOTE
This program sends an ICMP message to the remote host asking for
acknowledgement.
Prototype
int result = netPing(char *host)
Parameters
host
Pointer to remote host either in the “xxx.xxx.xxx.xxx” IP address
format or fully qualified domain name.
Return Values
212
0
Success
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
TCP/IP E THERNET
ftpGet()
ftpGet()
Transfers the file from the FTP server to the terminal.
NOTE
This function logs in to the FTP server, retrieves the file, and logs off.
Prototype
int result = netGetConfig(net_conf_t *net)
Parameters
net
Pointer to the FTP parameter structure.
typedef struct{
char ftpHost[32];
char port[8];
char userID[32];
char password[32];
char localFile[64];
char
remoteFile[64];
char errorMsg[64];
} ftp_parm_t;
ftpHost
In the “xxx.xxx.xxx.xxx” IP
address format or the fully
qualified domain name format
ftp.site.com
port
FTP port. Defaults to 21 if not
specified.
userID
FTP user name
password
FTP password
localFile
Local file name, with directory
path (relative to “/home/
usr1/”)
remoteFile
Remote file name:
• For ftpGet(), this is the
directory pathname and
filename.
• For ftpPut(), this is the
directory pathname only.
errorMsg
Returns the verbose error
message
Return Values
0
Success, network interface is up.
<0
Error, probably network interface is down.
MX800 SERIES PROGRAMMERS GUIDE
213
TCP/IP E THERNET
ftpPut()
ftpPut()
Transfers a file from the terminal to the FTP server.
NOTE
This function logs in to the FTP server, sends the file to the server, and logs off.
Prototype
int result = ftpPut(FTP_parm_t *ftp)
Parameters
ftp
Pointer to FTP parameter structure (see ftpGet()). The
remoteFile field is the directory pathname only. The resultant
filename is the same as the source filename.
Return Values
214
0
Success
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 10
IPP Legacy Library
IPP Support for This chapter describes the IPP support functions ported from the TXO platforms
the Mx800 series (Omni 7xxx):
of Terminals • ipp_getpin()
• ipp_read()
• ipp_abort()
• ipp_diag()
•
ipp_mac()
• select_key_mgmnt()
• get_key_mgmnt()
These functions are actually a front-end to the IPP functions described in Chapter
4. All the limitations of the IPP emulation listed in Chapter 4 also apply to this set
of functions.
In addition, there are several differences between the Omni 7xxx functions and
the Mx800 series of terminals functions due to the underlying architecture:
•
The PIN exhaustion protection is implemented differently (See Note on the
PIN session timeout). On the Mx800 series of terminals, a token must be
available when starting the PIN session. If no token is available the
ipp_getpin() function returns -2. In the Omni 7xxx, a token must be
available when returning the encrypted PIN block. The ipp_read() function
returns -5 until one gets available.
•
On the Mx800 series terminal, some of the parameter checking is done
beforehand. For instance ipp_getpin() returns -3 for an invalid minimum
PIN length, invalid maximum PIN length, invalid master key number or invalid
working key string. On the Omni 7xxx, those errors are reported by the
ipp_read() function.
•
The Mx800 series of terminals’ ipp_read() return value does not go through
all the intermediate states than the Omni 7xxx’s does. For instance, value -3, 4 and -5 are never returned by ipp_read() on the Mx800 series of terminals.
MX800 SERIES PROGRAMMERS GUIDE
215
IPP L EGACY L IBRARY
IPP Support for the M x 800 series of Terminals
•
There is no IPP trap mechanism on the Mx800 series of terminals.
•
The Interac mode support functions are not implemented on the Mx800 series
of terminals. Interac support is done through Security Script.
All legacy IPP functions are defined in the header file ippleg.h.
Applications must link with the libvfileg.so and libvfisec.so libraries by
using -lvfileg and -lvfisec.
Applications must call ippOpen() before using the legacy IPP functions listed
below.
216
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
ipp_getpin()
ipp_getpin()
This command passes the appropriate parameters to define PIN entry.
Prototype
result = ipp_getpin(key_type, disp_line, min_pin_len, max_pin_len,
zero_pin_ok, max_time, pan, working_key, master_key);
int result, key_type, max_time, master_key;
char dsp_line, min_pin_len, max_pin_len, zero_pin_ok,
*working_key, *pan);
Parameters
key_type
0 for Master Key Management, 1 for DUKPT
dsp_line
Not used on the Mx800 series of terminals.
min_pin_len
minimum length of the PIN (4 .. max_pin_len)
max_pin_len
maximum length of the PIN (min_pin_len ..12)
zero_pin_len
0 - not permitted, 1 - permitted
max_time
1...300 max time in seconds for timeout abort
pan
pointer to Personal Account Number
8...19 characters - null terminated
working_key
master_key
1DES
Mode
16 characters - null terminated in case of Master Key
Session, ignored in case of DUKPT.
3DES
Mode
120 characters - null terminated, GISKE data block
in case of Master Key Session, ignored in case of
DUKPT.
1 character: (0...9) in case of Master Key Session, (0...2) in case of
DUKPT to select DUKPT engine.
MX800 SERIES PROGRAMMERS GUIDE
217
IPP L EGACY L IBRARY
ipp_getpin()
Return Values
0
Successful
-1
PIN Entry Occurring
-2
Too many PIN entry requests in a short period - Retry later.
-3
Invalid parameter or IPP communication error.
Prior to issuing this command, the setSecurePINDisplayParameters()
function must be used to register the “PIN feedback” callback function and to load
the hotspot table. See SetSecurePINDisplayParameters().
Once this function is executed, the touch panel data is no longer accessible to the
application and it is routed directly to internal software. As each digit of the PIN is
entered, an event is echoed to the application through the callback function. Illegal
keys are ignored. Pressing [CLEAR] will abort the session
Encryption of the PIN is performed internally by the system hardware immediately
after the PIN is entered and [ENTER] is pressed. Raw PIN data is never made
available to the Application. After issuing this command, the ipp_read()
function must be used to collect the encrypted PIN information.
218
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
ipp_read()
ipp_read()
This function returns the encrypted PIN block generated by ipp_getpin().
Prototype
result = ipp_read(buffer, size);
intresult;
unsigned int size;
char *buffer;
Parameters
NOTE
buffer
User defined buffer in the application space where the information is to
be stored.
size
The number of bytes to be read.
The size parameter was defined in the Everest+ implementation but is not used
by this function. Recommend the size parameter be set to 0.
Return Values
NOTE
>0
Number of bytes read
0
IPP is idle
-1
Waiting for PIN entry
-2
PIN entry occurring
-6
Abort PIN entry by Timeout
-7
Abort PIN entry by Program
-8
Abort PIN entry by CLEAR key
-9
Abort with data
-10
IPP Communication Error
-11
IPP Command Error
-12
Zero PIN length Error
Some of the above events occur so quickly that it may not be possible to see
every status code.
If the return value is >0, the packet is interpreted as given below.
MX800 SERIES PROGRAMMERS GUIDE
219
IPP L EGACY L IBRARY
ipp_read()
For Master Session Key Management, the buffer contains the following packet:
STX
1H
Start of text, value 02h
packet type
2AN
value ‘71'
delimiter
1A
value '.'
Function key
1N
value 0 if function key feature not implemented
PIN length
2N
value 00 or 04 -12
PIN Block Format
2N
value 01 - format prior to encryption
Encrypted PIN
Block
16H
encrypted PIN
ETX
1H
End of text, value 03h
In case of an input error, the packet looks like:
STX
1H
Start of text, value 02h
packet type
2AN
value ‘71'
error code
1N
"1" = No Master Key
"2" = account / working key error
"3” = PIN length over Max
"4” = PIN length under Min / non decimal digit in PIN
"6" = Master Key Attributes error
"7” = KOF/GISKE Working Key Attributes error
ETX
1H
End of text, value 03h
For DUKPT Key Management:
STX
1H
Start of text, value 02h
packet type
2AN
value ‘73'
packet delimiter
1A
value '.'
00000
5N
value: ‘00000'
KSN
10-20H
Key Serial Number: Hex (Leading F's suppressed)
Presented only if PIN entered
Length is 0 if no PIN entered
220
Encrypted PIN
16H
The 64 bit encrypted PIN block represented as 16
hexadecimal digits.
ETX
1H
End of text, value 03h
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
ipp_read()
In case of an input error, the packet looks like:
STX
1H
Start of text, value 02h
packet type
2AN
value ‘73'
error code
1N
"1" = No key
"2" = key serial number error
"3” = PIN length over Max
"4” = PIN length under Min
"6" = Over 1 million transactions
error ETX
1H
End of text, value 03h
MX800 SERIES PROGRAMMERS GUIDE
221
IPP L EGACY L IBRARY
ipp_mac()
ipp_mac()
This function performs a MAC calculation on the user data and returns the
resultant value.
Prototype
return = ipp_mac(master_key, working_key, second_key, message,
message_length, result);
int return;
unsigned int message_length;
char master_key, second_key, *working_key, *message, *result;
Parameters
ASCII "0...9" selects master key number
master_key
working_key
1DES Mode
16 characters, null terminated
3DES Mode
20 characters, null terminated GISKE data
block
second_key
ASCII "0...9" selects second key number
message
message to calculate MAC on
message_length
max 3200, number of characters in message
result
buffer pointer to contain the resultant MAC value
Return Values
222
1
Successful
-1
Master Key Pointer Error
-2
Second Key Pointer Error
-3
Message length too large
-4
Wrong Block Size
-5
Communication Error
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
ipp_mac()
The resultant MAC value is placed in the users result buffer and is formatted as
follows:
Process code field
One character, indicates status
"0" = no error and MAC follows
MAC field
16 character MAC value
The message parameter is blocked into 32-byte blocks and a running calculation
is performed on each block. Maximum number of blocks = 100, so maximum
message length is 3200 bytes.
If the second_key parameter is non-zero then MAC generation starts with the
master_key and if the message is longer than 1 32-byte block, the final block will
be processed using the second_key for enhanced security.
MX800 SERIES PROGRAMMERS GUIDE
223
IPP L EGACY L IBRARY
ipp_abort()
ipp_abort()
This function aborts PIN collection.
Prototype
return = ipp_abort(void);
int return;
Return Values
0
Successfully aborted
-1
Failure to abort
On successful return, the Application gets control of the keyboard and display.
NOTE
If PIN collection is not running when this function is called, then a 0 is returned.
224
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
ipp_diag()
ipp_diag()
This function executes various IPP diagnostics. The application can use this
function to check information on the IPP firmware as well as perform 1DES test
encryptions.
Prototype
return = ipp_diag(test_type, result, master_key);
int
return, test_type, master_key;
char *result;
Parameters
Type of test that the user wants to perform:
test_type
0
ROM Checksum Test
1
Serial Number Test
2
ROM Version Number Test
3
Master/Session Encryption Test
4
DUKPT Encryption Test
result
Pointer to a buffer sufficient enough to hold the results. It must
be at least 17 bytes for tests 0-2 and at least 150 bytes for
tests 3-4.
master_key
Master key slot # to use when performing test #3.
DUKPT engine to use when performing test #4.
Return Values
0
Success
-1
Error
The result buffer will contain the following, according to the test_type
specified:
Table 20
Test_type
Result buffer
0
Buffer contains checksum
1
Serial number if present
2
Version number
3-4
Refer to the Remarks section of ipp_read().
MX800 SERIES PROGRAMMERS GUIDE
225
IPP L EGACY L IBRARY
ipp_diag()
All strings are null terminated. For DUKPT and Master/Session Encryption tests,
the usual prompts for necessary information have been hard coded for the
purpose of this diagnostic. The values for this information are:
M/S working_key
1234567890123456
DUKPT working_key
DUKPT ENCRYPTION
Card Number
4012345678901
PIN
1234
NOTE
Keys loaded for Master/Session and DUKPT must be 1DES compatible.
226
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
select_key_mgmnt()
select_key_mgmnt()
This function selects the Key Management method. It allows selection of Master/
Session and DUKPT methods, either Single DES (1DES) or Triple DES (3DES)
as well as Secure Messaging and Zero Key support.
Prototype
return = select_key_mgmnt(kmm, demf);
int return;
unsigned char kmm, demf;
Parameters
kmm
1 char binary encoded 7 6 5 4 3 2 1 0
-------------------000
1DES Master/Session (default)
-----001
Mixed Mode (1DES & 3DES GISKE)
-----010
3DES GISKE Master/Session
-----011
Secure Messaging (not supported on Mx800 series)
----0---
DUKPT Engine "0" 1DES (default)
----1---
DUKPT Engine "0" 3DES
---0----
Zero Key Support OFF (default)
---1----
Zero Key Support ON
--0-----
Empty GISKE session key support OFF (default)
--1-----
Empty GISKE session key support ON
-0------
Do not clear the keys
-1------
Clear all MS keys and KLK key
0-------
MAC Empty Working Key Support OFF (default)
1-------
MAC Empty Working Key Support ON
MX800 SERIES PROGRAMMERS GUIDE
227
IPP L EGACY L IBRARY
select_key_mgmnt()
demf
1 char binary encoded 7 6 5 4 3 2 1 0
DUKPT Engine "1"
-------0
1DES DUKPT (default)
-------1
3DES DUKPT
DUKPT Engine "2"
3DES GISKE Master/Session
------0-
1DES DUKPT (default)
------1-
3DES DUKPT
XXXXXX--
Reserved
Return Values
228
0
Success
-10
IPP Communication Error
-11
IPP Command Error
MX800 SERIES PROGRAMMERS GUIDE
IPP L EGACY L IBRARY
get_key_mgmnt()
get_key_mgmnt()
This function is used to check the current Key Management settings.
Prototype
return = get_key_mgmnt(kmm, demf);
int return;
char *kmm, *demf;
Parameters
kmm
1 char binary encoded 7 6 5 4 3 2 1 0
-------------------000
1DES Master/Session (default)
-----001
Mixed Mode (1DES & 3DES GISKE)
-----010
3DES GISKE Master/Session
-----011
Secure Messaging (not supported on Mx800 series)
----0---
1DES DUKPT (default)
----1---
3DES DUKPT
---0----
Zero Key Support OFF (default)
---1----
Zero Key Support ON
--0-----
Empty GISKE session key support OFF (default)
--1-----
Empty GISKE session key support ON
-0------
MS keys or KLK key present
-1------
All MS keys and KLK key are clear
0-------
MAC Empty Working Key Support OFF (default)
1-------
MAC Empty Working Key Support ON
MX800 SERIES PROGRAMMERS GUIDE
229
IPP L EGACY L IBRARY
get_key_mgmnt()
demf
1 char binary encoded 7 6 5 4 3 2 1 0
DUKPT Engine "1"
-------0
1DES DUKPT (default)
-------1
3DES DUKPT
DUKPT Engine "2"
------0-
1DES DUKPT (default)
------1-
3DES DUKPT
XXXXXX--
Reserved
Return Values
0
Success
-10
IPP Communication Error
-11
IPP Command Error
The returned values will be placed in the users variables kmm and demf.
230
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 11
Contactless RF Card Reader Module
The Mx800 series of terminals supports the Contactless RF Card Reader Module.
The module communicates over the COM4 serial port (/dev/ttySAC2) at
19200bps 8N1 using a simple command and response protocol.
The user space shared library libvfirfcr and the RFCRapi.h header file
helps to interface common features of the module and are detailed in this chapter.
The routines in the API shall begin with RFCR for RF Card Reader.
NOTE
Library API
Functions
The application can also use the low level commands to communicate with the
module. Please refer to the Omni 7xxx and Mx800 Contactless Modules
Programmers Manual, VDN 23309, for command protocol, status, and error
returns.
The succeeding sections discusses the library API functions used in the Mx800
series of terminals to support the RF Card Reader.
MX800 SERIES PROGRAMMERS GUIDE
231
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRlibVersion()
RFCRlibVersion()
Prototype
int RFCRlibVersion(char *libVersion)
Parameters
libVersion
Pointer to read in the RFCR library version, in the form:
“xx.yy.zz”
Return Values
232
>=0
Success
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRInit()
RFCRInit()
RFCRInit() performs device initialization, opens, and configures the serial port.
The device handle that is returned on success can be used by the applications.
Prototype
int RFCRInit(void);
Return Values
>0
Success, and the device handle is returned.
<0
Error
-ENXIO if no RFCR Module detected
MX800 SERIES PROGRAMMERS GUIDE
233
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRGetVersion()
RFCRGetVersion()
Prototype
int RFCRGetVersion(char *fwVersion);
Parameters
fwVersion
Pointer to read in the RFCR firmware version
Return Values
0
Success
<0
Error
-EBADF if not initialized
>0
234
MX800 SERIES PROGRAMMERS GUIDE
NAK error
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRPing()
RFCRPing()
Tests if the RFCR module is alive and responding
Prototype
int RFCRPing(void);
Return Values
0
Success
<0
Error
-EBADF if not initialized
MX800 SERIES PROGRAMMERS GUIDE
235
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRReset()
RFCRReset()
Configures the RESET line of the RFCR module.
Prototype
int RFCRReset(int onOffPulse);
Parameters
onOffPulse
0 = OFF
1 = ON
2 = PULSE (OFF then ON)
Return Values
0
Success, for OFF
>0
Success, for ON or PULSE. Return value is the RFCR handle
<0
Error
-EBADF if not initialized
236
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRSetAntenna()
RFCRSetAntenna()
Configures the Antenna control of the RFCR module.
Prototype
int RFCRSetAntenna(short onOff);
Parameters
onOff
0 = Disable the RF Antenna
1 = Enable the RF Antenna
Return Values
0
Success, for OFF
<0
Error
-EBADF if not initialized
>0
NAK status
MX800 SERIES PROGRAMMERS GUIDE
237
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRSetIndicator()
RFCRSetIndicator()
Configures the optional indicator controls of the RFCR module. The controllable
optional LED is located on the right side of the reader face. The LED on the top
left side of the reader face is not controllable.
NOTE
The current RFCR hardware does not support the optional buzzer control.
Prototype
int RFCRSetIndicator(int led, int buzz);
Parameters
led
0 = disable LED
1 = enable LED for 100 ms
2 = enable LED for 200 ms
...
15 = enable LED for 1500 ms
buzz
Not used at this time
Return Values
0
Success
<0
Error
-EBADF if not initialized
>0
238
MX800 SERIES PROGRAMMERS GUIDE
NAK status
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRGetCardPayload()
RFCRGetCardPayload()
Prototype
int RFCRGetCardPayload(char* buff, int maxlen);
Parameters
buff
Pointer to store the Card Payload Packet
maxlen
Maximum size of buff
Return Values
>0
Success, with the length of the Card Payload Packet data read.
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
239
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRParseCardPayload()
RFCRParseCardPayload()
Parses the Card Payload Data to the CardPayload structure.
Prototype
int RFCRParseCardPayload(CardPayload* payLoad, char* buff, int len);
Parameters
payload
Pointer to CardPayload structure to store the data
buff
Pointer to Card Payload Packet data
len
Size of the Card Payload Packet data in buff
Return Values
1
Success
not 1
Any return value that is not 1 (either < = 0 or >1) are considered
errors.
The CardPayload structure is:
typedef struct {
char status;// see below
char cardType;// see below
short trk1Start;// index to beginning of Track 1 data
short trk1Length;// length of Track 1 data
short trk2Start;// index to beginning of Track 2 data
short trk2Length;// length of Track 2 data
unsigned char crc1;// LSB of CRC
unsigned char crc2;// MSB of CRC
} CardPayload;
Please refer to the Omni 7xxx and Mx800 Contactless Modules Programmers
Manual, VPN 23309 for the latest status code and the card type values.
Track 1 and Track 2 data will contain the Start and End Sentinels.
240
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRUpdateFW()
RFCRUpdateFW()
Upgrades the RFCR Module firmware.
Prototype
int RFCRUpdateFW(char* fileName, int removeFile, FWUpdateCallback
*displayProgress);
Parameters
fileName
Pointer to name of the update hex file. The filename shall not
have any path prefix, and the file is assumed to be in the “/lib/
modules” directory.
removeFile
0 = do not remove the file
1 = remove the hex file after a successful update
displayProgre
ss
Pointer to callback function to process the progress messages. If
NULL, no progress or error messages are provided (except the
return code).
The format of the FWUpdateCallback is:
typedef void (FWUpdateCallback)(int messageType, const char*
msg);
where the messageType is:
#define ERROR_MESSAGE 1
#define INFO_MESSAGE 2
Return Values
1
Success
not 1
Any return value that is not 1 (either < = 0 or >1) are considered
errors.
MX800 SERIES PROGRAMMERS GUIDE
241
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRPurge()
RFCRPurge()
Purges any pending input from the reader.
Parameters
void RFCRPurge(void);
242
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRInputPending()
RFCRInputPending()
Returns the number of bytes available for reading.
Prototype
int RFCRInputPending(void);
Return Values
0
No data available
>0
Number of bytes available for reading
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
243
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRRawWrite()
RFCRRawWrite()
Sends raw data to the RFCR module.
Prototype
int RFCRRawWrite(unsigned char *buff, int len);
Parameters
buff
Pointer containing the data to send to the RFCR module
len
Number of bytes to send
Return Values
244
>0
Number of bytes written
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRRawRead()
RFCRRawRead()
Reads raw data from the RFCR module.
Prototype
int RFCRRawRead(unsigned char *buff, int maxlen, int msecs);
Parameters
buff
Pointer to store the data read from the RFCR module
maxlen
Maximum size of the buffer
msecs
Maximum wait time for data to arrive
Return Values
>=0
Number of bytes read
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
245
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRAddCRC()
RFCRAddCRC()
Calculates the CRC of the data contained in buff and insert it at the offset position
of the buffer.
Prototype
void RFCRAddCRC(char* buff, int offset);
Parameters
246
buff
Buffer containing the Command Frame to calculate the CRC.
size
The position in the buffer to insert the CRC (and the size of the data to
CRC), usually 14 for Command Frame.
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRCheckCRC()
RFCRCheckCRC()
Prototype
int RFCRCheckCRC (char* buff, short len, unsigned short* calcCRC);
Parameters
buff
Buffer containing the data and CRC, with the CRC being the last 2
bytes of the buffer data.
len
Length of the data including the CRC
calcCRC
Pointer to store the calculated CRC
Return Values
1
CRC is valid
0
CRC did not match
MX800 SERIES PROGRAMMERS GUIDE
247
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRReceiveACKFrame()
RFCRReceiveACKFrame()
Receives an ACK frame from the RFCR module. The contents of the ACK frame
specify whether the reader accepted the command. Depending upon the
command, the ACK frame may provide additional information.
Prototype
int RFCRReceiveACKFrame (char* buff);
Parameters
buff
Pointer to store the ACK frame. It should have space for 16 bytes.
len
Length of the data including the CRC
calcCRC
Pointer to store the calculated CRC
Return Values
248
>0
Success, with the number of bytes read
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
C ONTACTLESS RF C ARD R EADER M ODULE
RFCRReceiveDataFrame()
RFCRReceiveDataFrame()
Receives a data frame from the RFCR device. The Size of the data frame may
vary.
Prototype
int RFCRReceiveDataFrame (char* buff, int maxlen);
Parameters
buff
Pointer to store the ACK frame. The number of bytes returned may
vary, but the buff should be able to accept the maximum possible size
of the data frame.
maxlen
Maximum size of buff.
Return Values
>0
Success, with the number of bytes read
<0
Error
MX800 SERIES PROGRAMMERS GUIDE
249
C ONTACTLESS RF C ARD R EADER M ODULE
RFCR Return Values
RFCR Return
Values
Along with the generic error returns in errno.h, the RFCR specific error returns
are as follows (most are from the RFCRUpdateFW() routine):
Table 21
250
RFCR Return Values
Error
Value
No File
-401
Bad File
-402
Enter ISP Error
-403
Autobaud Error
-404
Frequency Error
-405
Erase Error
-406
Receive Timeout
-407
File Read Error
-408
Big Record Error
-409
Burn Error
-410
Cleanup Error
-411
Invalid Data Frame
-420
Invalid Card Payload
-422
Buffer Too Small
-430
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 12
Input Events
The Mx800 series terminal supports input events as captured through the Linux
kernel Input Event module. Currently, the Input Events module supports the
following event devices:
•
Touch panel – this enables an event interface that an application can use to
capture events from the touch panel. There is currently support to open and
close the event device for the touch panel, but is not fully supported at this
time. Further implementation of a complete API to read/write to the touch
panel may be done some time in the future.
•
USB Human Interface Device - This includes all the USB HID’s listed under
the section USB HID Support: keyboard, scanner and mouse. The mouse
device is not fully implemented at this time. There is full support for the
keyboard and scanner devices.
The APIs below are used to interface to these devices and capture event data.
MX800 SERIES PROGRAMMERS GUIDE
251
I NPUT E VENTS
inputOpen
inputOpen
Prototype
int inputOpen(int vfi_device)
Parameters
vfi_device
The device desired to open as defined in vfiInputAPI.h header file
as follows:
• VFI_TOUCHPAD
• VFI_USB_KBD
• VFI_USB_SCANNER
• VFI_USB_MOUSE
Return Values
This function will return a value greater than 0 upon successful execution,
corresponding to the handle of the opened device, otherwise, it will return a
negative value.
252
MX800 SERIES PROGRAMMERS GUIDE
I NPUT E VENTS
inputRead()
inputRead()
Prototype
int inputRead(int inHdl)
Parameters
inHdl
The device handle obtained from opening the device with
inputOpen().
Return Values
The function will return a value of int size from the device. Currently, touchpad and
mouse events are not captured. Only keyboard and scanner data can be read.
The function will return the ASCII value or the raw scancode of the key pressed or
data scanned. If this function is called in a loop, data can be continually read from
the keyboard or scanner device thereby allowing capturing of data as it is entered/
scanned.
The function will return a negative value if the device corresponding to the handle
cannot be found. If no data is read then 0 is returned.
MX800 SERIES PROGRAMMERS GUIDE
253
I NPUT E VENTS
inputClose()
inputClose()
Prototype
int inputClose(int inHdl)
Parameters
inHdl
The device handle obtained from opening the device with
inputOpen().
Return Values
The function will return a 0 upon success or a negative value if an error occurred
while trying to close the device. When the device is closed, any illuminated LEDs
are turned off.
254
MX800 SERIES PROGRAMMERS GUIDE
CHAPTER 13
Visual Payments
The SMF group shall be responsible for the code needed to connect to the Visual
Payments (VP) server with no applications loaded. Thus, the output will be a VP
shared library and the code that initiates it in System Mode. The VP shared library
shall also be available for the application.
NOTE
•
The TERMINALAPPLICATIONNAME and TERMINALAPPLICATIONVERSION
shall be use the values in the *VPAPPNAME and *VPAPPVERSION
environment variables, respectively.
•
For FTP commands, the directory paths may be embedded in the filename.
•
The FTP server is responsible for any ‘/’ to ‘\’ translations, if required.
•
When initiated in System Mode, the terminal will support XFTPGET with
FILETYPE OS and APP only.
•
Down Channel is for VP Server initiated commands, and Up Channel is for
Terminal initiated commands such as XTRMCFG and sigcap.
•
ApplyOnDate logic to be handled by the application. System Mode will not
support future ApplyOnDate.
Visual Payments •
Library •
Functions
vpInit()
vpParseFields()
• vpSendPacket()
• vpExit()
• vpVersion()
• netUp()
• netPing()
MX800 SERIES PROGRAMMERS GUIDE
255
V ISUAL P AYMENTS
vpInit()
vpInit()
Connects to Visual Payment and starts a thread to monitor the connection.
Callback functions for:
•
Up Channel data received
•
Disconnect
•
Down Channel Request received
•
Down Channel File Status
•
Timeout
Environment variables for XTRMCFG:
•
*VPAPPNAME = string for TERMINALAPPLICATIONNAME
•
*VPAPPVERSION = string for TERMINALAPPLICATION
•
*VPDOWNPORT = string for Down Channel Port Number. Default is 5016.
•
*VPSERVERADDRESS = string for VP Server Address
•
*VPSERVERPORT = string for VP Server Port. Default is 5014.
Prototype
int vpInit(vp_parm_t *pstVP);
typedef struct {
int
iOptions;
char chSeperator;
void *fnUpData;
void *fnUpDisconnect;
int
*fnDownReq;
void *fnDownFileStatus;
void *fnTimedOut;
} vp_parm_t;
Parameters
Bit defined options:
iOptions
0x0002 Disable Auto ACKs
0x0001 Force Download
chSeparator
Return Values
0
256
MX800 SERIES PROGRAMMERS GUIDE
Error
Field separator character
V ISUAL P AYMENTS
vpParseFields()
vpParseFields()
Parses the input buffer into the field arrays. The STX should not be in the input
buffer.
Prototype
int vpParseFields(char *pchInBuf, vp_field_t *pszField, char *pszSep);
typedef struct {
key[];
value[];
} vp_field_t;
Parameters
pchInBuf
Input Data Stream to parse
pszField
Pointer to array of vp_field_t to store parsed strings
chSep
Pointer to field separator character string
Return Values
First index usually returns the command in key, with no value.
MX800 SERIES PROGRAMMERS GUIDE
257
V ISUAL P AYMENTS
vpSendPacket()
vpSendPacket()
Sends the packet to VP server after adding the wrappers. This is used for both Up
and Down Channel messages.
Prototype
int vpSendPacket(int iFd, int iOptions, unsigned short ushMsgNum, char
*pchOutBuf, unsigned short ushLength);
Parameters
iFd
Socket fd
iOptions
Bit defined options:
0x0002 Wait for ACK
ushMsgNum
0 = Message Number included
0 > Insert this Message Number
pchOutBuf
Pointer to data buffer to send
ushLength
Length of payload data
Return Values
Returns bytes sent or error. The VP library will wait for the ACK and do the retries,
if required, before returning.
258
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
vpExit()
vpExit()
Closes the VP connections, frees the memory, and then exits the application.
Prototype
int vpExit(int iFd);
MX800 SERIES PROGRAMMERS GUIDE
259
V ISUAL P AYMENTS
vpVersion()
vpVersion()
Returns the VP library version string in the form “xx.xx.xx”.
Prototype
void vpVersion(char *pchVersion);
260
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
Visual Payments Callback Functions
Visual Payments •
Callback •
Functions
fnDownReq()
fnDownFileStatus()
• fnUpData()
• fnUpDisconnect()
• fnTimedOut()
MX800 SERIES PROGRAMMERS GUIDE
261
V ISUAL P AYMENTS
fnDownReq()
fnDownReq()
Called after a REQ packet is received on the Down Channel. The application can:
•
allow or disallow this command to proceed
•
perform the request and detail the result.
If this callback function is not provided, all REQ commands will be allowed to run.
VP library will send the ACK prior to issuing this callback.
NOTE
System mode may use this to put up downloading status.
Prototype
int fnDownReq(int iDownFd, int iFieldCount, vp_field_t *pszFields);
typedef struct
{
char key[MAX_KEY_SIZE];
char value[MAX_VALUE_SIZE];
} vp_field_t;
Parameters
iDownFd
Socket fd of Down Channel.
iFieldCount
Number of fields in the array.
pszFields
Pointer to array of field structure.
Return Values
262
>0
Allow
0
Success, application performed the request
-1
Disallow, and don’t ask again
-2
Disallow, terminal busy, try again
-3
Failure, application performed the request
-4
Failure
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
fnDownFileStatus()
fnDownFileStatus()
Called after a file that is successfully received from the XFTPGET command on the
Down Channel is to be acted on.
Prototype
void fnDownFileStatus(int iStatus, int iFieldCount, vp_field_t
*pszFields);
Parameters
iStatus
Status of FTP operation:
< 0 Error
= 0 Done
> 0 Bytes or percentage of completion
iFieldCount
Number of fields in the array.
pszFields
Pointer to array of field structure
MX800 SERIES PROGRAMMERS GUIDE
263
V ISUAL P AYMENTS
fnUpData()
fnUpData()
Called when response data is received on the Up Channel. VP library will send
the ACK prior to issuing this callback.
Prototype
int fnUpData(unsigned short ushDataSize, unsigned short ushMsgNum, char
*pchData);
Parameters
264
ushDataSize
Contains the size of data in pchData.
ushMsgNum
Contains the Message Number.
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
fnUpDisconnect()
fnUpDisconnect()
Called when the Up Channel is disconnected. Application should call vpExit()
to clean up.
Prototype
void fnUpDisconnect(void);
MX800 SERIES PROGRAMMERS GUIDE
265
V ISUAL P AYMENTS
fnTimedOut()
fnTimedOut()
Called when ACKs are not received within the timeout period for the Down
Channel Response message.
NOTE
For the Up Channel, the application is responsible for the protocol timeouts.
Prototype
void fnTimedOut(void);
266
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
Network/Ethernet Library Functions Required by Visual Payments
Network/
Ethernet Library
Functions
Required by
Visual Payments
• ftpPut()
• ftpGet()
• netLinkStatus()
• netDown()
• netUp()
• netPing()
MX800 SERIES PROGRAMMERS GUIDE
267
V ISUAL P AYMENTS
ftpPut()
ftpPut()
Gets a file from the VP Server.
FTPHost in form of IP address “xxx.xxx.xxx.xxx” or fully qualified domain name
“ftp.site.com”.
Translation of directory path ‘/’ to ‘\’ to be done by the VP server.
VP server must support the following FTP commands:
•
USER
•
PASS
•
TYPE I
•
PASV
•
RETR
•
CWD
•
STOR
•
QUIT
Prototype
int ftpPut(FTP_parm_t *pstFTP);
typedef packed struct{
char ftpHost[];
char port[];
char userID[];
char password[];
char localFile[];
char remoteFile[];
char errorMsg[];
} FTP_parm_t;
268
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
ftpGet()
ftpGet()
Sends a file to the VP Server.
Prototype
int ftpGet(FTP_parm_t *pstFTP);
MX800 SERIES PROGRAMMERS GUIDE
269
V ISUAL P AYMENTS
netLinkStatus()
netLinkStatus()
Returns the link status of the eth0 network interface.
Prototype
int netLinkStatus();
270
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
netDown()
netDown()
Deactivates the network interface.
Prototype
int netDown();
MX800 SERIES PROGRAMMERS GUIDE
271
V ISUAL P AYMENTS
netUp()
netUp()
Activates the network interface.
Prototype
int netUp();
272
MX800 SERIES PROGRAMMERS GUIDE
V ISUAL P AYMENTS
netPing()
netPing()
Pings the remote host.
Prototype
int netPing(char *host);
MX800 SERIES PROGRAMMERS GUIDE
273
V ISUAL P AYMENTS
XFTP Commands
XFTP
Commands
The succeeding sections lists all XFTP commands.
XFTPGET •
•
System Mode will act only on FILETYPE OS and APP.
•
The FILENAME is in reference to the VP server, and may contain a directory
path.
•
The file will be transferred to the directory defined in the *VPDOWNLOADDIR
environment variable. If not defined, it defaults to “/home/usr1”.
•
The application is responsible for the processing of the transferred file.
XFTPPUT •
Required fields are: FTPHOST, FTPPORT, FTPUSER, FTPPWD, FILENAME.
•
The FILENAME is in reference to the local file, and may contain a directory
path.
•
The VP server application currently will only upload diagnostic log files.
XFTPDEL •
274
Required fields are: FTPHOST, FTPPORT, FTPUSER, FTPPWD, FILENAME,
FILETYPE.
Required fields is: FILENAME.
•
The FILENAME is in reference to the local file, and may contain a directory
path.
•
The application has a chance to disallow the request in the fnDownReq()
callback.
•
For root owned files, only those in the “/var/log” directory may be deleted
by the XFTPDEL command.
•
The VP server application currently will only upload diagnostic log files.
MX800 SERIES PROGRAMMERS GUIDE
APPENDIX A
IPP MS and DUKPT Communications Packets
This appendix describes the required packet commands of the IPP for MS (Master
Session) or DUKPT operations supported by the Mx800 series.
Advanced
Programming in
IPP
The differences between the Verix and Verix V IPP MS and DUKPT from the
Mx800 series IPP (XMIPP8) are summarized in Table 22.
Table 22
Differences in Mx800 series IPP
IPP
IPP6
IPP7
VVIPP
IPP8
VVIPP8
MXIPP8
Secure Message Mode
No
Yes
No
Yes
No
No
Spain SEMP/4B
Yes
Yes
No
Yes
No
No
Key tagging
Yes
No
No
No
No
No
DUKPT Engines
1
1
1
3
3
3
VVIPP supports IPP7 GISKE 3DES key features with one enhancement: All 10
master keys can be triple-length keys. IPP7 is limited to at most three triple-length
keys.
Minor Differences <SI>0103<SO> PROM Checksum
by Packet
The value of the checksum does not match IPP7 because Verix V does not use
the same code.
<SI>0108<SO> IPP ROM Version Number
The return packet is
<SI>14IPP8 EMULvvv mm/yy<SO>{LRC}
where, vvv is the version number, mm is the release month, and yy is the release
year.
<SI>13n<SO> Select Baud Rate
Since there is no IPP UART, setting the baud rate does not affect anything.
However, the baud rate is stored in non-volatile memory so it can be returned in
diagnostics packets.
In platforms with an IPP chip, the application must determine the baud rate of the
IPP by sending a test packet at all possible baud rates until the IPP responds with
an ACK. In Verix-based Omni series terminals, there is no UART so baud rate
mismatch is not possible. Applications that try all possible baud rates receive an
ACK on the first test packet thus, speeding up applications slightly.
MX800 SERIES PROGRAMMERS GUIDE
275
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packets
<SI>15SPAIN<SO> Set IPP6 Key Management Mode
Spain mode is not supported and switching to Spain mode erases keys. This is
done because some programs depend on this feature to erase keys.
<SI>17xyz<SO> Set IPP7 Key Management Mode
SM mode is not supported but switching to SM mode erases keys. This is done
because some programs depend on this feature to erase keys.
<SI>02…<SO> Set Master Key
IPP7 can hold a maximum of three (3) triple-length keys. In VVIPP, all ten key
locations can hold a single-, double-, or triple-length key.
<STX>75..<ETX> DUKPT Accept and Encrypt PIN/Data Authentication
Response
ANSI DUKPT MAC is only defined for 3DES DUKPT. VVIPP returns error code 8
if ANSI DUKPT MAC is requested when using 1DES DUKPT. IPP7 returns
undefined results in this case.
Packets
The packet set is similar to that used for external PIN pads, such as the
PINpad 1000, however, unlike previous IPPs, the Omni 33XX IPP is a software
module running on the main CPU. Previous IPPs used dedicated microcontrollers
connected to the main CPU through a serial port. In Omni 33XXIPP the COM5
serial port is emulated in software along with all IPP functionality.
The IPP command and response packets can be divided into the following
categories:
NOTE
•
Common Packets: Packets used in both MS and DUKPT.
•
MS-Specific Packets: Packets used while doing MS.
•
DUKPT-Specific Packets: Packets used while doing DUKPT.
•
MAC-Specific Packets: MAC generation of received message packets.
Omni 33XX IPP does not support Spain SEMP/4B mode or Secure Messaging
(SM) mode.
The IPP supports both MS and DUKPT key management modes concurrently.
Also, the IPP supports MAC processing while doing MS or DUKPT.
Table 23 lists packets used in both MS and DUKPT sessions.
Table 23
276
Common Packets
Packet
Description
01
Interactive diagnostic routine
05
Transfer serial number
06
Request PIN pad serial number
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packets
Table 23
Common Packets (Continued)
Packet
Description
09
Response to Packet 01
11
PIN pad connection test
12
Dummy packet
13
Select baud rate
14
Response to Packet 01
15
Set IPP key management mode
17
Set IPP7 key management mode
18
Check IPP7 key management mode
M04
Read Permanent Unit Serial Number (IPP8 Emulation)
Table 24 lists packets supported by IPP for MS.
Table 24
IPP Supported Packets for MS
Packet
Description
02
Load/set master key
04
Check master key
07
'Dummy' DES reliability test
08
Select master key
Z60
Accept and encrypt PIN (VISA mode)
Z63
Accept and encrypt PIN, custom PIN entry requirements (VISA mode)
71
Response PIN block
Z66
MAC processing
Z67
Return MAC
72
Cancel MAC session
Table 25 lists packets supported by IPP for DUKPT.
Table 25
IPP Supported Packets for DUKPT
Packet
Description
90
Load initial key
91
Confirm initial key
75
Encrypt PIN/authentication data response
78
Encrypt PIN/authentication data test request
76
PIN entry test request
71
Response PIN entry test request of “76”
Z60
Accept and encrypt PIN request (VISA mode)
Z63
Accept and encrypt PIN, custom PIN entry requirements (VISA mode)
Z69
Accept and encrypt PIN/data authentication request (VISA mode)
73
Response PIN block
19
Select a DUKPT Engine (IPP8 Emulation)
25
Check the DUKPT Engine (IPP8 Emulation)
MX800 SERIES PROGRAMMERS GUIDE
277
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packets
Packet The IPP only responds to commands that have the proper packet format. The
Acknowledgement packet can be in the form of <STX>msg<ETX>[LRC]or <SI>msg<SO>[LRC]
and Timing according to the specific command.
The IPP returns <ACK> within 20ms to the terminal when it receives a properly
framed packet with a valid LRC. When other framing is received for a command
that requires <STX><ETX> framing (for example, <SI><SO>, <SI><ETX>, or
<STX><SO>), <ACK> is returned if the LRC is valid; only the specified framing is
processed.
This rule also applies to <SI><SO> packet commands. The IPP does not act on
an incorrectly formatted packet. This includes a packet with a wrong header,
wrong trailer, wrong field separator, an out of range indexing, or incorrect packet
length. An example of a packet that has an out of range indexing would be
packet 02, master key address = 15.
The response message from the IPP follows the <ACK> if the packet command
has a response. However, the timing varies from different commands.
Encryption There are two methods of PIN encryption in IPP:
•
MS
•
DUKPT
MS Method
IPP encrypts the customer's PIN according to the ANSI X9.8 standard and the
ANSI X9.24 master key management method, based on the ANSI X3.92 DES
algorithm implemented in the IPP firmware. The encryption during a transaction is
as follows:
1 The master device sends a private communication key (or working key) to the
IPP, where it is decrypted using the currently selected master key. An account
number and PIN are also entered to IPP through the master device.
2 The IPP generates the clear text PIN block using the account number and
PIN.
3 Using the decrypted working key, the IPP encrypts the PIN block using the
DES algorithm and working key, then sends the encrypted PIN block to the
master device.
4 The master device appends the encrypted PIN block to a request packet and
forwards the completed request packet to the host.
278
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packets
The following illustrates an MS encryption session.
Master Device
IPP
1 Forwards the encrypted working
key, account number, and PIN to
the IPP.
1 Decrypt the working key using
the master key.
2 Encrypts the PIN block with
the decrypted working key.
3 Sends the PIN block to the
master device.
2 Appends the PIN block to the
request packet.
3 Forwards the packet to the host.
DUKPT Method
The IPP encrypts the customer's PIN according to the ANSI X9.8 standard and
Visa's ANSI X9.24 DUKPT key management method, based on the ANSI X3.92
DES algorithm implemented in the IPP firmware.
Before actual operation, each IPP must be loaded with a unique initial KSN (key
serial number) and a unique initial PEK (PIN Encryption Key). And the encryption
counter of the IPP is set to zero. The initial PEK is generated by encrypting the
initial KSN using appropriate derivation key.
The encryption per transaction of IPP during actual operation is as follows:
1 The master device sends an account number and a PIN to the IPP.
2 The IPP generates the clear-text PIN block using the account number and
PIN.
3 Using the generated PEK based on the encryption counter which is updated
after each transaction, the IPP do a special encrypt to the PIN block using the
DES algorithm and PEK, then sends the encrypted PIN block with current
KSN (the concatenation of the initial KSN and the encryption counter) to the
master device.
4 The master device then appends the encrypted PIN block and current KSN to
a request packet and forwards the completed request packet to the host.
MX800 SERIES PROGRAMMERS GUIDE
279
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packets
The following illustrates the DUKPT method of encryption.
Master Device
IPP
1 Forwards the account number
and PIN to the IPP.
1 Creates the PIN block.
2 Encrypts PIN block with the
generated PEK.
3 Sends the PIN block and current
KSN (key serial number) to the
master device.
2 Appends the PIN block and KSN
to the request packet.
3 Forwards the packet to the host.
Figure 2
DUKPT Session Encryption Example
Constraints The known software constraints for IPP are:
•
All communication must be asynchronous, half-duplex, 1200/2400/4800/9600/
19200 baud, 7 data bits, even parity, and 1 stop bit (7E1).
•
Packet length is limited to 255 characters.
NAKs When the IPP receives NAK, it retransmits the last message and increments a
NAK counter for that communication session. If more than three NAKs are
received during any attempt to transmit the same item, the transmitting party send
an EOT, terminating the session.
Time Outs During a communication session, the IPP or the terminal times out if it does not
receive the expected communication within 15 seconds. The unit sends an EOT
to terminate the communication session.
Key Insertion This section describes MK insertion and DUKPT initial PIN encryption key
insertion.
Master Key Insertion
For each master key injection session, the IPP checks to see if it is the first time
that user tried to load the master key. If it is the first time, the IPP clears all master
keys to zero before loading a new master key.
NOTE
All master keys must be loaded in the same key injection session, otherwise the
previous master key is erased in the next master key injection session.
A master key injection session is the duration of the power level is maintained in
the IPP.
The master key insertion rule does not apply to the GISKE key loading key (KLK).
280
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
The terminal or master device uses Packet 02: Transfer Master Key to transfer the
master keys into the IPP for MS.
DUKPT Initial PIN Encryption Key Insertion
The terminal or master device uses DUKPT Packet 90: Load Initial Key Request
to load the initial PIN encryption key into the IPP for DUKPT.
Entering a PIN Packets Z60, Z63, and Z69 are used to get and encrypt a PIN from the user. Z63
is similar to Z60, but allows more options for PIN entry, such as minimum and
maximum PIN length and echo character. Z69 is similar to Z60, but does DUKPT
MAC processing as well as PIN encryption using the same DUKPT key.
Restrict the Speed PIN encryption is limited to one per 30 seconds on average to deter an exhaustive
of the PIN PIN search. The algorithm is best explained in terms of tokens in a bucket.
Encryption
A PIN encryption request is only accepted if there is a token in a bucket. A token
Operation
is placed in the bucket every 30 seconds, with a maximum of 127 tokens allowed
in the bucket. (The number of tokens in the bucket is maintained across power
cycles.) Every time a PIN is entered, a token is removed from the bucket. If there
is no token in the bucket, the PIN entry request returns an error.
This allows an average of one PIN encryption per 30 seconds, but over a long
period of time. The intention is that under normal use PIN entry is not denied.
IPP7
This section discusses IPP7-specific features for Omni 33XX IPP. Omni 33XX
IPP7 is backward compatible with IPP6 and IPP5. Exceptions to this rule are
noted.
GISKE GISKE (Global Interoperable Secure Key Exchange) is an industry standard key
block format for secure transfer of secret keys between two devices that share a
secret key. Both master and session keys can be in GISKE format. The GISKE
KLK (Key Loading Key) is used to encrypt and authenticate master keys. Master
keys can be remotely updated using this key. GISKE is designed for secure
transfer of double- and triple-length 3DES keys. For more details on GISKE refer
GISKE Key Block Spec, VPN 22986.
Key Management The rules for key management switching (see Packet 17: Set IPP7 Key
Switching Management Mode) are shown in Table 26.
Key •
NC = no change
•
E = all keys erased
•
1K = valid 1DES keys (single-length keys) retained, other keys erased
•
2/3K = valid 3DES keys (double- and triple-length keys) retained, other keys
erased
MX800 SERIES PROGRAMMERS GUIDE
281
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
Table 26
Key Management Switching Rules
Rules
To 1DES (VISA)
To 1DES (SPAIN)a
To Mixed Mode
To 3DES
To SMa
From 1DESb (VISA)
NC
E
NC
2/3K
E
From 1DESa (SPAIN)
E
NC
E
E
E
From Mixed modec
1K
E
NC
2/3K
E
From 3DESd
E
E
E
NC
E
From SMa
E
E
E
E
NC
Key Mode
1DES and 3DES Key Usage Rulese
1DES onlyb
• Load and use of 1DES MS keys allowedf
• Load KLK allowed
• Load 3DES master keys allowed
• Use of 3DES master keys not allowed
• Load 3DES session keys not allowed
• Use of 3DES session keys not allowed
• Key attributes verifiedg, except key usage = ‘AN’ – ANY is allowed
• GISKE key block verifiedh
Mixed modec
• Load and use 1DES or 3DES MS keys allowed
• Load KLK allowed
• 1DES master keys used for 1DES session keys
• 3DES master keys used for 1DES and 3DES keys
• Key attributes verified, except: key usage = ‘AN’ – ANY is allowed
• GISKE key block verified
3DES onlyd
• Load and use 3DES MS keys allowed
• Load KLK allowed
• Load 1DES master keys not allowed
• Use of 1DES master keys not allowed
• Load 1DES session keys not allowed
• Use of 1DES session keys not allowed
• Key attributes verified; no exceptions allowed
• GISKE key block verified
a.
b.
c.
d.
e.
f.
g.
h.
282
Spain and SM modes not supported in Verix V. Keys are erased as specified.
Least secure mode.
For transition period.
Most secure mode.
The key management register is set using Packet 17: Set IPP7 Key Management Mode.
All DUKPT related keys, counters, and registers are erased when the IPP KM switches between 1DES DUKPT and 3DES
DUKPT. Other MS related information remains untouched.
Key attributes verified means that when a key stored in the IPP is used, the IPP must validate the content of all key
attributes. The attributes of the key are validated against the GISKE specification acceptable for that command.
GISKE key block verified means that when receiving a key block, the IPP must validate both the key block binding method
of the key block and the content of the header. The header of the key is validated against a list of headers acceptable for
that command.
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
Using a Session Key Loading the Session Key
3DES session keys are only loaded in GISKE cipher text under the protection of
the indexed master key, as long as that key has its attribute set to ‘KEK’ (key
usage attributes = “K0”). The master key must be 3DES. The version of the
incoming key is not checked or saved. The usage attribute of the incoming
working key is checked, but is not saved.
The GISKE key length decryption rule is applied. The length of the master key
must be greater or equal to the length of the working key.
1DES session keys in key-only format are loaded in cipher text under the
protection of the indexed master key, if that key has its attribute set to ‘ANY’ or
‘KEK’ (key usage attributes = “K0”). The master key can be a single-, double-, or
triple-length key.
1DES session keys in GISKE format are loaded in cipher text under the protection
of the indexed master key, if that key has its attribute set to ‘KEK’ (key usage
attributes = “K0”). The version of the incoming key is not checked or saved. The
usage attribute of the incoming working key is checked, but not saved. The master
key can be a single-, double-, or triple-length key.
Master Key for PIN Encryption
Where the PIN Entry zero session key method for 1DES is used, the current
master key must be tagged ANY or PIN ENCRYPTION.
Where the tagged zero GISKE session key method for 3DES is used, the current
master key must be tagged for the specified purpose – key usage =
NOTE
•
‘P0’ - ‘PIN ENCRYPTION’
•
Key Algorithm = 'T' -TDES for double or triple-length keys
•
‘D’ - DES for single-length key
•
‘AN’ – ANY
Zero GISKE session key for 3DES means all fields are zero in the GISKE key
block.
If zero GISKE support is disabled, the zero GISKE session key causes an error
response from the IPP. The zero session key support is enabled or disabled
through the KM flag. Zero GISKE session key support (PIN entry) is enabled or
disabled through the KM flag.
MX800 SERIES PROGRAMMERS GUIDE
283
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
Rules for Loading This section provides details on IPP7 key attributes, key version, and key length.
the Master Key
On erasure, the master key usage attribute is set to 0, the version is set to 0, and
(MS only)
the length is set to 1DES.
NOTE
Each key has its own key attribute register, key version register, and key length
register.
The register listed in Table 27 applies to 1DES master key, 3DES master key
(GISKE), and KLK (GISKE). The original GISKE (ASCII-hex) key usage attribute
value is saved in RAM (2 bytes).
Table 27
Key Attributes
Key
Attribute
Register
Value
Definition
[XX]
AN
ANY: Key is available in IPP, but the Key was not
loaded using GISKE format.
D0
Data encryption
I0
IV
T0
Control vector
K0
Key encryption or wrapping
G0
MAC generation
M0
MAC verification
P0
PIN encryption
V0
PIN verification
C0
CVK: card verification key
B0
BDK: base derivation key [A]
00
ISO 9797-1, MAC algorithm 1– 56 bits
10
ISO 9797-1, MAC algorithm 1–112 bits
20
ISO 9797-1, MAC algorithm 2–112 bits
30
ISO 9797-1, MAC algorithm 3–112 bits
40
ISO 9797-1, MAC algorithm 4–112 bits
50
ISO 9797-1, MAC algorithm 5–56 bits
60
ISO 9797-1, MAC algorithm 5–112 bits
The key version of an incoming GISKE format key must be greater than or equal
to the version set in the key attribute table for all keys (that is1DES master key,
3DES master key GISKE, and KLK GISKE). The rules for the GISKE key version
are:
•
284
when the version is greater than or equal to the current key, OK is returned
and the IPP updates the new key
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
•
NOTE
when the version is less than the current key version, an error returns and the
IPP rejects the new key
The key version comparison is only compared to the key it is replacing, not to any
other keys.
Table 28 lists the key length register values for 1DES, 3DES, and three-key
3DES.
Table 28
Key Length Register Values
Length
Comments
1DES
Single-length key: Key length register = 00
3DES
Double-length key: Key length register = 01
3-Key 3DES
Triple-length key: Key length register = 10
Reserved
Key length register = 11
KLK The GISKE KLK is loaded as clear text if the KLK is not present in IPP. The
version of the incoming key is not checked. The version of the stored key is the
version carried in the message. The stored key attribute is set to the value in the
GISKE message, which should be 'K0'.
The GISKE KLK is loaded in cipher text if the stored KLK attribute location is 'K0'
and the KLK present flag in the IPP is set. The new GISKE KLK load is protected
by the previous GISKE KLK. The current and new KLK key must be a double- or
triple-length key. The version of the key is checked against the stored version.
The version of the stored key is the version carried in the message. The stored
key usage attribute is set to that carried in the GISKE message, which should be
'K0'.
The rules for the KLK are:
•
KLK is present and clear text is being loaded, the IPP returns an error.
•
KLK is not present and clear text is being loaded, OK is returned and the IPP
stores the first KLK.
•
KLK is present and cipher text is being loaded that is not encrypted with the
previous KLK, the IPP returns an error.
•
KLK is not present and cipher text is being loaded that is not encrypted with
the previous KLK, the IPP returns an error.
•
KLK is present and cipher text is being loaded that is encrypted with the
previous KLK but has an incorrect key version, the IPP returns an error.
•
KLK is not present and cipher text is being loaded that is encrypted with the
previous KLK but has an incorrect key version, the IPP returns an error.
MX800 SERIES PROGRAMMERS GUIDE
285
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
•
KLK is present and cipher text is being loaded that is encrypted with the
previous KLK, has the correct key version and the key attribute is not equal to
“KEK”, the IPP returns an error.
•
KLK is present and cipher text is being loaded that is encrypted with the
previous KLK, has the correct key version and the key attribute is equal to
“KEK”, the IPP stores the KLK and its attributes.
•
KLK is not present and cipher text is being loaded that is encrypted with the
previous KLK, has the correct key version, the key attribute KEK value has no
effect, the IPP returns an error.
3DES All 3DES key loads are in GISKE format. 3DES master keys are loaded in clear
text without cryptographic protection if the KLK present flag is clear in the IPP.
The MAC value is all zero bytes. The version of the incoming key is checked
against the stored version. The version of the stored key is the version carried in
the GISKE message. The stored key attribute is set to that in the GISKE
message.
3DES master keys load in cipher text under the protection of the KLK if the KLK
present flag is set. The KLK must be 3DES. The version of the key is checked
against the stored version. The version of the stored key is the version carried in
the GISKE message. The stored key usage attribute is set to that in the GISKE
message.
The rules for 3DES are:
286
•
KLK is present (the current key attribute register in the IPP is GISKE format)
and clear text 3DES master key is being loaded, the IPP returns error
•
KLK is not present (the IPP KLK present flag is clear) and clear text 3DES
master key is being loaded, the IPP stores the 3DES key
•
KLK is present (the current key attribute register in the IPP is GISKE format)
and cipher text 3DES master key is being loaded with an incorrect key
version, the IPP returns an error
•
KLK is present (the current key attribute register in the IPP is GISKE format)
and cipher text 3DES master key is being loaded with the correct key version,
the IPP decrypts and stores the 3DES key master key attribute equal to the
GISKE format length and equal to 3DES
•
KLK is not present (the IPP KLK present flag is clear) and cipher text 3DES
master key is being loaded, the IPP returns an error
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
1DES The 1DES master keys loaded in the short-form method (that is, IPP6 key-only
format) have the 'ANY' and 1DES attributes set. The 1DES master keys in GISKE
format are be loaded in GISKE clear text without cryptographic protection, if the
KLK present flag is clear in the IPP. The MAC value is all zero bytes. The version
of the incoming key is checked. The version of the stored key is the version
carried in the GISKE message. The stored key attribute is set to that carried in the
GISKE message.
The 1DES master keys in GISKE format are loaded in cipher text under the
protection of the KLK, if the KLK present flag is set. The KLK master key must be
3DES. The version of the key is checked against the stored version. The version
of the stored key is the version carried in the GISKE message. The stored key
attribute is set to that carried in the GISKE message.
Master Key In Omni 33XX, all master key locations 0–9 can hold single-, double-, or tripleAddressing length DES keys. Omni 33XX IPP7 can hold at most three triple-length keys.
Clear Text GISKE The following are VeriFone-proprietary rules for GISKE key block loading, and are
Key Block Loading not part of the ANSI GISKE specification.
Rule
• If the KLK is not loaded, the GISKE key block is loaded in clear text.
•
The clear-text GISKE key bock must be padded to a length of 120 bytes, as
shown in the following examples.
Key
GISKE key block:
Cipher text GISKE key
block for transmit
(encrypted with KLK
or KEK):
Clear text GISKE key
block (MAC is all
zeros):
HB
indicates the header block
KB
indicates the key block
eHB
indicates the encrypted header block
eKB
indicates the encrypted key block.
8 HB + 24 HB + 24 KB + 8 MAC
8 HB + 48 eHB + 48 eKB + 16 MAC
8 HB + 24 HB + 48 KB + 16 MAC
To pad the clear text GISKE key block to a total length of 120 bytes and be
consistent with its counterpart (that is, the cipher text GISKE key block), 24 HB
is expanded to 48 HB. The high and low nibbles of ASCII are converted to an
individual hex value. For example:
D
expanded HB =
0
A
...
0x44
0x30
0x41
(ASCII)
0x34 0x34
0x33 0x30
0x34 0x31
(hex)
MX800 SERIES PROGRAMMERS GUIDE
287
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
IPP7
Padded clear text
GISKE key block
(MAC is all zeros):
288
8 HB + 48 HB + 48 KB + 16 MAC
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Common
Packets
This section presents the packets common to all protocols.
Packet 01: Packet 01 has the IPP run a specified self-diagnostic test. Information on the test
Interactive in progress is provided using response packets 9 and 14, depending on the
Diagnostic Routine selected test.
Table 29
Packet 01 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 01
Diagnostic # [dd]
2N
2-byte ASCII code of the diagnostic test to run.
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error check
Packet 01 Length: •
MAX: 7 characters
•
MIN: 7 characters
Packet 01 Example: Send the IPP the request to run diagnostic test 1, RAM test/one time:
<SI>0101<SO>{LRC}
Packet 05: Transfer The master device uses this packet to transfer a serial number to the IPP.
Serial Number Table 30
Packet 05 Format
Packet 05 Length: •
•
Data Element
Characteristic
Comments
<SI>
1H
Shift in, value: 0Fh
Packet Type
2AN
Value: 05
[vvv]
3AN
PINpad version number
[dddddd]
6N
Release date -- format: YYMMDD
[p]
1AN
Production facility code
[bb]
2AN
Production batch code
[nnnn]
4N
Serial # for group ID 0001–9999
<SO>
1H
Shift out, value: 0Eh
{LRC}
1H
Error check
MAX: 21 characters
MIN: 21 characters
Packet 05 Example: Set the IPP serial number to 246880401A001234:
<SI>05246880401A001234<SO>{LRC}
MX800 SERIES PROGRAMMERS GUIDE
289
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 31
Packet 05 Communication Protocol
Transmit
Direction
Master Device
IPP
<SI>05[vvv][dddddd][p][bb][nnnn]
<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
<SI>05[vvv][dddddd][p][bb][nnnn]
<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect; the IPP
saves serial number
• EOT after 3 NAKs
EOT
Packet 06: Request The master device uses this packet to request the serial number from the IPP. If
PIN Pad Serial no serial number stored in the IPP, 16 bytes of ASCII zeros will be returned to the
Number master device.
Table 32
Packet 06 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, value: 0Fh
Packet Type
2AN
Value: 06
<SO>
1H
Shift out, value: 0Eh
{LRC}
1H
Error check
Packet 06 Length: •
MAX: 5 characters
•
MIN: 5 characters
Request Sample <SI>06<SO>{LRC}
Packet
Table 33
Packet 06 Format
290
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 06
[vvv]
3AN
PIN Pad version number
[dddddd]
6N
Release date, format: YYMMDD
[p]
1AN
Production facility code
[bb]
2AN
Production batch code
[nnnn]
4N
Serial # for Group ID 0001 - 9999
<SO>
1H
Shift out, value: 0Eh
{LRC}
1H
Error check
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Packet 06 Length: •
•
MAX: 21 characters
MIN: 21 characters
Response Sample <SI>06246880401A001234SO>{LRC}
Packet
Table 34
Packet 06 Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>06<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
<SI>06[vvv][dddddd][p][bb][nnnn]<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect,
the IPP saves serial
number
• EOT after 3 NAKs
EOT
Packets 09 and 14: In response to packet 01, the IPP returns packets 09 and 14 to the master device:
Response Packet to
• Packet 09 is the response packet to packet 01 with diagnostic # 07 (UART
Packet 01
Loopback Test).
•
Packet 14 is the response packet to the packet 01 with diagnostics #00, 01,
02, 03, 06, 08, 09, and 10.
Packets 09 and 14 are in the format shown in Table 35.
MX800 SERIES PROGRAMMERS GUIDE
291
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 35
Packets 09 and 14 Communication Protocol
Master Device
Transmit
Direction
IPP
00 Current Baud Rate
<SI>0100<SO>{LRC}
ACK/NAK/EOT
<SI>14yyyyy<SO>{LRC}
where, yyyyy indicates the current baud
rate:
• 1200
• 2400
• 4800
• 9600, or
• 19200
ACK/NAK/EOT
EOT to terminate process.
01 RAM Test/One-Time
<SI>0101<SO>{LRC}
ACK/NAK/EOT
<SI>14RAM TST BEGIN<SO>{LRC}
ACK/NAK/EOT
<SI>14RAM TST OK<SO>{LRC} or
<SI>14BAD RAM<SO>{LRC}
ACK/NAK/EOT
EOT to terminate process.
292
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 35
Packets 09 and 14 Communication Protocol (Continued)
Master Device
Transmit
Direction
IPP
02 RAM Test/Continuous
<SI>0102<SO>{LRC}
IPP7
ACK/NAK/EOT
<SI>14RAM TST BEGIN<SO>{LRC}
ACK/NAK/EOT
ACK
<SI>14RAM TST OK<SO>{LRC} or
<SI>14BAD RAM<SO>{LRC}
ACK/NAK/EOT
EOT to terminate process.
03 PROM Checksum Test
<SI>0103<SO>{LRC}
IPP7
ACK/NAK/EOT
<SI>14xx<SO>{LRC}
where, xx is the one-byte PROM internal
checksum. There are two checksums
inside the IPP:
• The PROM checksum, which is 2-bytes
long and is located at 7FFE/7FFF. This
checksum is for manufacturing
purposes.
• The PROM internal checksum.
ACK/NAK/EOT
EOT to terminate process.
MX800 SERIES PROGRAMMERS GUIDE
293
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 35
Packets 09 and 14 Communication Protocol (Continued)
Master Device
Transmit
Direction
IPP
06 Serial Number Check
<SI>0106<SO>{LRC}
IPP6 and earlier
ACK/NAK/EOT
<SI>14xxxxxxxxxxxxxxxx<SO>{LRC}
where, xxxxxxxxxxxxxxxx indicates the
serial number of the IPP. Length is 16
digits, for example, 1234567890123456.
ACK/NAK/EOT
EOT to terminate process.
07 UART Loopback Test
<SI>0107<SO>{LRC}
IPP7
ACK/NAK/EOT
<SI>09<SO>{LRC}
ACK/NAK/EOT
<SI>09<SUB>PROCESSING<SO>{LRC}
ACK/NAK/EOT
<SI>09<SUB>PROCESSING<SO>{LRC}
ACK/NAK/EOT
EOT to terminate process.
294
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 35
Packets 09 and 14 Communication Protocol (Continued)
Master Device
Transmit
Direction
IPP
08 IPP PROM Version Number
<SI>0108<SO>{LRC}
IPP7
ACK/NAK/EOT
<SI>14IPPx vvvvxxx MM/YY<SO>{LRC}
where:
• vvvv: 4-digit software ID number. For
IPP5, 0PGP.
• xxx: 3-digit software version number.
For example, xxx = 011 indicates the
software version number is 1.1; if 11A
(11B, 12D, 21A, and so on), the
software is not ECO released and is for
test and qualification purposes only. For
formal ECO released versions, xxx is
all numbers.
• MM/YY: date of software.
For example, MM/YY = 05/95 means
the software was created May 1995.
ACK/NAK/EOT
EOT to terminate process.
09 Reset IPP
<SI>0109<SO>{LRC}
IPP7
ACK/NAK/EOT
<SI>14RESET COMPLETE<SO>{LRC}
ACK/NAK/EOT
EOT to terminate process. (The IPP
restarts. Insert a delay before sending
data to the IPP.)
MX800 SERIES PROGRAMMERS GUIDE
295
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 35
Packets 09 and 14 Communication Protocol (Continued)
Transmit
Direction
Master Device
IPP
10 Clear IPP
IPP7
<SI>0110<SO>{LRC}
ACK/NAK/EOT
<SI>14CLR COMPLETE<SO>{LRC}
ACK/NAK/EOT
EOT to terminate process.
Packet 11: PIN Pad The master device uses this packet to check the connection with the IPP. If the
Connection Test connection is good, the master device receives an ‘ACK’ from the IPP within one
second. Else, it assumes that the IPP is not connected.
Table 36
Packet 11 Length: •
•
Packet 11 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift in, value: 0Fh
Packet Type
2AN
Value: 11
<SO>
1H
Shift out, value: 0Eh
{LRC}
1H
Error check
MAX: 5 characters
MIN: 5 characters
Sample Packet <SI>11<SO>{LRC}
Table 37
Packet 11 Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>11<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
Packets 7 and 12: Packets 7 and 12 are dummy packets. When the IPP receives these packets it
Dummy Packets sends out only <ACK> within one second.
296
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Packet 13: Select Omni 33XX supports this packet but it has no effect. Verix-based Omni series
Baud Rate terminals do not use an RS-232 interface so do not need this setting. However, it
is supported for compatibility with other IPPs.
This packet command selects the baud rate for the RS-232 communication
interface. Through packet command 01 diagnostic 00, the current baud rate can
be determined. The factory default is 1200 bps.
The baud rate setting is stored in backup RAM. After a power cycling memory test
or loss of backup battery power, the baud rate setting is reset to the default.
Table 38
Packet 13 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift in, value: 0Fh
Packet Type
2AN
Value: 13
Packet Data
1N
Baud rate codes: 1 - 5
• 1 = 1200 bps (default)
• 2 = 2400 bps
• 3 = 4800 bps
• 4 = 9600 bps
• 5 = 19200 bps
Packet 13 Length: •
•
<SO>
1H
Shift out, value: 0Eh
{LRC}
1H
Error check
MAX: 6 characters
MIN: 6 characters
MX800 SERIES PROGRAMMERS GUIDE
297
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 39
Packet 13 Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>13x<SO>{LRC}
ACK if LRC okay; NAK if LRC incorrect.
<SI>14yyyyy<SO>{LRC}
where,
x = baud rate code
yyyyy = string for selected
baud rate
• 1
• 1200 (default)
• 2
• 2400
• 3
• 4800
• 4
• 9600
• 5
• 19200
The baud rate code must be in the range 1–5; all
other codes are ignored and directly echo [EOT]
with the baud rate unchanged.
ACK/NAK
EOT to terminate process (the PIN pad uses the
new baud rate accordingly).
Packet 15: Set IPP This packet command changes the secret key management mode that the IPP
Key Management uses for the transaction. The IPP supports two modes of secret key management:
Mode
• IPP5 or VISA MASTER SESSION+DUKPT mode
VISA MASTER SESSION+DUKPT mode covers MS and DUKPT and MAC
process of standard ANSI MAC. The Omni 33XX IPP does not include SEMP/4B
mode, and erases keys when this mode is selected.
NOTE
In the Omni 33XX IPP, switching to SEMP/4B mode clears all IPP memory but
leaves the IPP in VISA M/S+DUKPT mode.
Request Packet <SI>15[Key Code][<SO>{LRC}
Format
Table 40
IPP Request Packet 15 Format
Data Element
Field
Length
Comments
<SI>
Start of
packet
1
Shift in.
Packet type
2
15
298
MX800 SERIES PROGRAMMERS GUIDE
Control character- 0Fh
Set IPP key management mode
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 40
IPP Request Packet 15 Format
Data Element
Field
Length
Comments
[Key Code]
Packet
parameters
4 or 5
The key management operation
mode for the IPP
• “SPAIN” – Spain SEMP/4B
mode
• “VISA” – IPP mode
• Other characters – no change
[SO]
{LRC}
End of
packet
1
Block code
check
1
Shift out.
Control character- 0Eh
Error check character
Response Packet <SI>15[Key Code]<SO>{LRC}
Format
Table 41
IPP Response Packet 15 Format
Data Element
Field
Length
Comments
<SI>
Start of
packet
1
Shift in.
15
Packet type
2
Set IPP key management mode
[Key Code]
Packet
parameters
4 or 5
The key management operation
mode for the IPP:
Control character- 0Fh
• “SPAIN” – Spain SEMP/4B
mode
• “VISA” – IPP mode
• Other characters – no change
[SO]
{LRC}
End of
packet
1
Block code
check
1
Shift out.
Control character- 0Eh
Error check character
If the terminal receives the response without any errors, then it sends ACK to the
IPP. The IPP then sends <EOT> { ASCII CODE is 04 } to terminate the
session.
Packet 15 Example: <SI>15SPAIN<SO>{LRC}
<SI>15VISA<SO>{LRC}
NOTE
( set Spain SEMP/4B mode)
( set MS / DUKPT mode)
In IPP6, the following packet 15 variation is included for compatibility purposes
only, and does not result in the key information being erased.
MX800 SERIES PROGRAMMERS GUIDE
299
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 42
Packet 15 Length: •
•
Packet 15 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 15
Packet Data
4AN
Value: 'IPP2', fixed as password
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
MAX: 9 characters
MIN: 9 characters
Table 43
Packet 15 Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>15IPP2<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
<SI>15IPP2<SO>{LRC}
ACK/NAK
EOT to terminate process.
Packet 17: Set IPP7 This packet sets or clears a number of control switches in the key management
Key Management options register for IPP7 key management configuration. IPP7 supports the
Mode following additional functions (as compared to IPP6):
•
Triple DES (3DES) DUKPT support
•
GISKE MS Key support
•
Zero (0) key support
Note that the new MAC alternatives apply only when GISKE is active, and are
selected by key attributes and not the key management switch.
For compatibility, the default key management mode for IPP7 is set to IPP5 mode
(MS- DUKPT or single DES mode). Once a new key management scheme is
selected, it is retained during power cycles.
Setting a new mode causes the IPP7 to erase all existing keys or non-volatile
security values stored for secure messaging.
Incoming Packet <SI>17[KMM][PINER]<SO>{LRC}
Format:
300
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 44
Packet 17 Format
Data Elements
Characteristics
Comments
<SI>
1H
Shift In, value: 0Fh
Packet Type
2AN
Value: 17
Key Management
Mode
2AH
The two ASCII hex digits are
concatenated big-endian, to produce a
single control byte. The key
management mode register (8 bits) in
IPP7 is as follows:
Bit
[KMM]
0
1
2
Description
0
0
0
1DES MS (default)
1
0
0
Mixed mode (1DES
and 3DES GISKE)
0
1
0
3DES GISKE MS
1
1
0
Secure messaging
(not supported in
Omni 33XX.
Bit 3
Description
0
1DES DUKPT (default)
1
3DES DUKPT
Bit 4
Description
0
Zero key support off (default)
1
Zero key support on
Bit 5
Description
0
Zero GISKE session key
support off (default)
1
Zero GISKE session key
support on
Bit 6
Description
0
N/A
1
Clear all MS master keys and
KLK
MX800 SERIES PROGRAMMERS GUIDE
301
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 44
Packet 17 Format (Continued)
Data Elements
Characteristics
Comments
Bit 7
Description
0
MAC empty working key
support off (default)
1
DUKPT Engine 1/2
Mode Flag [DEMF]
Note:
1AH
This field
was added
for IPP8
emulation.
MAC empty working key
support on
The one ASCII-Hex digit is used
produce half of a control byte.
Bit 0
( DUKPT Engine "1")
Description
0
1DES DUKPT - Default
1
3DES DUPKT
Bit 1
( DUKPT Engine "2")
Description
0
1DES DUKPT - Default
1
3DES DUPKT
Bit 2 ~ 3
---------Reserved
Example
Engine=
Packet 17 Length: •
•
302
0
1DES
1DES
0x31
1
3DES
1DES
0x32
2
1DES
3DES
0x33
3
3DES
3DES
1H
Shift Out, value: 0Eh
{LRC}
1H
Error Check
MIN: 8 characters
MX800 SERIES PROGRAMMERS GUIDE
2
DEMF = 0x30
<SO>
MAX: 8 characters
1
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Packet 17 Set IPP Key Management Mode
Master Device
Transmit
Direction
IPP
<SI>17[KMM][PINER]<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
<SI>17[KMM][PINER]<SO>{LR
C}
• ACK if LRC and key management echo
is OK
• NAK if LRC incorrect
• EOT after 3 NAKs
• EOT if LRC is correct, but key
management echo is not OK.
EOT to terminate process.
The IPP saves the new key
management accordingly.
NOTE
•
The default setting of the IPP KM mode is “old single DES mode” (IPP5/6 =
all zeros in the KMM register). When defaulting to IPP5/6 mode, the IPP is
also set to default to VISA mode (not SPAIN).
•
When the IPP receives packet 17 to change KM modes (for example, to
3DES or SM mode). the master device must know the new specification and
functions associated with the IPP. If the IPP is not in the “old single DES”
mode (IPP5/6), the IPP ignores packet 15 and will not allow itself to be
switched to SPAIN mode unless the KMM register is set to IPP5/6 mode.
•
SPAIN mode is a submode of the single DES (IPP5/6) KMM register setting.
A change from 1DES to 3DES or mixed mode will disable SPAIN mode.
•
When zero GISKE session key support is enabled (that is, on), the current
master key is used for PIN encryption only if packet Z60 has a zero GISKE
(3DES) session key and the current master key has its key attribute set to
“PIN Encryption” or “ANY.” A zero GISKE (3DES) session key means that all
fields are zero in the GISKE key block.
•
The master device must delay for at least 500 msec before send a packet to
the IPP when the KMM is switched from IPP7 to SM or from SM to IPP7.
•
Switching from SM to IPP7 mode causes a factory reset. The IPP clears the
contents of RAM and communication to the IPP is reset to the default, 1200
baud, 7 data bits, even parity, and 1 stop bit (7E1).
•
Changing the MAC empty working key support flag erases all keys (that is,
the KLK, MS key, and DUKPT key)
MX800 SERIES PROGRAMMERS GUIDE
303
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Packet 17 Examples: The following examples only illustrate the command packet sent from the master
device. Some valid IPP KMM are shown below.
1 1DES MS mode, zero key support off, zero GISKE session key support off,
and 1DES DUKPT mode:
<SI>17000<SO>{LRC}
2 Mixed MS mode, zero key support off, zero GISKE session key support off,
and 1DES DUKPT mode:
<SI>17010<SO>{LRC}
3 3DES MS mode, zero key support off, zero GISKE session key support off,
and 1DES DUKPT mode:
<SI>17020<SO>{LRC}
4 1DES MS mode, zero key support off, zero GISKE session key support off,
and 3DES DUKPT mode:
<SI>17080<SO>{LRC}
5 Mixed MS mode, zero key support off, zero GISKE session key support off,
and 3DES DUKPT mode:
<SI>17090<SO>{LRC}
6 3DES MS mode, zero key support off, zero GISKE session support off, and
3DES DUKPT mode:
<SI>170A0<SO>{LRC}
7 1DES MS mode, zero key support on, zero GISKE session support off, and
1DES DUKPT mode:
<SI>17100<SO>{LRC}
8 Mixed MS mode, zero key support on, zero GISKE session support on, and
1DES DUKPT mode:
<SI>17310<SO>{LRC}
9 3DES MS mode, zero key support off, zero GISKE session key support on,
and 1DES DUKPT mode:
<SI>17220<SO>{LRC}
10 1DES MS mode, zero key support on, zero GISKE session key support off,
and 3DES DUKPT mode:
<SI>17180<SO>{LRC}
11 Mixed MS mode, zero key support off, zero GISKE session key support on,
and 3DES DUKPT mode:
<SI>17390<SO>{LRC}
12 3DES MS mode, zero key support off, zero GISKE session key support on,
and 3DES DUKPT mode:
<SI>172A0<SO>{LRC}
304
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
The combinations of KMM setting are limited, which means that the mixtures of
MS mode, zero key support, zero GISKE session key support, DUKPT mode, and
SM mode are not applicable in some cases. If there is a conflict in the KMM
setting, the following priority rules apply:
Priority
KMM setting
Notes
1
MS/DUKPT mode vs. SM mode
If bit 1 and bit 0 of the KMM register is set
to “ONE,” the IPP switches to SM mode,
regardless how the other bits are set.
2
MS mode vs. zero key support
Zero key support is not applicable in
3DES MS mode, due to the key usage
rule (that is, single-length key use is not
allowed in 1DES MS mode).
The IPP stores the setting, but it has no
affect on the MS function.
3
MS mode vs. zero GISKE
session key support
Zero GISKE session key support is not
applicable in 1DES MS mode, due to the
key usage rule (triple-length key use is
not allowed in 3DES MS mode).
The IPP stores the setting, but it has no
affect on the MS function.
Packet 18: Check Checks the setting in the IPP7 key management options register.
IPP7 Key
Management Mode
Request Packet <SI>18<SO>{LRC}
Format Table 45
Packet 18 Format
Data Elements
Characteristics
Comments
<SI>
1H
Shift In, value: 0Fh
Packet Type
2AN
Value: 18
MX800 SERIES PROGRAMMERS GUIDE
305
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 45
Packet 18 Format
Data Elements
Characteristics
Comments
Key Management Mode
2AH
The two digits are concatenated bigendian, to produce a single control
byte. The key management mode
register (8 bits) in IPP7 is as follows:
Bit
[KMM]
0
1
2
Description
0
0
0
Old single DE
1
0
0
Mixed mode (1DES
and 3DES GISKE).
0
1
0
3DES GISKE MS
1
1
0
Secure messaging (not
supported in Omni
33XX)
Bit 3
Description
0
1DES DUKPT
1
3DES DUKPT
Bit 4
Description
0
Zero key support off
1
Zero key support on.
Bit 5
Description
0
Zero GISKE session key
support off
1
Zero GISKE session key
support on
Bit 6
Description
0
At least one MS key or KLK
key has been loaded.
1
All MS master keys and the
KLK are clear (no keys
loaded).
Bit 7
Description
0
MAC empty working key
support off.
1
306
MX800 SERIES PROGRAMMERS GUIDE
MAC empty working key
support on.
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 45
Packet 18 Format
Data Elements
Characteristics
Comments
DUKPT Engine 1/2
Mode Flag [DEMF]
1AH
The one ASCII-Hex digit is used
produce half of a control byte.
Note:
This field was
added for IPP8
emulation.
Bit 0
( DUKPT Engine "1")
Description
0
1DES DUKPT - Default
1
3DES DUPKT
Bit 1
( DUKPT Engine "2")
Description
0
1DES DUKPT - Default
1
3DES DUPKT
Bit 2 ~ 3
---------Reserved
Example:
Engine=
Packet 18 Length: •
•
1
2
DEMF = 0x30
0
1DES
1DES
0x31
1
3DES
1DES
0x32
2
1DES
3DES
0x33
3
3DES
3DES
<SO>
1H
Shift Out, value: 0Eh
{LRC}
1H
Error Check
MAX: 8 characters
MIN: 8 characters
Table 46
Packet 18 Check IPP7 Key Management Mode
Master Device
Transmit
Direction
IPP
<SI>18<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
<SI>18[KMM][PINER]<SO>{LRC}
MX800 SERIES PROGRAMMERS GUIDE
307
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 46
Packet 18 Check IPP7 Key Management Mode
Master Device
Transmit
Direction
IPP
• ACK/NAK
EOT to terminate process.
Packet 18 Examples: The following examples show the response packet,
<SI>18[KMM][PINER]<SO>{LRC} from the IPP.
1 1DES MS mode, zero key support off, zero GISKE session key support off,
and 1DES DUKPT mode:
<SI>18000<SO>{LRC}
2 Mixed MS mode, zero key support off, zero GISKE session key support off,
and 1DES DUKPT mode:
<SI>18010<SO>{LRC}
3 3DES MS mode, zero key support off, zero GISKE session key support off,
and 1DES DUKPT mode:
<SI>18020<SO>{LRC}
4 1DES MS mode, zero key support off, zero GISKE session key support off,
and 3DES DUKPT mode:
<SI>18080<SO>{LRC}
5 Mixed MS mode, zero key support off, zero GISKE session key support off,
and 3DES DUKPT mode:
<SI>18090<SO>{LRC}
6 3DES MS mode, zero key support off, zero GISKE session support off, and
3DES DUKPT mode:
<SI>180A0<SO>{LRC}
7 1DES MS mode, zero key support on, zero GISKE session support off, and
1DES DUKPT mode:
<SI>18100<SO>{LRC}
8 Mixed MS mode, zero key support on, zero GISKE session support on, and
1DES DUKPT mode:
<SI>18310<SO>{LRC}
9 3DES MS mode, zero key support off, zero GISKE session key support on,
and 1DES DUKPT mode:
<SI>18220<SO>{LRC}
10 1DES MS mode, zero key support on, zero GISKE session key support off,
and 3DES DUKPT mode:
308
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
<SI>18180<SO>{LRC}
11 Mixed MS mode, zero key support off, zero GISKE session key support on,
and 3DES DUKPT mode:
<SI>18390<SO>{LRC}
12 3DES MS mode, zero key support off, zero GISKE session key support on,
and 3DES DUKPT mode:
<SI>182A0<SO>{LRC}
13 1DES MS mode, zero key support on, zero GISKE session key support off,
and 3DES DUKPT mode:
<SI>18580<SO>{LRC}
14 Mixed MS mode, zero key support on, zero GISKE session key support on,
and 3DES DUKPT mode
<SI>18790<SO>{LRC}
15 3DES MS mode, zero key support off, zero GISKE session key support on,
and 3DES DUKPT mode:
<SI>186A0<SO>{LRC}
Packet Z60: Accept On receipt of the Z60 packet, Omni 33XX reads the user’s PIN from the keyboard,
and Encrypt PIN echoing to the display an asterisk for each digit accepted. The PIN length can be
(VISA Mode) between 4 and 12 digits. There are two variations of the request packet: Master/
Session and DUKPT.
Sample Packet Z60 Request <STX>Z60.[acct num]<FS>[working key]<ETX>{LRC}
for MS Response <STX>71.0[PIN len][PIN block format]
[encrypted PIN block]<ETX>{LRC}
Sample Packet Z60 Request <STX>Z60.[acct num]<FS>DUKPT ENCRYPTION<ETX>{LRC}
for DUKPT Response <STX>73.00000[key serial number]
[encrypted PIN block]<ETX>{LRC}
On receipt of a packet Z60 that contains the account number and working key (if
MS) or DUKPT ENCRYPTION (if DUKPT), the IPP gets the PIN from the user
then checks if MS or DUKPT is selected.
•
If MS is selected, the IPP encrypts the formatted PIN block using the working
key that was decrypted using the selected master key. The IPP returns the
cipher-text PIN block using packet 71 (see MS Packet 71: Transfer PIN Block).
•
If DUKPT is selected, the IPP encrypts the formatted block using the DUKPT
algorithm. The IPP returns the key serial number and cipher-text PIN block
using packet 73 (see DUKPT Packet 73: Transfer PIN Block (for Packets Z60
or Z63)).
Packet Z60 Format <STX>Z60.[aaa…aaa]<FS>[www…www]<ETX>{LRC}
MS
MX800 SERIES PROGRAMMERS GUIDE
309
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Packet Z60 Format <STX>Z60.[aaa…aaa]<FS>[DUKPT ENCRYPTION]<ETX>{LRC}
DUKPT Table 47
Packet Z60 Format
Data Elements
Characteristics
Comments
<STX>
1H
Start of Text, Value: 02h
Packet Type
3AN
Value: Z60
Packet Delimiter
1A
Value: (.), 2Eh
[aaa...aa]
8-19N
Card account number
<FS>
1H
Field Separator, Value: 1Ch
[www...www]
or
DUKPT
ENCRYPTION
16AH or 120AH
[www….www] – encrypted working key
(encrypted session key)
DUKPT ENCRYPTION means DUKPT is
selected. Otherwise, it is the working key of
MS encrypted under the master key. GISKE is
used here for 3DES session key support.
Size of [www…www] indicates which packet
format is used:
• 16AH – 1DES, key-only format
• 120AH – GISKE key block format. For more
details on GISKE refer GISKE Key Block
Spec, VPN 22986.
• (1DES only) If zero key support is enabled
and the encrypted working key is zero-filled,
the currently selected master key is used as
the working key.
• (1DES only) If zero key support mode is
disabled, the passed key is used regardless
of the encrypted key value.
• Zero GISKE session key support for GISKE
key block format communication protocol.
(see Using a Session Key).
• Zero key support and zero GISKE session
key support are controlled by a switch in the
key management option register set using
packet 17 and checked using packet 18.
Packet Z60 Length: •
•
<ETX>
1H
End of Text, Value: 03h
{LRC}
1H
Error Check
Maximum: 147 characters
Minimum: 32 characters
Sample Packet Z60 <STX>Z60.0123456789012345678<FS>0123456789012345<ETX>{LRC}
for MS 1DES:
Sample Packet Z60 <STX>Z60.0123456789012345678<FS>DUKPT ENCRYPTION<ETX>{LRC}
for DUKPT:
Sample Packet Z60 <STX>Z60.0123456789012345678<FS>01234567890123456789012345678901234567890
for MS GISKE: 1234567890123456789012345678901234567890123456789012345678901234567890123
456789<ETX>{LRC}
310
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Errors returned by write()
Some packet format errors are caught when the packet is written to the IPP. In this
case, write() returns –1 and errno set. The packet is not ACKed or NAKed, and
no response packet returns.
Z60 Format Error
errno
No <FS>
EINVAL
PIN entry too fast.
EACESS
See Restrict the Speed of the PIN Encryption Operation.
Packet Z63: Accept
and Encrypt PIN–
Custom PIN Entry
Requirements
(VISA Mode)
On receipt of the Z63 packet, Omni 33XX reads the user’s PIN from the keyboard,
echoing to the display [echo char] for each digit accepted. The PIN length can be
between [min len] and [max len] digits, inclusive, or 0 if the
[NULL allowed flag] is set. There are two variations of these request
packets: MS and DUKPT.
Sample Packet Z63 Request <STX>Z63.[acct num]<FS>[working key][min len][max len]
for MS [NULL allowed flag][echo char]<ETX>{LRC}
Response
Sample Packet Z63 Request
for DUKPT
Response
<STX>71.0[PIN len][PIN block format]
[encrypted PIN block]<ETX>{LRC}
<STX>Z63.[acct num]<FS>DUKPT ENCRYPTION[min len][max len]
[NULL allowed flag][echo char]<ETX>{LRC}
<STX>73.00000[key serial number][encrypted PIN block]<ETX>{LRC}
Note that [min len] and [max len] are two-character ASCII digits that
represent values between 04 and 12, inclusive. [max len] should not be less
than [min len] that is:
04
≤ [min len] ≤ [max len] ≤ 12
Furthermore, [NULL allowed flag] and [echo char] each are 1-byte
values with the following requirements:
•
[NULL allowed flag] = Y allows a zero-length PIN entry
•
[NULL allowed flag] = N does not allow zero-length PIN entries
•
[echo char] should be displayable and cannot be <STX>, <ETX>, <SI>,
<SO>, or <FS>, even if the currently selected font can display characters 02h,
03h, 0Fh, 0Eh, or 1Ch.
If any of these four fields do not conform to the restrictions, then the packet is
rejected by the driver (return code of -1 with errno set to EINVAL).
Table 48
Packet Z63 Format
Data Elements
Characteristics
Comments
<STX>
1H
Start of Text, Value: 02h
Packet Type
3AN
Value: Z63
Packet Delimiter
1A
Value: (.), 2Eh [aaa...aa] 8-19N Card
account number
MX800 SERIES PROGRAMMERS GUIDE
311
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Table 48
Packet Z63 Format (Continued)
Data Elements
Characteristics
Comments
<FS>
1H
Field Separator; Value: 1Ch
[www...www]
16AH or 120AH
Encrypted working key or (encrypted
session key) DUKPT. DUKPT
ENCRYPTION means DUKPT is
ENCRYPTION selected. Otherwise, it is
the working key of MS encrypted under
the master key. GISKE is used here for
3DES session key support.
Size of [www…www] indicates which
packet format is used:
• 16AH: 1DES, key-only format
• 120AH: GISKE key block format. For
more details on GISKE refer GISKE
Key Block Spec, VPN 22986.
• (1DES only) If zero key support is
enabled and the encrypted working key
is zero-filled, the currently selected
master key is used as the working key.
• (1DES only) If zero key support mode is
disabled, the passed key is used
regardless of the encrypted key value.
•
Zero GISKE session key support for
GISKE key block format communication
protocol. (see Using a Session Key).
• Zero key support and zero GISKE
session key support are controlled by a
switch in the key management option
register set using packet 17 and
checked using packet 18.
[min len]
2N
Minimum PIN length. 04–12
[max len]
2N
Maximum PIN length. 04–12
[Null PIN allowed]
1A
Null (zero length) PIN allowed. Y or N.
[echo char]
1AN
Echo character.
<ETX>
1H
End of Text, Value: 03h
{LRC}
1H
Error Check
Errors returned by write()
Some packet format errors are caught when the packet is written to the IPP. In this
case, write() returns –1 and errno set. The packet is not ACKed or NAKed, and
no response packet returns.
Z60 Format Error
errno
No <FS> invalid MIN, MAX, echo character, or null PIN flag
EINVAL
PIN entry too fast.
EACESS
See Restrict the Speed of the PIN Encryption Operation.
312
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Common Packets
Packet M04: Read This command is used to check the permanent unit serial number.
Permanent Unit
Serial Number
NOTE
This packet is added for IPP8 emulation.
Request Packet <SI>M04<SO>{LRC}
Format Table 49
Packet M04 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, value: 0Fh
Packet Type
3AN
Value: M04
<SO>
1H
Shift Out, value: 0Eh
{LRC}
1H
Error Check
Packet M04 Length: •
Maximum: 6 characters
•
Minimum: 6 characters
Response Packet <SI>M04[PUSN]<SO>{LRC}
Format
Table 50
Packet M04 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, value: 0Fh
Packet Type
3AN
Value: M04
Permanent Unit Serial
Number [PUSN]
11AN
Unit Serial Number format:
<SO>
1H
Shift Out, value: 0Eh
{LRC}
1H
Error Check
xxx-xxx-xxx
Packet M04 Length: •
Maximum: 17 characters
•
Minimum: 17 characters
Table 51
Packet M04 Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>M04<SO>{LRC}
• ACK if LRC okay.
• NAK if LRC incorrect (EOT after 3 NAKs).
<SI>M04[PUSN]<SO>{LRC}
MX800 SERIES PROGRAMMERS GUIDE
313
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 51
Packet M04 Communication Protocol (Continued)
Transmit
Direction
Master Device
IPP
• ACK if LRC okay
• NAK if LRC
incorrect (EOT
after 3 NAKs).
EOT terminates session.
MS-Specific
Packets
The following packets are specific to MS 1DES and 3DES operations. The default
mode for the IPP at power up is MS 1DES.
Packet 02: Transfer The master device uses this packet to send a master key to the IPP. The response
Master Key from the IPP to the master device depends on the value of the key management
option register.
Table 52
MS Packet 02 Format
Data Element
Characteristic
Comments
<STX>
1H
Shift In, Value: 0Fh
Packet Type
3AN
Value: 02
[n]
1N
Address or key usage identifier.
1DES:
• Master key address is 0-9
3DES:
• Master key address for double- or triple-length
keys is 0–9, 'Fa
[hhh...hh]
16H
Master key in ASCII.
• 16Ah: 1DES mode for single-length key
• 120Ah: GISKE mode for double- and triple-
length key, including key block header, master
key, and MAC. For more details on GISKE
refer GISKE Key Block Spec, VPN 22986.
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
a.
MS Packet 02 Length: •
•
When the GISKE KEK is passed to the IPP in this message, the KEK usage identifier is
checked in the GISKE key header block before the key is accepted.
MAX: 126 characters
MIN: 22 characters
Communication Protocols
Each key stored in the IPP contains its own key attributes.
314
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Key-only Format
The key attribute information is not available when the key is loaded using the
key-only format (as compared to the GISKE communication protocol). The IPP
sets the default attributes to the key, as shown in Table 53.
Table 53
Default Key Attributes
Key Attributes
Value
Hex
Definition
Key usage
AN
0x41, 0x4E
Any; no special restrictions
Key Algorithm
D
0x44
DES
Key mode of use
N
0x4E
No special restrictions
Key version
00
0x30, 0x30
version = zero
Key length
1
0x31
single-length key
The single-DES communication protocol between the master device and the IPP
as follows:
Sample Packet 02 in This sample packet requests the IPP to load master key 0123456789ABCDEF
Key-only Format into location '0'.
<SI>0200123456789ABCDEF<SO>{LRC}
Table 54
Packet 02 Key-Only Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>02[n][hhhhhhhhhhhhhhhh]<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
<SI>02[n][hhhhhhhhhhhhhhhh]<SO>{LRC}
• ACK if LRC and key echo
are okay
• NAK if LRC incorrect
• EOT after 3 NAKs
• EOT if LRC correct, but key
echo incorrect
• IPP saves the new master key only
on receipt of ACK
• EOT terminates session
MX800 SERIES PROGRAMMERS GUIDE
315
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
GISKE Key Block Format
3DES communication protocol between the master device and the IPP is as
follows:
Sample Packet 02 in This sample packet requests that the IPP load the 120-byte GISKE key block into
GISKE Key Block address 0
Format: “0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
0123456789ABCDEF0123456789ABCDEF012345678901234567890123:”
<SI>
02000123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF01234
56789ABCDEF0123456789ABCDEF012345678901234567890123<SO>{LRC}
Table 55
Packet 02 Response Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 02
[n]
1N
Response code (0–7):
• 0 = No error
• 1 = Error: IPP in incorrect KM mode
• 2 = Error: incorrect key usage, mode of use,
algorithm, or key length
• 3 = Version error
• 4 = Error: KLK already exists or new KLK was
not encrypted from the previous KLK
• 5 = GISKE decryption or MAC error
• 6 = Error: master key address does not
match the address range described in Packet
02: Transfer Master Key
• 7 = Error: inappropriate master key
addressing
Packet 02 GISKE Key •
Block Format Length:
•
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
MAX: 102 characters
MIN: 6 characters
Packet 02 GISKE Key <SI>020<SO>{LRC}
Block Format
Example:
316
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 56
Packet 02 GISKE Key Block Format Communication Protocol
Transmit
Direction
Master Device
IPP
<SI>02[r][hhh.hhh]<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
<SI>02[n]<SO>{LRC}
• ACK if LRC, no errors, and key
echo okay
• NAK if LRC incorrect
• EOT after 3 NAKs
• EOT if LRC correct, but key echo
incorrect
• IPP saves new key only on
receipt of ACK
• EOT terminates session
Packet 04: Check The master device sends this packet to check if the IPP has a master key stored
Master Key at a designated master key address. To avoid an overwrite, this packet must be
sent before sending packet 02 to check that a valid master key is already stored in
the designated address.
Table 57
MS Packet 04 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 04
[a]
1N
Master Key address: 0–9
KLK: F
MS Packet 04 Length: •
•
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
MAX: 6 characters
MIN: 6 characters
MX800 SERIES PROGRAMMERS GUIDE
317
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Packet 04 Communication Protocol
Packet 04 has two types of communication format: key-only and GISKE key block
format. The communication format depends on the IPP key management setting
and the length of the key at address [a]. The use of the communication protocol is
as follows:
IPP Key Management Setting
Key Length at
Address [a]
Communication
Protocol Used
1DES mode
1DES (single-length
key)
Key-only format (IPP5/
IPP6)
3DES (single-, double, or triple-length key)
GISKE key block
formata
1DES (single-length
key)
GISKE key block format
3DES (single-, double, or triple-length key)
GISKE key block format
Mixed or 3DES mode
a.
If a single-, double-, or triple-length key stored in the IPP contains the key attribute
information described in the GISKE specification, this indicates that master device must be
compatible with the IPP7 (3DES) specification. Therefore, the master device can
understand the GISKE key block format communication protocol.
Packet 04 Key-only Format
To check if the master key is loaded at address 5, the request sample packet 04
for key-only format is
<SI>045<SO>{LRC}
Table 58
Response Packet 04 Key-only Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 04
[r]
1AN
Response code:
• 0 = No master key at address [a]
• F = Master key present at address [a]
318
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 59
Response Packet 04 Key-only Format Communication
Protocol
Transmit
Direction
Master Device
IPP
<SI>040<SO>{LRC}
• ACK if LRC okay
• NAK if LRC incorrect
• EOT after 3 NAKs
• PIN pad checks requested address [a].
<SI>04[r]<SO>{LRC}
• ACK if LRC okay
• NAK if LRC incorrect
• EOT after 3 NAKs
EOT
Response Packet 04 •
Key-only Format
•
Length:
MAX: 6 characters
MIN: 6 characters
Response Packet 04 <SI>040<SO>{LRC}
Key-only Format
Example: Packet 04 GISKE Key Block Format
The GISKE key block format communication protocol is used when the IPP is in
mixed or 3DES mode. The original GISKE (ASCII-hex) key usage attribute value
is saved in RAM (2 bytes).
<SI>042<SO>{LRC}
Table 60
Response Packet 04 GISKE Key Block Format
Data
Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 04
[r]
1AN
Response code:
• 0 = No master key at address [a]
• F = Master key present at address [a]
MX800 SERIES PROGRAMMERS GUIDE
319
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 60
Response Packet 04 GISKE Key Block Format (Continued)
Data
Element
Key Usage
Attribute (KUA)
Characteristic
Comments
2AH
Only when master key is present at address [a]:
• AN: ANY: The key is available in the IPP, but
was not loaded using GISKE format.
• D0: Data encryption
• I0: IV
• T0: control vector
• K0: key encryption or wrapping
• G0: MAC generation
• M0: MAC verification
• P0: PIN encryption
• V0: PIN verification
• C0: CVK (card verification key)
• B0: BDK (base derivation key [A])
• 00: ISO 9797-1 MAC algorithm 1 (1–56 bits)
• 10: ISO 9797-1 MAC algorithm 1 (1–112 bits)
• 20: ISO 9797-1 MAC algorithm 2 (2–112 bits)
• 30: ISO 9797-1 MAC algorithm 3 (3–112 bits)
• 40: ISO 9797-1 MAC algorithm 4 (4–112 bits)
• 50: ISO 9797-1 MAC algorithm 5 (5–56 bits)
• 60: ISO 9797-1 MAC algorithm 5 (5–112 bits)
Algorithm
1AH
(optional) Only if the master key is present at
address [a]. The value is stored in the Key
Attributes register.
• D: DES [0]
• R: RSA [1]
• A: AES [2]
• S: DSA [3]
• T: TDES [4]
• U: Unknown [5]
• E: Elliptic Curve [6]
• [7]–[F] = Reserved
Note:
320
MX800 SERIES PROGRAMMERS GUIDE
To save storage space in RAM, the
algorithm attribute is converted to [x], a
hex number ranging form 0–F (4 bits). In
the response packet (to packet 04), the
IPP converts the number back to
characters used in GISKE specification.
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 60
Data
Element
Mode of Use
Attribute
(MOUA)
Response Packet 04 GISKE Key Block Format (Continued)
Characteristic
Comments
1AH
(optional) Only if the master key present at
address [a]. The value is stored in the key
attributes register.
• N: No special restrictions [0]
• E: Encryption only [1]
• D: Decryption only [2]
• S: Signature only [3]
• 0: IV [4]
• G: MAC generate [5]
• V: MAC verify [6]
• C: Calculate = generate or verify) [7]
• [6]–[F]: Reserved
Note:
Key Version
(KV)
2AH
(optional) Only if the master key present at
address [a]. The 2-digit ASCII character version
number is optionally used to reinject old keys. If
not used, this field is filled with ASCII 0 (0x30).
Note:
Key Length
(KL)
1AH
To save storage space in RAM, the
mode of use attribute is converted to [x],
a hex number ranging form 0–F (4 bits).
In the response packet (to packet 04),
the IPP converts the hex number back
to characters used in the GISKE
specification.
The IPP allocates 1 byte per key for
each key version register.
(optional) Only if the master key present at
address [a].
• 1: single-length key
• 2: double-length key
• 3: triple-length key
Note:
Response Packet •
GISKE Block Format
•
04 Length:
The IPP allocates 1 byte per key for
each key version register.
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
MAX: 12 characters
MIN: 12 characters
Response Packet 04 <SI>040[KUA][MOUA][MACMA][KV][KL]<SO>{LRC}
GISKE Block Format
Example:
MX800 SERIES PROGRAMMERS GUIDE
321
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 61
Response Packet 04 GISKE Block Format Communication
Protocol
Transmit
Direction
Master Device
IPP
<SI>04[a]<SO>{LRC}
• ACK if LRC okay
• NAK if LRC incorrect
• EOT after 3 NAKs
• PIN pad checks requested address [a].
<SI>04[r][KUA][MOUA][MACMA][KV][KL]<SO>{L
RC}
• ACK if LRC okay
• NAK if LRC incorrect
• EOT after 3 NAKs
EOT
MS Packet 08: The master device sends this packet to the IPP to select one of the ten possible
Select a Master Key master keys (0–9). It is recommended that the master device should always send
this packet first before sending a packet (for example, Packet Z60: Accept and
Encrypt PIN (VISA Mode)) to request for PIN entry.
Table 62
MS Packet 08 Length: •
•
MS Packet 08 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 08
[a]
1N
Master Key address: 0–9
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
MAX: 6 characters
MIN: 6 characters
MS Packet 08 To select Master Key 7:
Example:
<SI>087<SO>{LRC}
322
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MS-Specific Packets
Table 63
MS Packet 08 Communication Protocol
Transmit
Direction
Master Device
IPP
<SI>08[a]<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
• PIN pad makes master key [a] active.
EOT
Notes 1
The 1DES and 3DES key usage rules (see Rules for Loading the Master Key
(MS only)) applies when selecting a master key. If the selecting master key is
not available or is not applicable due to the 1DES or 3DES key usage rule, no
response is returned to the master device.
2 If the master key address does not contain any key, the IPP still sets the
currently selected key as the active master key due to a backward
compatibility requirement.
MS Packet 71: Response packet to Packet Z60: Accept and Encrypt PIN (VISA Mode) and
Transfer PIN Block Packet Z63: Accept and Encrypt PIN–Custom PIN Entry Requirements (VISA
Mode). The IPP encrypts the formatted clear-text PIN block and sends the ciphertext PIN block to the master device.
Table 64
MS Packet 71 Length: •
•
MS Packet 71 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of Text, Value: 02h
Packet Type
2AN
Value: 71
Packet
Delimiter
1A
Value: (.), 2Eh
Function Key
Indicator
1N
Value is 0; Function key feature not
implemented.
PIN Length
2N
Range 00, 04 to 12
PIN BLock
Format
2N
Value: 01; Format of PIN block prior to
encryption
Encrypted PIN
Block
16H
The 64-bit encrypted PIN block represented as
16 hexadecimal digits. Present only if PIN
entered.
<ETX>
1H
End of Text, Value: 03h
{LRC}
1H
Error check
MAX: 27 characters
MIN: 27 characters
MX800 SERIES PROGRAMMERS GUIDE
323
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
DUKPT-Specific Packets
MS Packet 71 <STX>71.000010123456789123456<ETX>{LRC}
Example:
This packet 71 is the response packet to PIN request Z60 and Z63 when no errors
are detected in the Z60 or Z63 packet. If errors are detected in the Z60 or Z63
packet, the response packet is in the following format:
Table 65
MS Response Packet 71 Format: Errors in Z60 or Z63 Packets
Data Element
Characteristic
Comments
<STX>
1H
Start of Text, Value: 02h
Packet Type
2AN
Value: 71
Error Code
1N
• 1 = no master key
• 2 = account or working key error
• 3 = PIN too long.
• 4 = PIN too short / non-decimal digit(s) in PIN.
• 5 = PIN pad used as DUKPTa
• 6 = Master key attributes error
• 7 = KOF/GISKE working key attributes error,
key attributes: key usage, algorithm, mode of
use, key version, or key length
<ETX>
1H
End of Text, Value: 03h
{LRC}
1H
Error Check
a.
MS Packet 71 Length: •
•
Error code 5 does not occur in the IPP, since it supports simultaneous DUKPT and MS.
MAX: 6 characters
MIN: 6 characters
MS Packet 71 <STX>711<ETX>{LRC}
Example:
Packet 07: Dummy To have the IPP pass the DES reliability test on the MKI program, a dummy
Packet packet 07 is added. When this packet is received, the IPP only returns an <ACK>,
followed by an <EOT> after a 1 second delay (this delay is necessary for
compatible with the MKI program).
DUKPT-Specific
Packets
The following packets are specific to DUKPT operation. Two DUKPT modes are
implemented in IPP7: 1DES or 3DES. All keys associated with DUKPT are erased
when switching between 1DES and 3DES DUKPT modes.
Packet 19: Select a The application sends this packet to the IPP to select one of the DUKPT engines
DUKPT Engine ("0", "1", or "2"). It is recommended that the application always send this packet
first before sending a DUKPT packet (eg. packet Z60, Z63, 76, Z69 and 90).
NOTE
This packet was added for IPP8 emulation.
324
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
DUKPT-Specific Packets
Table 66
DUKPT Packet 19 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift In, Value: 0Fh
Packet Type
2AN
Value: 19
[a]
1N
DUKPT Engine: "0", "1",or "2"
<SO>
1H
Shift Out, Value: 0Eh
{LRC}
1H
Error Check
DUKPT Packet 19 Length:
Maximum: 6 characters
Minimum: 6 characters
Sample Packet: To select second DUKPT Engine:
<SI>192<SO>{LRC}
Table 67
DUKPT Packet 19 Communication Protocol
Master Device
Transmit
Direction
IPP
<SI>19[a]<SO>{LRC}
• ACK if LRC okay
• NAK if LRC incorrect (EOT after 3 NAKs).
Echo packet 19 setting
<SI>19[a]<SO>{LRC}
• ACK if LRC okay
• NAK if LRC incorrect
(EOT after 3 NAKs)
…
IPP changes DUKPT engine
…
EOT to terminate process.
NOTE
• If there is any packet format error, IPP does not echo the response packet back to the
master device. The incorrect packet format includes out of range DUKPT engine,
incorrect packet type, incorrect packet length, etc.
• The default DUKPT engine is set to "0".
MX800 SERIES PROGRAMMERS GUIDE
325
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Packet 25: Check The application sends this packet to the IPP to check the current active DUKPT
the DUKPT Engine engines ("0", "1", or "2").
NOTE
This packet is added for IPP8 emulation.
Request Packet <SI>25<SO>{LRC}
Format Table 68
Packet 25 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift in, value: 0Fh
Packet Type
2AN
Value: 25
<SO>
1H
Shift out, value: 0Eh
{LRC}
1H
Error check
Packet 25 Length: •
Maximum: 5 characters
•
Minimum: 5 characters
Response Packet <SI>25[PUSN]<SO>{LRC}
Format
Table 69
Packet 25 Format
Data Element
Characteristic
Comments
<SI>
1H
Shift in, value: 0Fh
Packet Type
2AN
Value: 25
[a]
1N
Active DUKPT Engine: "0", "1",or "2"
<SO>
1H
Shift Out, value: 0Eh
{LRC}
1H
Error Check
Packet 25 Length: •
Maximum: 6 characters
•
Minimum: 6 characters
Sample Packet:
To Check DUKPT Engine:
<SI>25<SO>{LRC}
Response packet, DUKPT Engine "1" = active DUKPT Engine:
<SI>251<SO>{LRC}
326
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Table 70
Packet 25 Communication Protocol
Transmit
Direction
Master Device
IPP
<SI>25<SO>{LRC}
• ACK if LRC okay.
• NAK if LRC incorrect (EOT after 3
NAKs).
Response current active DUKPT
engine.
<SI>25[a]<SO>{LRC}
• ACK if LRC okay
• NAK if LRC incorrect (EOT
after 3 NAKs).
EOT terminates session.
DUKPT Packet 73:
Transfer PIN Block
(for Packets Z60 or
Z63)
Response packet to Packet Z60: Accept and Encrypt PIN (VISA Mode) and
Packet Z63: Accept and Encrypt PIN–Custom PIN Entry Requirements (VISA
Mode). The IPP encrypts the formatted clear-text PIN block and sends the ciphertext PIN block to the master device.
Table 71
DUKPT Packet 73 •
Length:
•
DUKPT Packet 73 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, Value: 02h
Packet Type
2AN
Value: 73
Packet
Delimiter
1A
Value: (.), 2Eh
00000
5N
Value: 00000
[KSN]
10–20AH
Key serial number; hex. (leading Fs
suppressed). Presented only if a PIN is entered;
length is 0 if no PIN is entered.
Encrypted PIN
Block
16AH
The 64-bit encrypted PIN block represented as
16 hexadecimal digits.
<ETX>
1H
End of text, Value: 03h
{LRC}
1H
Error check
MAX: 47 characters
MIN: 27 characters
DUKPT Packet 73 <STX>73.0000001234567890123456789123456<ETX>{LRC}
Example:
Packet 73 is the response packet to Packet Z60: Accept and Encrypt PIN (VISA
Mode), the PIN request packet with no errors detected. If errors are detected in
the Z60 or Z63 packet, the response packet is in the following format:
MX800 SERIES PROGRAMMERS GUIDE
327
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Table 72
MS Response Packet 73 Format: Errors in Z60 or Z63 Packet
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 73
Error Code
1N
• 1 = no key
• 2 = account error
• 3 = PIN too long
• 4 = PIN too short / non-decimal PIN digit in
PIN
• 5 = PIN pad used as MSa
• 6 = PIN pad has over 1 million transactions
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
a.
DUKPT Packet 73 •
Length:
•
Error code 5 do not occur in the IPP, since the IPP supports simultaneous DUKPT and MS.
MAX: 6 characters
MIN: 6 characters
DUKPT Packet 73 <STX>731<ETX>{LRC}
Example:
DUKPT Packet 90: Loads initial key to the IPP. After the initialization of packet 21, future keys, the IPP
Load Initial Key responds with packet 91 with confirmation status.
Request
Table 73
DUKPT Packet 90 •
Length
•
NOTE
328
DUKPT Packet 90 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, Value: 02h
Packet Type
2AN
Value: 90
[IPEK]
16H
Initial PIN Encryption Key, hexadecimal
[KSN]
20H
Key Serial Number; hex (leading Fs included)
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check character
MAX: 57 characters
MIN: 41 characters
The difference between DUKPT 1DES mode and DUKPT 3DES mode is in the
size of the initial PIN encryption key and the sizes of the future keys.
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Table 74
DUKPT Packet 90 Communication Protocol
Transmit
Direction
Master Device
IPP
90 Packet
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
• Initialization of 21 Future Keys
Packet 91 with confirmed status
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
DUKPT Packet 91: Response packet to packet 90. Response to controller with confirmation status. If
Load Initial Key 21 Future Keys are successfully initialized, Packet 91 responds with confirmation.
Response Else, negative response packet 91 returns.
Table 75
DUKPT Packet 91 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, Value: 02h
Packet Type
2AN
Value: 91
[CS]
1N
Confirmation status:
• 0 = Confirmed
• 1 = Not confirmed
• 2 = (IPP7 only) Error; incorrect key length.
Confirmation status 2 only applies to IPP7. It
indicates that the length of the initial PIN
encryption key does not comply with 1DES or
3DES DUKPT mode, as follows:
DUKPT Packet 91 •
Length
•
Initial PIN
encryption key length
(through packet 90)
sent by the master device
IPP7 Current
DUKPT Mode
[CS] response from
the IPP
16AH
3DES
2
32AH
1DES
2
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check character
MAX: 6 characters
MIN: 6 characters
MX800 SERIES PROGRAMMERS GUIDE
329
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Table 76
DUKPT Packet 91 Communication Protocol
Transmit
Direction
Master Device
IPP
Packet 91
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
DUKPT Packet 76: Directly presets the PIN code '1234' to do encryption and send response
PIN Entry Test packet 71.
Request
Table 77
DUKPT Packet 76 •
Length
•
NOTE
Table 78
DUKPT Packet 76 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 76
[account#]
8-19N
Card account number
<FS>
1H
Field separator, value: 1Ch
[C/D]
1H
Credit/Debit indicator, value: 43h/44h
[amount]
3-7N
Transaction amount must include the decimal
point.
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 33 characters
MIN: 18 characters
The amount filed must be present in the packet command, but the format is not
confirmed.
DUKPT Packet 76 Communication Protocol
Master Device
Transmit
Direction
IPP
76 Packet
• ACK if LRC
• NAK if LRC incorrect
Packet 71 with PIN = 1234
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
330
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
DUKPT Packet 71: Response packet to packet 76, request for PIN. The IPP encrypts the formatted
Transfer PIN Block - clear-text PIN block and sends the cipher-text PIN block to the master device.
(for Packet 76) (refer to the VISA PIN Processing and Data Authentication specification,
International version 1.0)
Packet 71 has a different packet format and meaning than the response PIN block
71 in MS. This is for compatibility with existing third parties (for example, Racal) to
initialize the DUKPT key.
Table 79
DUKPT Packet 71 •
Length:
•
DUKPT Packet 71 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 71
Function Key
1N
Value: 0, function key indicator feature not
implemented
Key Serial
Number
10-20H
Hexadecimal (leading Fs suppressed.);
Included only if PIN entered; length is 0 if no PIN
entered
Encrypted PIN
Block
16H
The 64-bit encrypted PIN block represented as
16 hexadecimal digits; length is 0, if no PIN
entered.
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 42 characters
MIN: 6 characters (if NULL entered)
DUKPT Packet 71 <STX>710[KSN]0123456789123456<ETX>{LRC}
Example:
When no errors are detected in packet 76, the IPP returns response packet 71. If
errors are detected in packet 76, response packet 71 is in the following format:
Table 80
DUKPT Packet 71 Format: Errors Detected in Packet 76
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 71
Error Code
1N
• 1 = no key
• 2 = account error
• 5 = C|D field error
• 6 = PIN pad has over 1 million transactions
DUKPT Packet 71 •
Length:
•
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 6 characters
MIN: 6 characters (if NULL entered)
MX800 SERIES PROGRAMMERS GUIDE
331
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
DUKPT Packet 71 <STX>711<ETX>{LRC}
Example:
DUKPT Packets 92 The DUKPT reinitialization request and reinitialization response packets are not
and 93 supported in Omni 33XX.
DUKPT Z69 Packet:
Accept and Encrypt
PIN / Data
Authentication
Request
On receipt of the Z69 packet, Omni 33XX reads the user’s PIN from the keyboard,
echoing to the display an asterisk for each digit accepted. The PIN length can be
between 4 and 12 digits.
Table 81
DUKPT Packet Z69 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
3AN
Value: Z69
[account#]
8–19N
Card account number.
<FS> or <US>
1H
<FS> is the field separator that indicates VISA
MACing is used.
<US> is the field separator that indicates ANSI
9.19 MACing is used.
DUKPT Packet Z69 •
Length
•
[C/D]
1H
Credit/debit indicator, value 43h/44h
[amount]
3–13N
Transaction amount including the decimal point.
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check character
MAX: 24 characters
MIN: 45 characters
Table 82
DUKPT Packet Z69 Communication Protocol
Master Device
Transmit
Direction
IPP
Z69 Packet
• ACK of LRC okay
• NAK if LRC incorrect
• EOT after 3 NAKs
Packet 75 with confirmed status
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
DUKPT Packet Z69 VISA:
Example:
<STX>Z6901234567890<FS>C19.99<ETX>{LRC}
ANSI:
<STX>Z6901234567890<US>C19.99<ETX>{LRC}
332
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Errors returned by write()
Some packet format errors are caught when the packet is written to the IPP. In this
case, write() returns –1 and errno set. The packet is not ACKed or NAKed, and
no response packet returns.
DUKPT Packet 75:
DUKPT Accept and
Encrypt PIN/Data
Authentication
Response
Z60 Format Error
errno
No <FS>
EINVAL
Response packet to packet DUKPT Z69 Packet: Accept and Encrypt PIN / Data
Authentication Request or Packet 78: DUKPT Accept and Encrypt PIN/Data
Authentication Test Request to the controller with confirmation status.
Authentication code #1 is the MAC on this message. If the request is approved,
the MAC received with the approval response message exactly matches
authentication code #2. If the request is declined, the MAC received with the
decline response message must exactly match authentication code #3.
Table 83
DUKPT Packet 75 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 75
[Auth. Code #1]
8H
Authentication code #1, message MAC
In ANSI mode, Auth Code is padded with all 0s
(0x30h).
[Auth. Code #2]
8H
Authentication code #2, transaction approved
check value
In ANSI mode, Authentication Code #2 is the left
4 bytes of the MAC value.
[Auth. Code #3]
8H
Authentication code #3, transaction declined
check value
In ANSI mode, Authentication Code #3 is the
right 4 bytes of the MAC value.
DUKPT Packet 75 •
Length:
•
Function Key
1N
Value is 0, Function Key Indicator feature not
implemented
Key Serial
Number
10–20H
Hexadecimal (leading Fs suppressed.);
Included only if PIN entered; Length is 0 if no PIN
entered
Encrypted PIN
Block
16H
The 64 bit encrypted PIN block represented as
16 hexadecimal digits.
Length is 0, if no PIN entered.
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check character
MAX: 57 characters
MIN: 67 characters
MX800 SERIES PROGRAMMERS GUIDE
333
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
DUKPT Packet 75 VISA:
Example:
PC ---> PINPAD : <STX>7801234567890<FS>C19.99<ETX>{LRC}
PC <--- PINPAD : <ACK>
PC <--- PINPAD :
<STX>75FCD3CA45D04396624CF6892B04A000002468000048D5D7AF0333800FD<ETX>{LRC}
PC ---> PINPAD : <ACK>
ANSI:
PC ---> PINPAD : <STX>7801234567890<US>C19.99<ETX>{LRC}
PC <--- PINPAD : <ACK>
PC <--- PINPAD :
<STX>7500000000D04396624CF6892B04A000002468000048D5D7AF0333800FD<ETX>{LRC}
PC ---> PINPAD : <ACK>
Packet 75 is the response packet to packet Z69 or packet 78, PIN request, when
no errors are detected in the request packet. If errors are detected in packet Z69
or packet 78, the response packet is in the following format:
Table 84
DUKPT Packet 75 Format: Errors Detected in Packet Z69 or
Packet 78
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 75
Error Code
1N
• 1 = no key
• 2 = account error
• 3 = PIN too long
• 4 = PIN too short/non-decimal digit in PIN
• 5 = C|D field error/not DUKPT mode
• 6 = PIN pad has over 1 million transactions
• 7 = amount error
• 8 = ANSI MAC not allowed when using 1DES
DUKPT
DUKPT Packet 75 •
Length:
•
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 6 characters
MIN: 6 characters
DUKPT Packet 75 <STX>751<ETX>{LRC}
Example:
334
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
Packet 25: Check the DUKPT Engine
Packet 78: DUKPT Packet 78 requests PIN encryption and MAC processing using a fixed PIN of
Accept and Encrypt '1234'. The response packet is packet 75.
PIN/Data
Authentication Test
Request
Packet 78 is similar to packet Z69, but the PIN code is preset to “1234.” The user
is not prompted to enter a PIN.
NOTE
This packet is used for testing and should not be used by applications.
Table 85
DUKPT Packet 78 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
2AN
Value: 78
[account#]
8–19N
Card account number
<FS> or <US>
1H
<FS> is the field separator that indicates VISA
MACing is used.
<US> is the field separator that indicates that
ANSI 9.19 MACing is used.
DUKPT Packet 78 •
Length:
•
NOTE
[C/D]
1H
Credit/Debit indicator, value: 43h/44h
[amount]
3-13N
Transaction amount, decimal point included.
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 33 characters
MIN: 18 characters
As per the VISA specification: The amount field should be 3–12 numeric
characters, excluding the decimal point. Due to compatibility concerns, this packet
is designed to be the same as the Z60 or 76 packet commands. However, the
amount length is extended to be able to accept 12 numeric characters. The lack of
a decimal point or multiple decimal points does not cause an error. The PIN pad
does not confirm the decimal point location. The MAC value is calculated across
the entire account number and all amount numbers, and the decimal point is
filtered out.
DUKPT Packet 78 VISA:
Example:
<STX>7801234567890<FS>C19.99<ETX>{LRC}
ANSI:
<STX>7801234567890<US>C19.99<ETX>{LRC}
MX800 SERIES PROGRAMMERS GUIDE
335
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MAC-Specific Packets
Table 86
DUKPT Packet 78 Communication Protocol
Transmit
Direction
Master Device
IPP
78 Packet
• ACK if LRC
• NAK if LRC incorrect
Packet 75 with PIN = 1234
• ACK if LRC
• NAK if LRC incorrect
• EOT after 3 NAKs
MAC-Specific
Packets
This section describes the master-session MAC generation of received message
packets for the IPP. Two packet formats are specified: Z66 and Z67. The detailed
module design and interface design are discussed. ANSI (Standard) MAC
algorithms are used. The following are the packets in this module:
•
Z66: Request MAC
•
Z67: Return MAC
•
72: Cancel MAC Session
MAC Packet Z66: Used by the master device to direct the IPP to generate the MAC of the current
Request MAC packet. If it is the first Z66 packet, the IPP begins MAC generation. If it is the last
Z66 packet, the IPP completes the MAC calculation for current packet, and
returns the MAC to the master device through the Z67 packet. Otherwise, the IPP
calculates the MAC from current packet and stores it in memory.
Table 87
MAC Packet Z66 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
3AN
value: Z66
[flag]
1N
ANSI (Standard) MAC: ASCII Data: Range: 4–5
• 4 = the last packet
• 5 = the first/middle packet
Binary Data; Range: 6–7
• 6 = the last packet
• 7 = the first/middle packet
336
[sequence]
2N
Range: 00–99
Master Key
Pointer
1N
Optional; Range: 0–9
<FS>
1H
Field separator, value: 1Ch
Working Key
16H
Encrypted working key for DES
<FS>
1H
Field separator, value: 1Ch
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MAC-Specific Packets
Table 87
MAC Packet Z66 Format (Continued)
Data Element
Characteristic
Comments
Second Key
1N
Optional; Second master key pointer;
Range: 0–9
<FS>
1H
Field separator, value: 1Ch
Message for
MACa
8*XAN0
ASCII message or ASCII-coded binary data:
X= 0–28 for ASCII data
X= 0,2,4,6,...,27,28 for binary data
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
a. ASCII messages for MAC should not include ETX(0x03) or SO(0x0E).
MAC Packet Z66 •
Length:
•
MAX: 255 characters
MIN: 12 characters
MAC Packet Z66 <STX>Z663002<FS>0123456789123456<FS><FS>0123456789ABCDEF<ETX>{LRC}
Example:
Notes 1
Maximum of 100 Z66 packets can be sent during one MAC session.
2 8*XAN in “Message for MAC” represents the number of 8-byte (or character)
blocks. For example,
•
X = 0: no message data
•
X = 1: 8 bytes of message data
•
X = 2: 16 bytes of message data
•
X = 3: 24 bytes of message data
:
:
•
X = 27: 216 bytes of message data
•
X = 28: 224 bytes of message data
For ASCII data, all values of X from 0–28 are allowed.
For Binary data, only 0, 2, 4, 6,...., 26, 28 are permitted. (X = 2 * N, where N =
0 to 14.)
3 If the length of “Message for MAC” is not a multiple of 8 in the final Z66 packet,
the PIN pad automatically pads it with zeros (ASCII 30h) internally.
4 An example of a 8-byte data block for the ASCII message “AMT$1.99” is
“414D5424312E3939”
5 ASCII-coded binary message is two hex digits that represent a byte value, see
the conversion result above.
MX800 SERIES PROGRAMMERS GUIDE
337
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MAC-Specific Packets
6 If the working key is loaded in 1DES key-only format, either ANSI (standard)
or MAC is used (depending on the status of the flag in the packet Z66).
7 If the working key is loaded in the GISKE format, the IPP uses the MAC
algorithm specified in the Key Usage Attributes of the GISKE key block.
8 When the key length and the MAC algorithm do not match, an error code (key
attribute/usage error) returns. For example, a single-length key is used with a
3DES MAC algorithm.
9 MAC algorithms used: ISO 9797-1 MAC Algorithm 1–56 bits, MAC Algorithm
1–112 bits, MAC Algorithm 2–112 bits, MAC Algorithm 3–112 bits, MAC
Algorithm 4–112 bits, MAC Algorithm 5–56 bits, MAC Algorithm 5–112 bits.
10 The GISKE working key can only be a single- or double-length key. Master
key used to encrypt the working key can be a single-, double-, or triple-length
key (the GISKE length encryption rule still applies). If a triple-length GISKE
working key is used in Z66, a working key error is returned.
Rules of Request MAC
The following rules are imposed to the size of the “Message for MAC” field:
Table 88
Rules for Request MAC
Maximum Size
of Message
(bytes)
Packet
Type
Size of X
Keyonly
ASCII: X = 0, 1, 2 – 27,
28
224
Binary: X = 0, 2, 4 – 26,
28
224
ASCII: X = 0, 1, 2 – 14,
15
120
Binary: X =0, 2, 4 – 12,
14
112
Apply to
Message
Sequence
Comments
00–99
format
GISKE
Key
Block
Format
mode
00 – 99
Due to size
of GISKE
key block,
the size of
message is
reduce to
120 bytes.
MAC Packet Z67: This multi-purpose packet:
Return MAC
• Sends a signal to the master device that the IPP is ready for the next Z66
packet.
•
338
Sends an error code to the master device if there any error is detected during
the MAC session.
MX800 SERIES PROGRAMMERS GUIDE
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MAC-Specific Packets
•
Sends the MAC value to the master device.
Table 89
MAC Packet Z67 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, value: 02h
Packet Type
3AN
Value: Z67
Process Code
1N
Range: 0–9:
• 0 = no error and MAC follows
• 1 = ready for next Z66 packet and no MAC
follows
• 2 = out-of-order error and no MAC follows
• 3 = [pointer] error and no MAC follows
• 4 = [second key] error and no MAC follows
• 5 = packet frame error and no MAC follows
• 6 = [flag] error
• 7 = [message] error
• 8 = [working key] error/GISKE key usage,
algorithm, mode of use, or key length error
• 9 = incorrect key attributes of the master key
(first or second)
MAC Packet Z67 •
Length:
•
MAC field
16H
Optional; only sent when no errors are detected
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 23 characters
MIN: 7 characters
MAC Packet Z67 <STX>Z671<ETX>{LRC}
Example:
Packet 72: Cancel Cancels the MAC session if an error is detected in a multi-MAC session. After the
MAC Session IPP receives packet 72, ACK is returned to terminate the session.
Table 90
Packet 72 Length: •
•
MAC Packet Z66 Format
Data Element
Characteristic
Comments
<STX>
1H
Start of text, Value: 02h
Packet Type
3AN
Value: 72
<ETX>
1H
End of text, value: 03h
{LRC}
1H
Error check
MAX: 5 characters
MIN: 5 characters
Packet Z72 Example: <STX>712 <ETX>{LRC}
MX800 SERIES PROGRAMMERS GUIDE
339
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS
MAC-Specific Packets
Table 91
Packet 72 Communication Protocol
Master Device
Transmit
Direction
IPP
<STX>72<ETX>{LRC}
• ACK if LRC
• NAK if LRC incorrect
MAC Module Design ANSI (Standard) MAC Algorithms
The algorithm to calculate the MAC is fully compatible with the ANSI X9.19 1986,
Financial Institution Retail Message Authentication specification. Within this
standard, there are two modes of operation: CBC (Cipher Block Chaining) and
CFB-64 (64-bit Cipher Feedback). In IPP5 implementation (that is, IPP5 and
higher, including IPP6, IPP7, and Omni 33XX IPP), CBC is used for MAC
calculation.
The master key and the working key for MAC calculation can be downloaded with
Z66 packet. Selection of these keys depends on the first Z66 packet
configurations within each MAC session, as summarized in Table 92.
Table 92
MAC for Master and Working Keys
[pointer]
[working key]
Selection
present
present
Master key selected by [pointer]; working key decrypted
by master key.
absent
present
Working key decrypted by current active master key.
After the MAC calculation, there is an optional procedure used to increase
protection against exhaustive key determination. This procedure can be turned
on/off by the [second key] field of the first Z66 packet. If this second key was
provided with the first Z66 packet, this procedure generates the final MAC and
uses [second key] as the master key pointer. If no [second key] is provided,
no procedure is performed on the current MAC.
One thing to note is that [second key] is used on a session-by-session basis.
Each [second key] field of the first Z66 packet defines its own optional
procedure on/off status during that MAC session. For more detailed information
about MAC optional procedure, please refer section 2.4.4.5 of the ANSI X9.19
specification.
After the process completes, a 64-bit MAC is generated. This MAC value returns
to the master device with packet Z67. If there any errors are detected during the
MAC process, packet Z67 returns with [code] set to an error code.
340
MX800 SERIES PROGRAMMERS GUIDE
INDEX
Numerics
1DES master key 284
A
audio
beeper units 135
disabling speakers 134
vlume, bass and treble control 133
C
C compiler and development tools
C compiler & tools 13
COM1 98
COM2 99
COM3 service functions 174
svcCom3FlushRxBuf() 185
svcCom3Polled() 188
svcCom3ReqExtStatus() 176
svcCom3ReqFirmVers() 180
svcCom3ReqTallyInfo() 178
svcCom3ResTallyData() 179
svcCom3SetBufFlushInt() 187
svcCom3SetDeviceAddr() 181
svcCom3SetECLevel() 182
svcCom3SetHandshake 183
svcCom3SetMode() 175
svcCom3SetRxRecThresh() 186
COM4 100
COM5 100
config.usrx 18
configuration variables 15
D
Delta smartcard interface/cardslot 92
device drivers
Delta 33
Display 33
ethernet port 33
IPP 33
magnetic stripe reader 33
real time clock 33
serial port 33
Sound 33
touch panel 33
USB 33
directory structure 198
file organization 198
user space and security 199
user space base structure 199
display 130
dspSetBrightness() 131
downloading 26
IBM ECR 27
NFS 26
TCP/IP 27
USB Memory Device 27
Zontalk 26
downloading files from the ECR 119
DUKPT
IPP7 324
E
ECR Environment Variables 116
Environment Variables
P4683 117
environment variables 15
A4683 117
G4683 118
I4683 116
L4683 117
O4683 116
S4683 118
V4683 118
environment/configuration variables
getEnvFile 19
putEnvFile 20
F
file authentification 28
file compression 15
MX800 SERIES REFERENCE MANUAL
341
I NDEX
file format details 15
file systems 15
firmware 13
IPP7 46, 284
DUKPT modes 324
G
JFFS2 15
getenv() 15
GISKE
key attribute 284
KLK key loads 285
GNU C compiler 13
GNU ZIP 15
I
IBM ECR tailgate & feature C 100
ecrRead 102
ecrReadReject 103
ecrStatus 104
IBM ECR tailgate & feature CecrClose 110
IBM ECR tailgate & feature CecrDownload 111
IBM ECR tailgate & feature CecrWrite 109
internal PIN pad
int ippClose(void) 48
int ippOpen(void) 47
int ippRead(char *buffer, int size) 49
int ippWrite(char *buffer, int size) 50
SetSecurePINDisplayParameters() 51
IPP
key attributes 284
key length 284
key version 284
IPP differences 56
IPP ROM version number 56
multiple DUKPT 56
PROM checksum 56
select baud rate 56
set IPP6 key management mode 56
set IPP7 key management mode 56
set master key 56
IPP refenreces 57
GISKE specification 57
PP7 specification 57
ipp_abort() 224
ipp_getpin() 217
ipp_mac() 222
ipp_read() 219
342
MX800 SERIES REFERENCE MANUAL
J
K
key 285
key attributes, IPP 284
KLK (GISKE) 285
L
LEDs 136
ledOff 138
ledOn 137
M
MAC value 286
magnetic stripe reader 34
msrClose 45
msrDisableLicenseDecode 43
msrEnableLicenseDecode 42
msrMagneticCardPresent 39
msrOpen 35
msrRaw 40
msrRead 36
msrStructured 41
msrVersion() 44
msrWrite 38
Mx800 series COM ports 98
COM3 99
O
operating system 13
P
packet mode 94
endPktMode() 96
Receiving Packet Messages 97
putenv() 15
R
real-time clock 139
void setRTC(void) 140
reference documents
LINUX books 12
I NDEX
root file system 197, 215
BusyBox 197
uClibc 197
S
security services APIs 80
AES() 86
authFile() 90
cryptoRead() 82
cryptoWrite() 81
DES() 85
generateRandom() 87
IRSA Computation 83
isAttacked() 88
loadOSFiles() 91
secVersion() 89
SHA1() 84
serial communication control structure 93
packet_parms 94
protocol 93
trailer 94
service functions 143
svcAlarm() 167
svcCrcCalc() 144
svcExpand 172
svcGetInQ() 170
svcGetOutQ() 171
svcGetPortStatus() 168
svcInfoCard() 156
svcInfoDsp() 155
svcInfoKey() 157
svcInfoPlatform() 152
svcInfoType() 154
svcReleaseAlarmCallback() 166
svcReleaseRxCallback() 164
svcRestart() 147
svcSetAlarmCallback() 165
svcSetOpenBlock 162
svcSetRxCallback() 163
SvcZontalkRcv() 159
SIGALRM 114, 115
SIGINT 114
SIGIO 114, 115
Signals 114
signature capture 120
Signature Capture API 123
svcDsp2Hex() 146
svcInfoRFS() 149
System Mode 195
T
touch panel 120
V
Verishield Security Scripts (VSS) 57
VSS APIs 57
iPS_CancelPIN() 73
iPS_CheckMasterKey() 64
iPS_DeleteKeys() 59
iPS_ExecuteScript() 77
iPS_GetPINResponse() 70
iPS_GetScriptStatus() 75
iPS_InstallScript() 74
iPS_LoadMasterClearKey() 62
iPS_LoadSysClearKey() 60
iPS_RequestPINEntry() 69
iPS_SelectPINAlgo() 68
iPS_SetPINParameter() 66
iPS_UninstallScript() 76
pcPS_GetVSSVersion() 79
SetSecurePINDisplayParameters() 65
MX800 SERIES REFERENCE MANUAL
343
VeriFone, Inc.
2099 Gateway Place, Suite 600
San Jose, CA, 95110 USA
Tel: (800) VeriFone (837-4366)
www.verifone.com
Mx800 Series
Programmers Guide
Part Number 23753, Revision A