Programmers Guide - Verifone Support Portal

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
CONTENTS
CHAPTER 1
Introduction Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Modifications to this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Acronyms, Abbreviations, and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Conventions Used in this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Recommended LINUX Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
File Format Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
getEnvFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
putEnvFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
System Configuration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
getSysctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
putSysctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Syslog Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Remote Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Downloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Downloaded Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
File Authentication and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Building ipkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Installing ipkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
CHAPTER 4
Device Drivers Device Drivers for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . 33
Magnetic Stripe Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
msrOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
msrRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
msrWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
msrMagneticCardPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
msrRaw. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
msrStructured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
msrEnableLicenseDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
msrDisableLicenseDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
msrVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
msrClose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Internal PIN Pad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
int ippOpen(void). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
int ippClose(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
int ippRead(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Note on the PIN session timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
MX800 SERIES REFERENCE MANUAL 3
C ONTENTS
int ippWrite(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

SetSecurePINDisplayParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
int ippPinEntryStatus(int *count, int *lastNonNumericKey) . . . . . . . . . . . . . . 54
ippTerminatePinEntry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
IPP Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
IPP Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
GISKE Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Security Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
VeriShield Security Scripts APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
iPS_DeleteKeys() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
iPS_LoadSysClearKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
iPS_LoadSysEncKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
iPS_LoadMasterClearKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
iPS_LoadMasterEncKey(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
iPS_CheckMasterKey(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
SetSecurePINDisplayParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
iPS_SetPINParameter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
iPS_SelectPINAlgo(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
iPS_RequestPINEntry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
iPS_GetPINResponse() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
iPS_CancelPIN(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
iPS_InstallScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
iPS_GetScriptStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
iPS_UninstallScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
iPS_ExecuteScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
pcPS_GetVSSVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Security Services APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
cryptoWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
cryptoRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
rsa_calc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
SHA1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
DES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
AES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
generateRandom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
isAttacked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
secVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
authFile(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
loadOSFiles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Delta Smartcard Interface / CardSlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Serial Ports and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Serial Communication Control Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Packet_parms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Packet Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Initialize Packet Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
endPktMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Receiving Packet Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
COM Ports on the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . 98
COM1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
COM2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4 MX800 SERIES REFERENCE MANUAL

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() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
svcDsp2Hex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
svcRestart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
svcInfoKernel() / svcInfoEprom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
svcInfoRFS() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

C ONTENTS
svcInfoSerialNum() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
svcInfoPtid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
svcInfoPlatform(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
svcInfoType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
svcInfoDsp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
svcInfoCard() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
svcInfoKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
svcInfoSerialNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
svcZontalkRcv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
zontalkCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
svcSetOpenBlock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
svcSetRxCallback(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
svcReleaseRxCallback(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
svcSetAlarmCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
svcReleaseAlarmCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
svcAlarm(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
svcGetPortStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
svcGetInQ(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
svcGetOutQ() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
svcExpand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
svcUsbStorPresent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
COM3 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
svcCom3SetMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
svcCom3ReqExtStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
svcCom3ReqTallyInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
svcCom3ResTallyData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
svcCom3ReqFirmVers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
svcCom3SetDeviceAddr(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
svcCom3SetECLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
svcCom3SetHandshake() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
svcCom3FlushRxBuf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
svcCom3SetRxRecThresh() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
svcCom3SetBufFlushInt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
svcCom3Polled(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
svcGetSysMillisec(), svcGetSysMicrosec(). . . . . . . . . . . . . . . . . . . . . . . . . 189
enableProcessMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
disableProcessMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
enableButtonSig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
disableButtonSig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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

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 . . . . . . . . . . . . . . . . . . . . . . 205
netUP() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
netDown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
netGetConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
netLinkStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
getSysctl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Supported Network Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
netPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
ftpGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
ftpPut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
C H A P T E R 10
IPP Legacy Library IPP Support for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . . 215
ipp_getpin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
ipp_read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
ipp_mac() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
ipp_abort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
ipp_diag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
select_key_mgmnt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
get_key_mgmnt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
C H A P T E R 11
Contactless RF Library API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Card Reader Module RFCRlibVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
RFCRInit(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
RFCRGetVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
RFCRPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
RFCRReset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
RFCRSetAntenna(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
RFCRSetIndicator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
RFCRGetCardPayload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
RFCRParseCardPayload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
RFCRUpdateFW() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
RFCRPurge() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
RFCRInputPending() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
RFCRRawWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
RFCRRawRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
RFCRAddCRC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
RFCRCheckCRC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
RFCRReceiveACKFrame(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
RFCRReceiveDataFrame(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
RFCR Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
C H A P T E R 12
Input Events inputOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
inputRead(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
inputClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

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
Communications Minor Differences by Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Packets <SI>0103<SO> PROM Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
<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

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
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
DUKPT Packet 75: DUKPT Accept and Encrypt PIN/Data Authentication
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

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

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 may be changed or extended to include new product

this document requirements.
Acronyms, Table 1 Acronyms, Abbreviations, and Definitions

Abbreviations, Abbreviation Definition
and Definitions 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 Acronyms, Abbreviations, and Definitions

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 Major Hardware Devices
ARM9 ARM SoC

Graphic Display Color (16 bpp) QVGA (320x234)
Conventions The following table describes the conventions used:

Used in this Table 3 Document Conventions
Document 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
The caution symbol indicates possible hardware or software

CAUTION 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 The Mx800 series terminal is the first VeriFone product to run ARM embedded
System and Linux. The initial kernel will be version 2.6.10.
Firmware 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.

O VERVIEW OF P RODUCT D ELIVERABLES
Operating System and Firmware

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 The Mx800 series of terminals will support GNU ZIP (.gz or .tgz or tar.gz)
Compression 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/ Linux has long had the concept of environment variables (also called
Configuration configuration variables). Unfortunately, environment variables are not permanent
Variables 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.

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, null-
terminated 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
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
trailing positions.
Line Feed 0x0A 10 This is a reserved character and cannot
Vertical Tab 0x0B 11 Cannot be used in leading and trailing
trailing positions.

F ILE S YSTEMS
Table 4
Character Hex Decimal Usage
Form Feed 0x0C 12 This is a reserved character and cannot
Carriage Return 0x0D 13 This is a reserved character and cannot
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.
NOTE
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.

F ILE S YSTEMS
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.

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

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 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 case-

sensitive.
*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 Use either *DHCP or
set MAC address as the *IFCONFIG.
system will do this for
you. See Chapter 9.
*GATEWAY IP Address in the form Used to define the address
xxx.xxx.xxx.xxx 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
Example: points to be defined.
“-t nfs –o nolock

10.64.88.249:/nfs /mnt/
smfnfs”

F ILE S YSTEMS
putEnvFile
Table 5
*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 Either IP address or DNS
server DNS name name of FTP server.
Max length = 96
characters
*FTPPORT Default = 21 Port number for FTP
connection.
*FTPFILE Default=app.tgz Remote file name (and path)
Max length = 96 of file to be retrieved from
characters the FTP server.
*FTPPWD Default = Terminal S/N FTP password

Max length = 32
characters
*FTPUSER Default = anonymous FTP User ID
Max length = 32
characters
*SYSLOG_MARK Default = 30 Specifies when a “MARK”
Min = 10 timestamp marker is placed
in the syslog messages file.
Max = 1440
Off = 0
*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).

F ILE S YSTEMS
putEnvFile
Table 5
*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.

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

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

F ILE S YSTEMS
Syslog Messages
Syslog The Mx800 series of terminals supports logging messages generated by

Messages 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.

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.

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 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.
File The Mx800 series implements VeriFone’s VeriShield File Authentication module.
Authentication All executable code must be authenticated prior to running. File authentication
and Certificates 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 The terminal supports the ability to group or package a collection of files as a
Management 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.

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.

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 is the name of the package and should match the regular expression [a-
z0-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[0-
9]\+". 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).

F ILE S YSTEMS
Package Management

CHAPTER 4
Device Drivers
Device Drivers The following device drivers are supported by Mx800 series of terminals:
for the Mx800
Ethernet Port Standard Linux support as /dev/eth0
series of
Terminals 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
• COM3 = /dev/ttyWR0
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.

D EVICE D RIVERS
Magnetic Stripe Reader
Magnetic Stripe All Mx800 series of terminals include a triple track magnetic stripe reader.
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);
}
}

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
flags Specify device access permissions for the MSR device. The
pertinent ones are:
O_RDONLY Read Only
O_RDWR Read and Write
O_NONBLOCK Read is non-blocking (default is

blocking)
callback Pointer to callback function. If available, this callback function will

be called when data is available.
Return Values
0 Magnetic Stripe Reader is open and ready
<0 Error

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)
The data includes the Start Sentinel, End Sentinel, and the LRC
characters. They were not included in the Omni 7xxx.

D EVICE D RIVERS
msrRead
The status byte (s1,s2,s3) can have one of the following values:
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
NOTE 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

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.

D EVICE D RIVERS
msrMagneticCardPresent
msrMagneticCardPresent
Prototype
int result = msrMagneticCardPresent(void)
Return Values
0 No data available
1 Data available
2 Magnetic field present

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_DATA;
Return Values
0 Data available
-1 No data available

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_DATA;
Return Values
0 Data available
-1 No data available

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);

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);

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
0 Successful execution
<0 Error

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 Error

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.

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

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

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).

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
=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.
NOTE 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.

D EVICE D RIVERS
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.

D EVICE D RIVERS
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 touch_spot[MAX_NUM_HOTSPOTS];
};

D EVICE D RIVERS
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*/

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 non-
numeric 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

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

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.
<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.

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 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.
VeriShield The Mx800 series of terminals support the VeriShield Security Scripts concept as
Security Scripts implemented in the SC 5000 PINpad and Verix V family of terminals. Existing
APIs 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.
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.

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_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
E_KM_SYSTEM_ERROR

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 VSS_KLK (16 bytes)
pucINKeyValue 16-byte buffer containing the clear-text key
Return Values
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

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
0x00 VSS_KLK (16 bytes)
pucINKeyValue 16-byte buffer containing the clear-text key
Return Values

possible
E_KM_SYSTEM_ERROR

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
...

Master key number / Key index in the selected set
pucINKeyValue pointer to the 8-byte buffer containing the cleartext value Master
Key.
Return Values
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

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
...

pucINKeyValue pointer to the 8-byte buffer containing the cleartext value Master
Key.
Return Values

possible
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

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
...
08 PIN Master Key (Master/Session)
09 MAC Master Key (Master/Session)

pucINKVC not used
Return Values
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

D EVICE D RIVERS
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);

D EVICE D RIVERS
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:
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

D EVICE D RIVERS
Return Values
E_KM_OUT_OF_RANGE At least one of the parameters is out of range
E_KM_SYSTEM_ERROR

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
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

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
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

D EVICE D RIVERS
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
OK Done. Data contains the result of the comparison/
(0x00) 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
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) Done.
pOUTData Number of PIN digits

->nbPinDigits entered (PIN length).
pOUTData contains no relevant

->encPinBlock information.
0x01 Unit is idle
pOUTData contains no relevant

->encPinBlock information.
0x02: Collecting PIN
pOUTData Number of PIN digits entered

->nbPinDigits so far.
pOUTData The first byte of the buffer

->encPinBlock 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.

D EVICE D RIVERS
0x05: or Aborted by user

0x0A:
pOUTData 0
->nbPinDigits
pOUTData The first byte of the buffer

->encPinBlock contains the value of the last
non-numeric key pressed.
Values can be:
• 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
E_KM_SYSTEM_ERROR

D EVICE D RIVERS
iPS_CancelPIN()
iPS_CancelPIN()
This function cancels the PIN processing.
Prototype
int iPS_CancelPIN(void)
Return Values
E_KM_SYSTEM_ERROR

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 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
E_VS_SCRIPT_NOT_LOADED This script is not installed or not accessible from the

current application group.

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.
Return Values
E_VS_SCRIPT_NOT_LOADED This script is not installed, not authenticated, or not

accessible from the current application group.
E_VS_SYSTEM_ERROR

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.
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.

D EVICE D RIVERS
iPS_ExecuteScript()
Return Values
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

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 Script number. Range [0..7]
r
Return Values
It returns a char pointer to the following NULL terminated string:
"PSVSSvX.Y"
X Major version
Y Minor version

D EVICE D RIVERS
Security Services APIs
Security The security device (/DEV/IPP) need not be opened to use the functions listed
Services APIs 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.

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
1 File Error, errno is set accordingly.
<1 System Error

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
1 File Error, errno is set accordingly.
<1 System Error

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 Error - Invalid parameter

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
<0 Error

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 Pointer to 8-byte output block

a
Return Values
Less than 0 Error

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
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
Less than 0 Error

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 Error

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
0 No attack has occurred since keys have been loaded.
1 An attack has occurred. Keys and encrypted file have been lost.

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
Less than 0 Error

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
the specified file is performed.
Prototype
int authFile(const char *filename)
Parameters
filename Pointer to the name of file to authenticate.
Return Values
0 File is authenticated
<0 File failed authentication

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
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 Error

D EVICE D RIVERS
Delta Smartcard Interface / CardSlot
Delta Smartcard The VeriFone Delta Smartcard module will be used to interface the ARM CPU to
Interface / the customer smartcard and SAMs. For more details on Smartcard APIs, refer to
CardSlot the Mx CardSlot Library Programmer’s Guide, VDN 23992.
Serial Ports and The Linux operating system is divided into two spaces, the kernel space and the
Protocols 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 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.
USER SPACE
Feature C Protocol
Packet Mode Protocol (VISA layer)
LINUX KERNEL
Character Device
UART Driver Wrenchman Coprocessor

stty1, stty2 Driver (SPI) stty3
Wrenchman
HARDWARE
Samsung ARM9 CPU Silicon Labs

Communication
Coprocessor
COM1 COM2 COM3

RTS/CTS, RTS/CTS, RTS/CTS
DCD DTR, DCD
Figure 1 LINUX operating system structure

D EVICE D RIVERS
Serial Communication Control Structure
Serial The following are the structures defined for configuring serial ports on the Mx800
Communication series of terminals. They contain all the necessary elements for defining the ports
Control into the different modes that each of them support.
Structure 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.

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

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 Error

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);

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

D EVICE D RIVERS
COM Ports on the M x 800 series of Terminals
COM Ports on There are 4 COM ports on the Mx800 series of terminals labeled COM1 – COM4
the Mx800 series plus an additional USB device serial port, COM5. They are referenced in software
of Terminals as the following devices:
• COM3 = /dev/ttyWR0
• 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.

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.

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 The succeeding section lists the IBM ECR APIs used both in Tailgate and Feature
Tailgate & C mode.
Feature C

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

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.

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.

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:

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.
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
defined as:
int frame_err;
int over_err;
int parity_err;
};
If in Feature C mode and VISA is enabled:
Prototype
struct vficomErrCounts *result=ecrStatus(int*buf);

D EVICE D RIVERS
ecrStatus
Copy current status information to caller’s 4-integer buffer.
1st Input messages pending

A value of 0 means no pending message.
A value of greater than 0 means that a message is pending.
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
4th Status of ecrWrite() message:

0 message ACKed
1 message pending
2 message rejected
Return Values
defined as:
int frame_err;
int over_err;
int parity_err;
};
framing, overrun and parity errors detected for that port. They counts provided are

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.)
0x20 set if CTS detected
0x10 set if Ring Indicator is present
0x08 set if Carrier Detect (CD) present
0x02 Reserved
0x01 Reserved

D EVICE D RIVERS
ecrStatus
Return Values
defined as:
int frame_err;
int over_err;
int parity_err;
};

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 Specific error that occurred

error code

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 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().

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()

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

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 specific error that occurred

errno value

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)

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.

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.

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 There are required environment variables set when the ECR connection is
Environment established. They reside in config.usrx (where x is number of user account 1-
Variables 8) 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:
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
NOTE
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:
XXXX YYYY
Application Version Parameter ID
Application Version is 4 bytes, which can contain any 4 byte alpha-

numeric string.
Parameter ID is 4 bytes, which can contain any 4 byte alpha-

numeric string.

D EVICE D RIVERS
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.

D EVICE D RIVERS
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.

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>

D EVICE D RIVERS
Touch Panel / Signature Capture/TIFF
Touch Panel / The touch panel is calibrated (also called compensated) at the factory. The factory
Signature calibration is used by the system until it is periodically updated. VeriFone strongly
Capture/TIFF 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.

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)

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
0 Success
1 Error

D EVICE D RIVERS
Signature Capture
Signature Signature Capture is implemented as a widget at the FancyPants GUI level. The
Capture 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.
NOTE
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.

D EVICE D RIVERS
SigCapCount()
SigCapCount()
Returns the number of signature points that are currently available.
Prototype
int SigCapCount(void)

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)

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);

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;

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
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.

D EVICE D RIVERS
int SigCap2Tiff()
Return Values
0 Success
<0 Error
NOTE
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");
}

D EVICE D RIVERS
Display
Display The user interface is managed by the FST FancyPants GUI.

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

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.

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
volume Accepted values: 0-100
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

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.

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.

D EVICE D RIVERS
LEDs
LEDs 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.

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

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

D EVICE D RIVERS
Real-Time Clock (RTC)
Real-Time Clock Linux has a rich API to support RTC functionality, so we will not be supplementing
(RTC) 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.

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)

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
• MM = Month
• DD = Day
• hh = Hour (24-hour format)
• mm = Minute
• YYYY = Year
• ss = Seconds
NOTE
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

D EVICE D RIVERS
setDateTime()

CHAPTER 5
Service Functions
Service This chapter lists the service function APIs used in the Mx800 series of terminals.
Functions for
the Mx800 series
of Terminals

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

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.

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, A-
F).
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.

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);

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.

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;

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 *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

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:
1 If the lithium battery is OK
0 If the lithium batter is bad
NOTE
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).

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
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
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
0 Smart Card Version 1 (Delta) 1 = YES
1 Smart Card Version 1 (Delta2) 1 = YES
2-15 Reserved

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);
Return Values

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);
Return Values
0 0
1 0
2 320
3 240
4 0
5 0
6 1
7 1

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.

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);
Return Values

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);

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
F Full download
P Partial download
endCallback 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.

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
The port should be configured for character mode and 8 bit, no parity, 1 stop. The
baud rate may be any rate supported.

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.

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.

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

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

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

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

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.

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.)
0x20 set if CTS detected
0x10 set if Ring Indicator present
0x08 set if Carrier Detect (CD) present
0x02 Reserved
0x01 Reserved
buf[3] 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:
int frame_err;
int over_err;
int parity_err;
};
the total errors counted for that port since it was opened which allows the

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

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

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.

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]
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.

S ERVICE F UNCTIONS
COM3 Service Functions
COM3 Service The COM3 service functions are for tuning and configuring the communication
Functions 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.

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.

S ERVICE F UNCTIONS
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 2-
byte 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
0 Polled access mode
1 On Demand access mode
b6 FWDS Watchdog Status

0 Disabled
1 Enabled
b5 FOPEN Channel status

0 Channel is closed
1 Channel is active
b4 FRST Reset path

0 Reset via Host control
1 Reset via Watchdog event
b3 FXDR External Device reset status

0 No device reset received
1 Device reest received
b2 * Reserved
b1 * Reserved
b0 * Reserved

S ERVICE F UNCTIONS
Where: DevStat2 = Handshake Status

Where:
Table 15
b7 RE Receive enable
0 Receive disabled
1 Receive enabled
b6 FHW Trransmit wait status

0 Transmit wait on handshake disabled
1 Transmit wait on handshake enabled
b5 FAO Auxiliary Out state

0 Aux Out is in idle state
1 Aux Out is in Asserted state
b4 FCO Control Out state

0 Control Out is in Idle state
1 Control Out is in Asserted state
b3 FRO Ready Out state

0 Ready Out is in Idle state
1 Ready Out is in Asserted state
b2 AI Auxiliary In status: (N/A)

0 Aux In is in Idle state
1 Aux In is in Asserted state
b1 CI Control In status: (CTS)

0 Control In is in Idle state
1 Control In is in Asserted state
b0 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)

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
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.

S ERVICE F UNCTIONS
svcCom3ResTallyData()
svcCom3ResTallyData()
The svcCom3ResTallyData() function resets all the tally counters to zero.
Prototype
short svcCom3ResTallyData(int fd)
Parameters
or ecrOpen().
Return Values

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
or ecrOpen().
*fwBuf Pointer to a buffer that is at least 16 bytes in size, that will hold the null-
terminated current communication processor firmware version string.
Return Values

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.

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

S ERVICE F UNCTIONS
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
b7 RE Receive enable
0 Receive disabled
1 Receive enabled
b6 HW Handshake wait
0 Transmit unconditionally
1 Transmit waits on Handshake
b5 AO Auxiliary Out (N/A)

0 Aux Out is in Idle state
1 Aux Out is in Asserted state
b4 CO Control Out
0 Control Out is in Idle state (RTS)
1 Control Out is in Asserted state (RTS)
b3 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

S ERVICE F UNCTIONS
Prototype
short svcCom3SetHandshake(int fd, char hs)
Parameters
or ecrOpen().
ec A 1 byte value that indicates the handshake control.

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
or ecrOpen().
Return Values

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
or ecrOpen().
rrt a 1 byte value that indicates the receive record threshold to be set.
Return Values

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
or ecrOpen().
rrt A 1 byte value that indicates the buffer flush interval to be set.
Return Values

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 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();

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)

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)

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
If the user presses the recessed button for longer than two seconds, the normal
system mode password display will be called.

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.

S ERVICE F UNCTIONS
disableButtonSig()

CHAPTER 6
System Mode
System Mode for The Mx800 series of terminals’ System Mode will be a departure from previous
the Mx800 series products in that a graphical user interface will be used for presentation. The
of Terminals 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.

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.

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 size-
optimization 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 yew-
see-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

R OOT F ILE S YSTEM
Directory Structure
Directory Linux / Unix has a long history with respect to the root file system directory
Structure 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 sbin usr var
initrd sys
usr1 usr2 bin sbin
Organization of
Files in the Standard
/bin stores essential binaries (programs) needed when booting the
Directory Structure
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.

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.

R OOT F ILE S YSTEM
Directory Structure

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.

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

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.

USB Human Interface Device (HID) Support
USB Human The Mx800 series terminal also has built in USB HID support for some devices
Interface Device through the Linux kernel Input Event module. When a HID is plugged into the USB
(HID) Support 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:
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.

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 variables are read for network configuration in bringing the interface
Configuration 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
*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 If not DHCP, DNS1 is used as the
xxx.xxx.xxx.xxx name server IP address.
*DNS2 IP Address in the form If not DHCP, DNS2 is used as the
xxx.xxx.xxx.xxx name server IP address.
*IFCONFIG Per Linux – No need to If not DHCP, use *IFCONFIG to set
set MAC address as the the following parameters:
system will do this for • host static IP address
you.
• netmask
Typically used: • broadcast (optional)
“eth0 xxx.xxx.xxx.xxx
netmask xxx.xxx.xxx.xxx”
*GATEWAY IP Address in the form Use to define the address of the
xxx.xxx.xxx.xxx gateway (router).
*TELNET 1 If *TELNET is present and the system
supports Ethernet, then it will start the
Telnet server daemon.

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
0 Success
<0 Error

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

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 { net_conf_t members Description
int dhcp;
char MAC[18]; short dhcp 1=DHCP, 0=Static
char ipaddr[16];
char netmask[16]; char MAC[18] format “xx:xx:xx:xx:xx:xx”
char gateway[16];
char dns1[16]; char ipaddr[16] format “xxx.xxx.xxx.xxx”
char dns2[16];
char netmask[16] format “xxx.xxx.xxx.xxx”
} net_conf_t;
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
0 Succes, interface is up.
<0 Error, probably network interface is down.

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

TCP/IP E THERNET
getSysctl()
getSysctl()
Returns the value of the specified kernel parameter.
Prototype
int result = getSysctl(char * varSysctl)
Return Values
1 Link is up.
0 Interface down or Ethernet cable is unplugged.
<0 Error

TCP/IP E THERNET
Supported Network Programs
Supported The Mx800 series of terminals API includes support for common networking
Network programs such as ping and FTP file transfers.
Programs 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

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
0 Success
<0 Error

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{ ftpHost In the “xxx.xxx.xxx.xxx” IP
char ftpHost[32];
address format or the fully
char port[8];
char userID[32]; qualified domain name format
char password[32]; ftp.site.com
char localFile[64];
char port FTP port. Defaults to 21 if not
remoteFile[64]; specified.
char errorMsg[64];
} ftp_parm_t; 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.

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
0 Success
<0 Error

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.

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.

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
1DES 16 characters - null terminated in case of Master Key
Mode Session, ignored in case of DUKPT.
3DES 120 characters - null terminated, GISKE data block

Mode in case of Master Key Session, ignored in case of
DUKPT.
master_key 1 character: (0...9) in case of Master Key Session, (0...2) in case of

DUKPT to select DUKPT engine.

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.

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
buffer User defined buffer in the application space where the information is to
be stored.
size The number of bytes to be read.
NOTE
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
>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
NOTE
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.

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 16H encrypted PIN

Block
ETX 1H End of text, value 03h
In case of an input error, the packet looks like:
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
For DUKPT Key Management:
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
Encrypted PIN 16H The 64 bit encrypted PIN block represented as 16

hexadecimal digits.

ipp_read()
In case of an input error, the packet looks like:
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

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
master_key ASCII "0...9" selects master key number
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
1 Successful
-1 Master Key Pointer Error
-2 Second Key Pointer Error
-3 Message length too large
-4 Wrong Block Size
-5 Communication Error

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.

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.

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
test_type Type of test that the user wants to perform:
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().

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.

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

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
0 Success

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

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
The returned values will be placed in the users variables kmm and demf.

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 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.
Library API The succeeding sections discusses the library API functions used in the Mx800
Functions series of terminals to support the RF Card Reader.

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
>=0 Success
<0 Error

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

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 NAK error

RFCRPing()
RFCRPing()
Tests if the RFCR module is alive and responding
Prototype
int RFCRPing(void);
Return Values
0 Success
<0 Error

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

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
>0 NAK status

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
...
buzz Not used at this time
Return Values
0 Success
<0 Error
>0 NAK status

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

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.

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 Pointer to callback function to process the progress messages. If

ss 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.

RFCRPurge()
RFCRPurge()
Purges any pending input from the reader.
Parameters
void RFCRPurge(void);

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

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
>0 Number of bytes written
<0 Error

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

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
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.

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

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
>0 Success, with the number of bytes read
<0 Error

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

RFCR Return Values
RFCR Return Along with the generic error returns in errno.h, the RFCR specific error returns
Values are as follows (most are from the RFCRUpdateFW() routine):
Table 21 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

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.

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.

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.

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.

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 • vpInit()

Library • vpParseFields()
Functions
• vpSendPacket()
• vpExit()
• vpVersion()
• netUp()
• netPing()

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
iOptions Bit defined options:
0x0002 Disable Auto ACKs
0x0001 Force Download
chSeparator Field separator character
Return Values
0 Error

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.

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.

V ISUAL P AYMENTS
vpExit()
vpExit()
Closes the VP connections, frees the memory, and then exits the application.
Prototype
int vpExit(int iFd);

V ISUAL P AYMENTS
vpVersion()
vpVersion()
Returns the VP library version string in the form “xx.xx.xx”.
Prototype
void vpVersion(char *pchVersion);

V ISUAL P AYMENTS
Visual Payments Callback Functions
Visual Payments • fnDownReq()

Callback • fnDownFileStatus()
Functions
• fnUpData()
• fnUpDisconnect()
• fnTimedOut()

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
>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

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

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
ushDataSize Contains the size of data in pchData.
ushMsgNum Contains the Message Number.

V ISUAL P AYMENTS
fnUpDisconnect()
fnUpDisconnect()
Called when the Up Channel is disconnected. Application should call vpExit()

to clean up.
Prototype
void fnUpDisconnect(void);

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);

V ISUAL P AYMENTS
Network/Ethernet Library Functions Required by Visual Payments
Network/ • ftpPut()
Ethernet Library • ftpGet()
Functions
• netLinkStatus()
Required by
Visual Payments • netDown()
• netUp()
• netPing()

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;

V ISUAL P AYMENTS
ftpGet()
ftpGet()
Sends a file to the VP Server.
Prototype
int ftpGet(FTP_parm_t *pstFTP);

V ISUAL P AYMENTS
netLinkStatus()
netLinkStatus()
Returns the link status of the eth0 network interface.
Prototype
int netLinkStatus();

V ISUAL P AYMENTS
netDown()
netDown()
Deactivates the network interface.
Prototype
int netDown();

V ISUAL P AYMENTS
netUp()
netUp()
Activates the network interface.
Prototype
int netUp();

V ISUAL P AYMENTS
netPing()
netPing()
Pings the remote host.
Prototype
int netPing(char *host);

V ISUAL P AYMENTS
XFTP Commands
XFTP The succeeding sections lists all XFTP commands.

Commands
XFTPGET • Required fields are: FTPHOST, FTPPORT, FTPUSER, FTPPWD, FILENAME,

FILETYPE.
• 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 • 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.

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 The differences between the Verix and Verix V IPP MS and DUKPT from the
Programming in Mx800 series IPP (XMIPP8) are summarized in Table 22.
IPP 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.

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:
• 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.
NOTE
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 Common Packets
Packet Description
01 Interactive diagnostic routine
05 Transfer serial number
06 Request PIN pad serial number

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)

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.

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.

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).

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

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
• 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 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. Spain and SM modes not supported in Verix V. Keys are erased as specified.
b. Least secure mode.
c. For transition period.
d. Most secure mode.
e. The key management register is set using Packet 17: Set IPP7 Key Management Mode.
f. 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.
g. 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.
h. 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.

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 =
• ‘P0’ - ‘PIN ENCRYPTION’
• Key Algorithm = 'T' -TDES for double or triple-length keys
• ‘D’ - DES for single-length key
• ‘AN’ – ANY
NOTE
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.

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 Value Definition
Register
[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
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:
• when the version is greater than or equal to the current key, OK is returned
and the IPP updates the new key

IPP7
• when the version is less than the current key version, an error returns and the
IPP rejects the new key
NOTE
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.

IPP7
previous KLK, has the correct key version and the key attribute is not equal to
“KEK”, the IPP returns an error.
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:
• 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
and cipher text 3DES master key is being loaded with an incorrect key
version, the IPP returns an error
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

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 triple-
Addressing 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
HB indicates the header block
KB indicates the key block
eHB indicates the encrypted header block
eKB indicates the encrypted key block.
GISKE key block: 8 HB + 24 HB + 24 KB + 8 MAC
Cipher text GISKE key 8 HB + 48 eHB + 48 eKB + 16 MAC

block for transmit
(encrypted with KLK
or KEK):
Clear text GISKE key 8 HB + 24 HB + 48 KB + 16 MAC

block (MAC is all
zeros): 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 0 A ...
0x44 0x30 0x41 (ASCII)
expanded HB = 0x34 0x34 0x33 0x30 0x34 0x31 (hex)

IPP7
Padded clear text 8 HB + 48 HB + 48 KB + 16 MAC

GISKE key block
(MAC is all zeros):

Common Packets
Common This section presents the packets common to all protocols.

Packets
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
<SI> 1H Shift in, value: 0Fh
[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

Packet 05 Example: Set the IPP serial number to 246880401A001234:

<SI>05246880401A001234<SO>{LRC}

Common Packets
Table 31 Packet 05 Communication Protocol

Transmit
Master Device IPP
Direction
<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
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.
<SI> 1H Shift In, value: 0Fh

Request Sample <SI>06<SO>{LRC}

Packet
[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

Common Packets

Response Sample <SI>06246880401A001234SO>{LRC}

Packet
Transmit
Master Device IPP
Direction
<SI>06<SO>{LRC}
• ACK if LRC
<SI>06[vvv][dddddd][p][bb][nnnn]<SO>{LRC}
• ACK if LRC
• NAK if LRC incorrect,
the IPP saves serial
number
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.

Common Packets
Table 35 Packets 09 and 14 Communication Protocol

Transmit
Master Device IPP
Direction
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

Common Packets
Table 35 Packets 09 and 14 Communication Protocol (Continued)

Transmit
Master Device IPP
Direction
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
03 PROM Checksum Test

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

Common Packets

Transmit
Master Device IPP
Direction
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
07 UART Loopback Test

ACK/NAK/EOT
<SI>09<SO>{LRC}
ACK/NAK/EOT
<SI>09<SUB>PROCESS-
ING<SO>{LRC}
ACK/NAK/EOT
<SI>09<SUB>PROCESSING<SO>{LRC}
ACK/NAK/EOT

Common Packets

Transmit
Master Device IPP
Direction
08 IPP PROM Version Number
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
09 Reset IPP
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.)

Common Packets

Transmit
Master Device IPP
Direction
10 Clear IPP
ACK/NAK/EOT
<SI>14CLR COMPLETE<SO>{LRC}
ACK/NAK/EOT
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.

Sample Packet <SI>11<SO>{LRC}

Transmit
Master Device IPP
Direction
<SI>11<SO>{LRC}
• ACK if LRC
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.

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.
Packet Data 1N Baud rate codes: 1 - 5
• 1 = 1200 bps (default)
• 2 = 2400 bps
• 3 = 4800 bps
• 4 = 9600 bps
• 5 = 19200 bps


Common Packets

Transmit
Master Device IPP
Direction
<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 1 Shift in.
packet Control character- 0Fh
15 Packet type 2 Set IPP key management mode

Common Packets
Table 40 IPP Request Packet 15 Format

[Key Code] Packet 4 or 5 The key management operation
parameters mode for the IPP
• “SPAIN” – Spain SEMP/4B
mode
• “VISA” – IPP mode
• Other characters – no change
[SO] End of 1 Shift out.
packet Control character- 0Eh
{LRC} Block code 1 Error check character
check
Response Packet <SI>15[Key Code]<SO>{LRC}

Format
Table 41 IPP Response Packet 15 Format

<SI> Start of 1 Shift in.
packet Control character- 0Fh
15 Packet type 2 Set IPP key management mode
[Key Code] Packet 4 or 5 The key management operation
parameters mode for the IPP:
• “SPAIN” – Spain SEMP/4B
mode
• “VISA” – IPP mode
• Other characters – no change
[SO] End of 1 Shift out.
packet Control character- 0Eh
{LRC} Block code 1 Error check character
check
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} ( set Spain SEMP/4B mode)
<SI>15VISA<SO>{LRC} ( set MS / DUKPT mode)
NOTE
In IPP6, the following packet 15 variation is included for compatibility purposes
only, and does not result in the key information being erased.

Common Packets

Packet Data 4AN Value: 'IPP2', fixed as password
{LRC} 1H Error Check

Transmit
Master Device IPP
Direction
<SI>15IPP2<SO>{LRC}
• ACK if LRC
<SI>15IPP2<SO>{LRC}
ACK/NAK
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:

Common Packets

Data Elements Characteristics Comments
Key Management 2AH The two ASCII hex digits are
Mode concatenated big-endian, to produce a
[KMM] single control byte. The key
management mode register (8 bits) in
IPP7 is as follows:
Bit
0 1 2 Description
0 0 0 1DES MS (default)
Mixed mode (1DES

1 0 0
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)
Zero GISKE session key

1
support on
Bit 6 Description
0 N/A
Clear all MS master keys and

1
KLK

Common Packets
Table 44 Packet 17 Format (Continued)

Bit 7 Description
0 MAC empty working key

support off (default)
MAC empty working key

1
support on
DUKPT Engine 1/2 1AH The one ASCII-Hex digit is used

Mode Flag [DEMF] produce half of a control byte.
Note: This field
was added Bit 0 ( DUKPT Engine "1")
for IPP8 Description
emulation.
0 1DES DUKPT - Default
1 3DES DUPKT
Bit 1 ( DUKPT Engine "2")

Description
1 3DES DUPKT
Bit 2 ~ 3
----------
Reserved
Example
Engine= 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



Common Packets
Packet 17 Set IPP Key Management Mode

Transmit
Master Device IPP
Direction
<SI>17[KMM][PINER]<SO>{LRC}
• ACK if LRC
<SI>17[KMM][PINER]<SO>{LR
C}
• ACK if LRC and key management echo
is OK
• EOT if LRC is correct, but key
management echo is not OK.
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)

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,
<SI>17010<SO>{LRC}
<SI>17020<SO>{LRC}
<SI>17080<SO>{LRC}
<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,
<SI>17220<SO>{LRC}
10 1DES MS mode, zero key support on, zero GISKE session key support off,
<SI>17180<SO>{LRC}
11 Mixed MS mode, zero key support off, zero GISKE session key support on,
<SI>17390<SO>{LRC}
<SI>172A0<SO>{LRC}

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 Zero GISKE session key support is not
session key support 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

Common Packets

Key Management Mode 2AH The two digits are concatenated big-
[KMM] endian, to produce a single control
byte. The key management mode
register (8 bits) in IPP7 is as follows:
Bit
0 1 2 Description
0 0 0 Old single DE
Mixed mode (1DES

1 0 0
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
Zero GISKE session key

1
support on
Bit 6 Description
0 At least one MS key or KLK

key has been loaded.
All MS master keys and the

1 KLK are clear (no keys
loaded).
Bit 7 Description
0 MAC empty working key

support off.
MAC empty working key

1
support on.

Common Packets

DUKPT Engine 1/2 1AH The one ASCII-Hex digit is used
Mode Flag [DEMF] produce half of a control byte.
Note: This field was
added for IPP8 Bit 0 ( DUKPT Engine "1")
emulation. Description
1 3DES DUPKT
Bit 1 ( DUKPT Engine "2")

Description
1 3DES DUPKT
Bit 2 ~ 3
----------
Reserved
Example:
Engine= 1 2
DEMF = 0x30 0 1DES 1DES
0x31 1 3DES 1DES
0x32 2 1DES 3DES
0x33 3 3DES 3DES


Table 46 Packet 18 Check IPP7 Key Management Mode
Transmit
Master Device IPP
Direction
<SI>18<SO>{LRC}
• ACK if LRC
<SI>18[KMM][PINER]<SO>{LRC}

Common Packets
Table 46 Packet 18 Check IPP7 Key Management Mode

Transmit
Master Device IPP
Direction
• ACK/NAK
Packet 18 Examples: The following examples show the response packet,

<SI>18[KMM][PINER]<SO>{LRC} from the IPP.
<SI>18000<SO>{LRC}
<SI>18010<SO>{LRC}
<SI>18020<SO>{LRC}
<SI>18080<SO>{LRC}
<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}
<SI>18220<SO>{LRC}

Common Packets
<SI>18180<SO>{LRC}
11 Mixed MS mode, zero key support off, zero GISKE session key support on,
<SI>18390<SO>{LRC}
<SI>182A0<SO>{LRC}
<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}
<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]
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

Common Packets
Packet Z60 Format <STX>Z60.[aaa…aaa]<FS>[DUKPT ENCRYPTION]<ETX>{LRC}

DUKPT Table 47 Packet Z60 Format
<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] 16AH or 120AH [www….www] – 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.
<ETX> 1H End of Text, Value: 03h
Packet Z60 Length: • 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}
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 On receipt of the Z63 packet, Omni 33XX reads the user’s PIN from the keyboard,
and Encrypt PIN– echoing to the display [echo char] for each digit accepted. The PIN length can be
Custom PIN Entry between [min len] and [max len] digits, inclusive, or 0 if the
Requirements [NULL allowed flag] is set. There are two variations of these request
(VISA Mode) 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 <STX>71.0[PIN len][PIN block format]
Sample Packet Z63 Request <STX>Z63.[acct num]<FS>DUKPT ENCRYPTION[min len][max len]

for DUKPT [NULL allowed flag][echo char]<ETX>{LRC}
Response <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
Packet Delimiter 1A Value: (.), 2Eh [aaa...aa] 8-19N Card
account number

Common Packets
Table 48 Packet Z63 Format (Continued)

<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.


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.

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
Packet Type 3AN Value: M04
Packet M04 Length: • Maximum: 6 characters

Response Packet <SI>M04[PUSN]<SO>{LRC}

Format
Table 50 Packet M04 Format
Packet Type 3AN Value: M04
Permanent Unit Serial 11AN Unit Serial Number format:
Number [PUSN]
xxx-xxx-xxx
Packet M04 Length: • Maximum: 17 characters

Table 51 Packet M04 Communication Protocol

Transmit
Master Device IPP
Direction
<SI>M04<SO>{LRC}
• ACK if LRC okay.

• NAK if LRC incorrect (EOT after 3 NAKs).
<SI>M04[PUSN]<SO>{LRC}

MS-Specific Packets
Table 51 Packet M04 Communication Protocol (Continued)

Transmit
Master Device IPP
Direction
• ACK if LRC okay
• NAK if LRC
incorrect (EOT
after 3 NAKs).
EOT terminates session.
MS-Specific The following packets are specific to MS 1DES and 3DES operations. The default
Packets 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
<STX> 1H Shift In, Value: 0Fh
[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.
a. 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.
MS Packet 02 Length: • MAX: 126 characters

Communication Protocols
Each key stored in the IPP contains its own key attributes.

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
Transmit
Master Device IPP
Direction
<SI>02[n][hhhhhhhhhhhhh-
hhh]<SO>{LRC}
• ACK if LRC
<SI>02[n][hhhhhhhhhhhhhhhh]<SO>{LRC}
• ACK if LRC and key echo
are okay
• EOT if LRC correct, but key
echo incorrect
• IPP saves the new master key only
on receipt of ACK
• EOT terminates session

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
[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 • MAX: 102 characters

Block Format Length:
Packet 02 GISKE Key <SI>020<SO>{LRC}

Block Format
Example:

MS-Specific Packets
Table 56 Packet 02 GISKE Key Block Format Communication Protocol

Transmit
Master Device IPP
Direction
<SI>02[r][hhh.hhh]<SO>{LRC}
• ACK if LRC
<SI>02[n]<SO>{LRC}
• ACK if LRC, no errors, and key
echo okay
• 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.
[a] 1N Master Key address: 0–9
KLK: F


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 Communication

Address [a] Protocol Used
1DES mode 1DES (single-length Key-only format (IPP5/
key) IPP6)
3DES (single-, double- GISKE key block
, or triple-length key) formata
Mixed or 3DES mode 1DES (single-length GISKE key block format
key)
3DES (single-, double- GISKE key block format
, or triple-length key)
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
[r] 1AN Response code:
• 0 = No master key at address [a]
• F = Master key present at address [a]

MS-Specific Packets
Table 59 Response Packet 04 Key-only Format Communication

Protocol
Transmit
Master Device IPP
Direction
<SI>040<SO>{LRC}
• ACK if LRC okay

• PIN pad checks requested address [a].
<SI>04[r]<SO>{LRC}
• ACK if LRC okay
EOT
Response Packet 04 • MAX: 6 characters

Key-only Format
Length:
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
Characteristic Comments
Element
[r] 1AN Response code:
• 0 = No master key at address [a]
• F = Master key present at address [a]

MS-Specific Packets
Table 60 Response Packet 04 GISKE Key Block Format (Continued)

Data
Element
Key Usage 2AH Only when master key is present at address [a]:
Attribute (KUA) • 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)
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: 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.

MS-Specific Packets
Table 60 Response Packet 04 GISKE Key Block Format (Continued)

Data
Element
Mode of Use 1AH (optional) Only if the master key present at
Attribute address [a]. The value is stored in the key
(MOUA) 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: 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.
Key Version 2AH (optional) Only if the master key present at
(KV) 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: The IPP allocates 1 byte per key for
each key version register.
Key Length 1AH (optional) Only if the master key present at
(KL) address [a].
• 1: single-length key
• 2: double-length key
• 3: triple-length key
Note: The IPP allocates 1 byte per key for
each key version register.
Response Packet • MAX: 12 characters

GISKE Block Format
04 Length:
Response Packet 04 <SI>040[KUA][MOUA][MACMA][KV][KL]<SO>{LRC}

GISKE Block Format
Example:

MS-Specific Packets
Table 61 Response Packet 04 GISKE Block Format Communication

Protocol
Transmit
Master Device IPP
Direction
<SI>04[a]<SO>{LRC}
• ACK if LRC okay

• PIN pad checks requested address [a].
<SI>04[r][KUA][MOUA][MACMA][KV][KL]<SO>{L
RC}
• ACK if LRC okay
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.
[a] 1N Master Key address: 0–9

MS Packet 08 To select Master Key 7:

Example:
<SI>087<SO>{LRC}

MS-Specific Packets
Table 63 MS Packet 08 Communication Protocol

Transmit
Master Device IPP
Direction
<SI>08[a]<SO>{LRC}
• ACK if LRC
• 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 cipher-
text PIN block to the master device.
Packet 1A Value: (.), 2Eh
Delimiter
Function Key 1N Value is 0; Function key feature not
Indicator implemented.
PIN Length 2N Range 00, 04 to 12
PIN BLock 2N Value: 01; Format of PIN block prior to
Format encryption
Encrypted PIN 16H The 64-bit encrypted PIN block represented as
Block 16 hexadecimal digits. Present only if PIN
entered.


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
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
a. Error code 5 does not occur in the IPP, since it supports simultaneous DUKPT and MS.

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 The following packets are specific to DUKPT operation. Two DUKPT modes are
Packets 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.

DUKPT-Specific Packets
Table 66 DUKPT Packet 19 Format

[a] 1N DUKPT Engine: "0", "1",or "2"
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
Transmit
Master Device IPP
Direction
<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
(EOT after 3 NAKs)
…
IPP changes DUKPT engine
…
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".

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
Packet 25 Length: • Maximum: 5 characters

Response Packet <SI>25[PUSN]<SO>{LRC}

Format
[a] 1N Active DUKPT Engine: "0", "1",or "2"
Packet 25 Length: • Maximum: 6 characters

Sample Packet:
To Check DUKPT Engine:
<SI>25<SO>{LRC}
Response packet, DUKPT Engine "1" = active DUKPT Engine:

<SI>251<SO>{LRC}


Transmit
Master Device IPP
Direction
<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: 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
(for Packets Z60 or Mode). The IPP encrypts the formatted clear-text PIN block and sends the cipher-
Z63) text PIN block to the master device.
<STX> 1H Start of text, Value: 02h
Packet 1A Value: (.), 2Eh
Delimiter
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 16AH The 64-bit encrypted PIN block represented as
Block 16 hexadecimal digits.
<ETX> 1H End of text, Value: 03h
DUKPT Packet 73 • MAX: 47 characters

Length:
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:

Table 72 MS Response Packet 73 Format: Errors in Z60 or Z63 Packet

<STX> 1H Start of text, value: 02h
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
a. Error code 5 do not occur in the IPP, since the IPP supports simultaneous DUKPT and MS.

Length:
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
[IPEK] 16H Initial PIN Encryption Key, hexadecimal
[KSN] 20H Key Serial Number; hex (leading Fs included)
{LRC} 1H Error check character

Length
NOTE
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.


Transmit
Master Device IPP
Direction
90 Packet
• ACK if LRC
• Initialization of 21 Future Keys
Packet 91 with confirmed status

• ACK if LRC
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.
[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:
Initial PIN IPP7 Current [CS] response from

encryption key length DUKPT Mode the IPP
(through packet 90)
sent by the master device
16AH 3DES 2
32AH 1DES 2


Length


Transmit
Master Device IPP
Direction
Packet 91
• ACK if LRC
DUKPT Packet 76: Directly presets the PIN code '1234' to do encryption and send response
PIN Entry Test packet 71.
Request
[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.

Length
NOTE
The amount filed must be present in the packet command, but the format is not
confirmed.

Transmit
Master Device IPP
Direction
76 Packet
• ACK if LRC
Packet 71 with PIN = 1234

• ACK if LRC

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.
Function Key 1N Value: 0, function key indicator feature not
implemented
Key Serial 10-20H Hexadecimal (leading Fs suppressed.);
Number Included only if PIN entered; length is 0 if no PIN
entered
Encrypted PIN 16H The 64-bit encrypted PIN block represented as
Block 16 hexadecimal digits; length is 0, if no PIN
entered.

Length:
• 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
• 5 = C|D field error

Length:
• MIN: 6 characters (if NULL entered)


Example:
DUKPT Packets 92 The DUKPT reinitialization request and reinitialization response packets are not
and 93 supported in Omni 33XX.
DUKPT Z69 Packet: On receipt of the Z69 packet, Omni 33XX reads the user’s PIN from the keyboard,
Accept and Encrypt echoing to the display an asterisk for each digit accepted. The PIN length can be
PIN / Data between 4 and 12 digits.
Authentication
Table 81 DUKPT Packet Z69 Format
Request
[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.
[C/D] 1H Credit/debit indicator, value 43h/44h
[amount] 3–13N Transaction amount including the decimal point.
DUKPT Packet Z69 • MAX: 24 characters

Length
Table 82 DUKPT Packet Z69 Communication Protocol
Transmit
Master Device IPP
Direction
Z69 Packet
• ACK of LRC okay

Packet 75 with confirmed status
• ACK if LRC
DUKPT Packet Z69 VISA:

Example:
<STX>Z6901234567890<FS>C19.99<ETX>{LRC}
ANSI:
<STX>Z6901234567890<US>C19.99<ETX>{LRC}



No <FS> EINVAL
DUKPT Packet 75: Response packet to packet DUKPT Z69 Packet: Accept and Encrypt PIN / Data
DUKPT Accept and Authentication Request or Packet 78: DUKPT Accept and Encrypt PIN/Data
Encrypt PIN/Data Authentication Test Request to the controller with confirmation status.
Authentication Authentication code #1 is the MAC on this message. If the request is approved,
Response 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.
[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.
Function Key 1N Value is 0, Function Key Indicator feature not
implemented
Key Serial 10–20H Hexadecimal (leading Fs suppressed.);
Number Included only if PIN entered; Length is 0 if no PIN
entered
Encrypted PIN 16H The 64 bit encrypted PIN block represented as
Block 16 hexadecimal digits.
Length is 0, if no PIN entered.

Length:

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
• 3 = PIN too long
• 4 = PIN too short/non-decimal digit in PIN
• 5 = C|D field error/not DUKPT mode
• 7 = amount error
• 8 = ANSI MAC not allowed when using 1DES
DUKPT

Length:

Example:

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
NOTE Packet 78 is similar to packet Z69, but the PIN code is preset to “1234.” The user
is not prompted to enter a PIN.
This packet is used for testing and should not be used by applications.

[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.
[C/D] 1H Credit/Debit indicator, value: 43h/44h
[amount] 3-13N Transaction amount, decimal point included.

Length:
NOTE 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}

MAC-Specific Packets

Transmit
Master Device IPP
Direction
78 Packet
• ACK if LRC
Packet 75 with PIN = 1234

• ACK if LRC
MAC-Specific This section describes the master-session MAC generation of received message
Packets 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
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
[sequence] 2N Range: 00–99
Master Key 1N Optional; Range: 0–9
Pointer
Working Key 16H Encrypted working key for DES

Table 87 MAC Packet Z66 Format (Continued)

Second Key 1N Optional; Second master key pointer;
Range: 0–9
Message for 8*XAN0 ASCII message or ASCII-coded binary data:
MACa X= 0–28 for ASCII data
X= 0,2,4,6,...,27,28 for binary data
a. ASCII messages for MAC should not include ETX(0x03) or SO(0x0E).
MAC Packet Z66 • MAX: 255 characters

Length:
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
:
:
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.

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 Apply to
Packet
Size of X of Message Message Comments
Type
(bytes) Sequence
Key- ASCII: X = 0, 1, 2 – 27, 224 00–99
only 28
format
Binary: X = 0, 2, 4 – 26, 224
28
GISKE ASCII: X = 0, 1, 2 – 14, 120 00 – 99 Due to size
Key 15 of GISKE
Block key block,
Format the size of
mode message is
reduce to
120 bytes.
Binary: X =0, 2, 4 – 12, 112
14
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.
• Sends an error code to the master device if there any error is detected during
the MAC session.

• Sends the MAC value to the master device.

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 field 16H Optional; only sent when no errors are detected
MAC Packet Z67 • MAX: 23 characters

Length:
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.

Packet Z72 Example: <STX>712 <ETX>{LRC}


Transmit
Master Device IPP
Direction
<STX>72<ETX>{LRC}
• ACK if LRC
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.

INDEX
Numerics real time clock 33

1DES master key 284 serial port 33
Sound 33
A touch panel 33
audio USB 33
beeper units 135 directory structure 198
disabling speakers 134 file organization 198
vlume, bass and treble control 133 user space and security 199
user space base structure 199
C
display 130
C compiler and development tools dspSetBrightness() 131
C compiler & tools 13 downloading 26
COM1 98 IBM ECR 27
COM2 99 NFS 26
COM3 service functions 174 TCP/IP 27
svcCom3FlushRxBuf() 185 USB Memory Device 27
svcCom3Polled() 188 Zontalk 26
svcCom3ReqExtStatus() 176 downloading files from the ECR 119
svcCom3ReqFirmVers() 180 DUKPT
svcCom3ReqTallyInfo() 178 IPP7 324
svcCom3ResTallyData() 179
svcCom3SetBufFlushInt() 187 E
svcCom3SetDeviceAddr() 181 ECR Environment Variables 116
svcCom3SetECLevel() 182 Environment Variables
svcCom3SetHandshake 183 P4683 117
svcCom3SetMode() 175 environment variables 15
svcCom3SetRxRecThresh() 186 A4683 117
COM4 100 G4683 118
COM5 100 I4683 116
config.usrx 18 L4683 117
configuration variables 15 O4683 116
S4683 118
D V4683 118
Delta smartcard interface/cardslot 92 environment/configuration variables
device drivers getEnvFile 19
Delta 33 putEnvFile 20
Display 33
F
ethernet port 33
IPP 33 file authentification 28
magnetic stripe reader 33 file compression 15

I NDEX
file format details 15 IPP7 46, 284

file systems 15 DUKPT modes 324
firmware 13
J
G JFFS2 15
getenv() 15
K
GISKE
key attribute 284 key 285
KLK key loads 285 key attributes, IPP 284
GNU C compiler 13 KLK (GISKE) 285
GNU ZIP 15 L
I LEDs 136
IBM ECR tailgate & feature C 100 ledOff 138
ecrRead 102 ledOn 137
ecrReadReject 103 M
ecrStatus 104
MAC value 286
IBM ECR tailgate & feature CecrClose 110
magnetic stripe reader 34
IBM ECR tailgate & feature CecrDownload 111
msrClose 45
IBM ECR tailgate & feature CecrWrite 109
msrDisableLicenseDecode 43
internal PIN pad
msrEnableLicenseDecode 42
int ippClose(void) 48
msrMagneticCardPresent 39
int ippOpen(void) 47
msrOpen 35
int ippRead(char *buffer, int size) 49
msrRaw 40
int ippWrite(char *buffer, int size) 50
msrRead 36
SetSecurePINDisplayParameters() 51
msrStructured 41
IPP
msrVersion() 44
key attributes 284
msrWrite 38
key length 284
M 800 series COM ports 98
x
key version 284
COM3 99
IPP differences 56
IPP ROM version number 56 O
multiple DUKPT 56 operating system 13
PROM checksum 56
select baud rate 56 P
set IPP6 key management mode 56 packet mode 94
set IPP7 key management mode 56 endPktMode() 96
set master key 56 Receiving Packet Messages 97
IPP refenreces 57 putenv() 15
GISKE specification 57
PP7 specification 57 R
ipp_abort() 224 real-time clock 139
ipp_getpin() 217 void setRTC(void) 140
ipp_mac() 222 reference documents
ipp_read() 219 LINUX books 12

I NDEX
root file system 197, 215 Signature Capture API 123

BusyBox 197 svcDsp2Hex() 146
uClibc 197 svcInfoRFS() 149
System Mode 195
S
security services APIs 80 T
AES() 86 touch panel 120
authFile() 90
cryptoRead() 82 V
cryptoWrite() 81 Verishield Security Scripts (VSS) 57
DES() 85 VSS APIs 57
generateRandom() 87 iPS_CancelPIN() 73
IRSA Computation 83 iPS_CheckMasterKey() 64
isAttacked() 88 iPS_DeleteKeys() 59
loadOSFiles() 91 iPS_ExecuteScript() 77
secVersion() 89 iPS_GetPINResponse() 70
SHA1() 84 iPS_GetScriptStatus() 75
serial communication control structure 93 iPS_InstallScript() 74
packet_parms 94 iPS_LoadMasterClearKey() 62
protocol 93 iPS_LoadSysClearKey() 60
trailer 94 iPS_RequestPINEntry() 69
service functions 143 iPS_SelectPINAlgo() 68
svcAlarm() 167 iPS_SetPINParameter() 66
svcCrcCalc() 144 iPS_UninstallScript() 76
svcExpand 172 pcPS_GetVSSVersion() 79
svcGetInQ() 170 SetSecurePINDisplayParameters() 65
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

VeriFone, Inc.
2099 Gateway Place, Suite 600
San Jose, CA, 95110 USA
Tel: (800) VeriFone (837-4366)
www.verifone.com
Mx800 Series
Programmers Guide

Programmers Guide - Verifone Support Portal

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Programmers Guide - Verifone Support Portal

Загружено:

Авторское право:

Доступные форматы

Mx800 Series

Part Number 23753, Revision A

int ippWrite(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4 MX800 SERIES REFERENCE MANUAL

MX800 SERIES REFERENCE MANUAL 5

6 MX800 SERIES REFERENCE MANUAL

USB Mass Storage and Memory Devices. . . . . . . . . . . . . . . . . . . . . . . . . . 202

MX800 SERIES REFERENCE MANUAL 7

8 MX800 SERIES REFERENCE MANUAL

Master Key for PIN Encryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

MX800 SERIES REFERENCE MANUAL 9

10 MX800 SERIES REFERENCE MANUAL

Modifications to This document may be changed or extended to include new product

Acronyms, Table 1 Acronyms, Abbreviations, and Definitions

MX800 SERIES PROGRAMMERS GUIDE 11

Table 1 Acronyms, Abbreviations, and Definitions

Table 2 Major Hardware Devices

ARM9 ARM SoC

Conventions The following table describes the conventions used:

The caution symbol indicates possible hardware or software

Recommended Beginning Linux Programming (3rd Edition)

12 MX800 SERIES PROGRAMMERS GUIDE

Overview of Product Deliverables

MX800 SERIES PROGRAMMERS GUIDE 13

14 MX800 SERIES PROGRAMMERS GUIDE

MX800 SERIES PROGRAMMERS GUIDE 15

16 MX800 SERIES PROGRAMMERS GUIDE

MX800 SERIES PROGRAMMERS GUIDE 17

18 MX800 SERIES PROGRAMMERS GUIDE

label Points to a null terminated string containing the label (reference

0 Entry not found

Less than 0 An error occured:

MX800 SERIES PROGRAMMERS GUIDE 19

label Points to a null terminated string containing the label (reference

value Points to a null terminated string containing the value associated

Less than 0 An error occured:

20 MX800 SERIES PROGRAMMERS GUIDE

Note that Linux is case-

“-t nfs –o nolock

MX800 SERIES PROGRAMMERS GUIDE 21

*FTPPWD Default = Terminal S/N FTP password

22 MX800 SERIES PROGRAMMERS GUIDE

MX800 SERIES PROGRAMMERS GUIDE 23

=0 Entry not found.

<0 An error has occurred:

24 MX800 SERIES PROGRAMMERS GUIDE

Dynamically modifies the value of the kernel parameters in the /proc/sys

<0 An error has occurred:

MX800 SERIES PROGRAMMERS GUIDE 25

Syslog The Mx800 series of terminals supports logging messages generated by

26 MX800 SERIES PROGRAMMERS GUIDE

MX800 SERIES PROGRAMMERS GUIDE 27

• If a .TAR file contains a special file named config.usrx (where x is 1 to 8)

An example config.usr1 file:

28 MX800 SERIES PROGRAMMERS GUIDE

install <file.ipk> Install package <file.ipk>

remove <pkg> Remove package <pkg>

list_installed List all and only the installed packages and

MX800 SERIES PROGRAMMERS GUIDE 29

Below is an example of a control file:

4 If your package has any configuration files, then create a file

30 MX800 SERIES PROGRAMMERS GUIDE

Description should be a short, (less than 80 characters) description of the program.

MX800 SERIES PROGRAMMERS GUIDE 31