MX800 Programmers Guide

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 VeriFones products and services are trademarks of VeriFone, Inc. All other brand names and trademarks appearing in this manual are the property of their respective holders. Comments? Please e-mail all comments on this document to your local VeriFone Support Team.
VeriFone, Inc. 2099 Gateway Place, Suite 600 San Jose, CA, 95110 USA www.verifone.com Part Number 23753, Revision A
CONTENTS
CHAPTER 1 Introduction Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Modifications to this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Acronyms, Abbreviations, and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions Used in this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recommended LINUX Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 11 12 12
CHAPTER 2 Overview of Product Operating System and Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Deliverables C Compiler and Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CHAPTER 3 File Systems File Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Environment/Configuration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Format Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getEnvFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . putEnvFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Configuration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSysctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . putSysctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syslog Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloaded Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Authentication and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building ipkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing ipkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 19 20 21 24 25 26 26 26 27 28 28 29 31
CHAPTER 4 Device Drivers Device Drivers for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . 33
Magnetic Stripe Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrMagneticCardPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrRaw. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrStructured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrEnableLicenseDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrDisableLicenseDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . msrClose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internal PIN Pad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int ippOpen(void). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int ippClose(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int ippRead(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Note on the PIN session timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 35 36 38 39 40 41 42 43 44 45 46 47 48 49 49
3
MX800 SERIES REFERENCE MANUAL
C ONTENTS
int ippWrite(char *buffer, int size) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SetSecurePINDisplayParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int ippPinEntryStatus(int *count, int *lastNonNumericKey) . . . . . . . . . . . . . . ippTerminatePinEntry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IPP Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IPP Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GISKE Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VeriShield Security Scripts APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_DeleteKeys() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_LoadSysClearKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_LoadSysEncKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_LoadMasterClearKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_LoadMasterEncKey(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_CheckMasterKey(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SetSecurePINDisplayParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_SetPINParameter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_SelectPINAlgo(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_RequestPINEntry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_GetPINResponse() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_CancelPIN(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_InstallScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_GetScriptStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_UninstallScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iPS_ExecuteScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pcPS_GetVSSVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Services APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cryptoWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cryptoRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rsa_calc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHA1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . generateRandom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isAttacked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . secVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . authFile(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loadOSFiles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delta Smartcard Interface / CardSlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial Ports and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial Communication Control Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packet_parms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packet Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initialize Packet Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . endPktMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving Packet Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COM Ports on the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . COM1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COM2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
50 51 54 55 56 57 57 57 57 57 59 60 61 62 63 64 65 66 68 69 70 73 74 75 76 77 79 80 81 82 83 84 85 86 87 88 89 90 91 92 92 93 93 94 94 94 95 96 97 98 98 99
C ONTENTS
COM3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 COM4 - Optional I/O Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 COM5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 IBM ECR Tailgate & Feature C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 ecrOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 ecrRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 ecrReadReject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 ecrStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 ecrWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 ecrClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 ecrDownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 ecrDnldCancel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 ECR Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 I4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 O4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 A4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 P4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 L4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 S4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 V4683. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 G4683 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Downloading Files from the ECR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Touch Panel / Signature Capture/TIFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 touchCmd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 touchCompNSave() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Signature Capture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 SigCapCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 SigCapGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 SigCapBoxApply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 TIFF API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 int SigCap2Tiff() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 dspSetBrightness() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Audio / Beeper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 soundCtrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 speaker(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 normalTone() / errorTone() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 LEDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ledOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 ledOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Real-Time Clock (RTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 setRTC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 setDateTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
CHAPTER 5 Service Functions Service Functions for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . 143
svcCrcCalc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcDsp2Hex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcRestart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoKernel() / svcInfoEprom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoRFS() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 146 147 148 149
5
C ONTENTS
svcInfoSerialNum() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoPtid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoPlatform(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoDsp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoCard() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcInfoSerialNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcZontalkRcv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zontalkCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcSetOpenBlock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcSetRxCallback(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcReleaseRxCallback(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcSetAlarmCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcReleaseAlarmCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcAlarm(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcGetPortStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcGetInQ(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcGetOutQ() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcExpand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcUsbStorPresent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COM3 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3SetMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3ReqExtStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3ReqTallyInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3ResTallyData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3ReqFirmVers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3SetDeviceAddr(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3SetECLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3SetHandshake() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3FlushRxBuf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3SetRxRecThresh() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3SetBufFlushInt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcCom3Polled(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svcGetSysMillisec(), svcGetSysMicrosec(). . . . . . . . . . . . . . . . . . . . . . . . . enableProcessMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . disableProcessMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enableButtonSig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . disableButtonSig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
150 151 152 154 155 156 157 158 159 161 162 163 164 165 166 167 168 170 171 172 173 174 175 176 178 179 180 181 182 183 185 186 187 188 189 190 191 192 193
CHAPTER 6 System Mode System Mode for the Mx800 series of Terminals . . . . . . . . . . . . . . . . . . . . . . . 195 CHAPTER 7 Root File System Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Organization of Files in the Standard Directory Structure. . . . . . . . . . . . . . 198 User Space Base Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 User Space and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
CHAPTER 8 USB - Device / Host USB Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

USB Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
6
C ONTENTS
USB Mass Storage and Memory Devices. . . . . . . . . . . . . . . . . . . . . . . . . . 202 USB Human Interface Device (HID) Support . . . . . . . . . . . . . . . . . . . . . . . . . . 204
CHAPTER 9 TCP/IP Ethernet Network Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

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

inputRead(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 inputClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
C ONTENTS
C H A P T E R 13 Visual Payments Visual Payments Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

vpInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 vpParseFields(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 vpSendPacket() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 vpExit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 vpVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Visual Payments Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 fnDownReq(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 fnDownFileStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 fnUpData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 fnUpDisconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 fnTimedOut(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Network/Ethernet Library Functions Required by Visual Payments . . . . . . . . . 267 ftpPut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 ftpGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 netLinkStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 netDown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 netUp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 netPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 XFTP Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 XFTPGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 XFTPPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 XFTPDEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 IPP MS and DUKPT Advanced Programming in IPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Minor Differences by Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Communications <SI>0103<SO> PROM Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Packets <SI>0108<SO> IPP ROM Version Number . . . . . . . . . . . . . . . . . . . . . . 275 <SI>13n<SO> Select Baud Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 <SI>15SPAIN<SO> Set IPP6 Key Management Mode . . . . . . . . . . . . . 276 <SI>17xyz<SO> Set IPP7 Key Management Mode . . . . . . . . . . . . . . . 276 <SI>02<SO> Set Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 <STX>75..<ETX> DUKPT Accept and Encrypt PIN/Data Authentication Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Packets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Packet Acknowledgement and Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 MS Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 DUKPT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 NAKs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Time Outs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Key Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Master Key Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 DUKPT Initial PIN Encryption Key Insertion . . . . . . . . . . . . . . . . . . . . . 281 Entering a PIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Restrict the Speed of the PIN Encryption Operation. . . . . . . . . . . . . . . . . . 281 IPP7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 GISKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Key Management Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Using a Session Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 Loading the Session Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8
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 PINCustom PIN Entry Requirements (VISA Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Errors returned by write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Packet M04: Read Permanent Unit Serial Number . . . . . . . . . . . . . . . . . . 313 MS-Specific Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Packet 02: Transfer Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Communication Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Key-only Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 GISKE Key Block Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Packet 04: Check Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Packet 04 Communication Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Packet 04 Key-only Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Packet 04 GISKE Key Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 MS Packet 08: Select a Master Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 MS Packet 71: Transfer PIN Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 Packet 07: Dummy Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 DUKPT-Specific Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Packet 19: Select a DUKPT Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Packet 25: Check the DUKPT Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 DUKPT Packet 73: Transfer PIN Block (for Packets Z60 or Z63). . . . . . . . 327 DUKPT Packet 90: Load Initial Key Request . . . . . . . . . . . . . . . . . . . . . . . 328 DUKPT Packet 91: Load Initial Key Response . . . . . . . . . . . . . . . . . . . . . . 329 DUKPT Packet 76: PIN Entry Test Request . . . . . . . . . . . . . . . . . . . . . . . . 330 DUKPT Packet 71: Transfer PIN Block - (for Packet 76) . . . . . . . . . . . . . . 331 DUKPT Packets 92 and 93 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 DUKPT Z69 Packet: Accept and Encrypt PIN / Data Authentication Request . 332 Errors returned by write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 DUKPT Packet 75: DUKPT Accept and Encrypt PIN/Data Authentication Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
C ONTENTS
Packet 78: DUKPT Accept and Encrypt PIN/Data Authentication Test Request 335 MAC-Specific Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 MAC Packet Z66: Request MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Rules of Request MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 MAC Packet Z67: Return MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Packet 72: Cancel MAC Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 MAC Module Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 ANSI (Standard) MAC Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
10
CHAPTER 1
Introduction
Scope
This document describes the programming environment for the Mx800 series of terminals. This document lists or references all significant functions unique to the terminal. This document will not describe the Linux application API. There are many good books on this topic. This document will list unsupported features and any deviations from standard Linux. Distinction will be drawn, where possible, between functions that are built into the terminal and are available when no application is present and functions that only become available if the application performs the correct programming operations.
Modifications to this document Acronyms, Abbreviations, and Definitions
This document may be changed or extended to include new product requirements. Table 1 Acronyms, Abbreviations, and Definitions Definition
Interrupt Service Routine Software in FLASH/ROM Journaling Flash File System Network File System File Transfer Protocol
Abbreviation
ISR Firmware JFSS2 NFS FTP
iPKG
MSR IPP PED VSS FA
The Itsy Package Management System

Magnetic Stripe Reader Internal PIN Pad PIN Entry Device VeriShield Security Scripts File Authentication
KLK
KVC SAM OSS LED RTC RRT BFI RFCR
VSS Key Loading Key

Key Verification Code Security Access Module Open Sound System Light Emitting Diode Real-time Clock Receive Record Threshold Buffer Flush Interval
RF Card Reader
MX800 SERIES PROGRAMMERS GUIDE
11
I NTRODUCTION Conventions Used in this Document
Table 1
Acronyms, Abbreviations, and Definitions Definition

Cyclic Redundancy Check bits per second Master Session Key Serial Number PIN Encryption Key Global Interoperable Secure Key Exchange
Abbreviation
CRC bps MS KSN PEK GISKE
Table 2
Major Hardware Devices
ARM9 Graphic Display
ARM SoC Color (16 bpp) QVGA (320x234)
Conventions Used in this Document
The following table describes the conventions used: Table 3 Convention

Blue
Document Conventions Meaning

Text in blue indicates terms that are cross referenced. The courier typeface is used while specifying onscreen text, such as text that you would enter at a command prompt. Italic typeface indicates book titles or emphasis. 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.
Courier Italics
SCREENTEXT
NOTE
CAUTION
The caution symbol indicates possible hardware or software failure, or loss of data.
Recommended Beginning Linux Programming (3rd Edition) LINUX Books

By: Neil Matthew, Richard Stones See: http://www.wrox.com/WileyCDA/WroxTitle/productCd-0764544977.html
12
CHAPTER 2
Overview of Product Deliverables
Operating System and Firmware
The Mx800 series terminal is the first VeriFone product to run ARM embedded Linux. The initial kernel will be version 2.6.10. Required libraries are described in the succeeding sections.
C Compiler and The GNU C compiler will be used to build Mx800 Series applications. The Tools Software Development Kit will include a version of the GNU development tools
that will run under Windows (using Cygwin). The Mx800 Series terminal will include gdbserver for use during application debug. VeriFone has created a "plug in" feature for the Eclipse IDE that simplifies application project building and debug.
13
O VERVIEW OF P RODUCT D ELIVERABLES Operating System and Firmware
14
CHAPTER 3
File Systems
The Mx800 series terminal file system uses the Journaling Flash File System or JFFS2. JFFS2 is used to store application code and data as well as shared libraries. JFFS2 supports wear leveling and power fail protection.
File Compression
The Mx800 series of terminals will support GNU ZIP (.gz or .tgz or tar.gz) compressed files. The system will support both creation and expansion of GNU ZIP files. Downloaded files may be compressed. The TAR format is used to combine multiple files into a single file. The resulting file may then be compressed. This process produces a tar.gz file. Winzip can open a tar.gz file but it cannot create one. There are a number of applications available to create tar.gz files on a Windows platform. Linux has long had the concept of environment variables (also called configuration variables). Unfortunately, environment variables are not permanent and Linux normally requires a shell script that sets the environment variables prior to their use. The Mx800 series of terminals will augment this process by having files in battery backed SRAM to store configuration variables. getenv() and putenv() are native functions to Linux. Using putenv() will set/ change/delete an environment variable but the value will not persist if a power failure occurs. The Mx800 series of terminals supports enhanced APIs getEnvFile() and putEnvFile() to get or set environment variables in the battery backed SRAM file system.
Environment/ Configuration Variables
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.
15
F ILE S YSTEMS Environment/Configuration Variables
By default, all configuration files will have two sections, perm and reg. The perm section is special in that entries under perm will not be deleted on a full download. All other section entries will be deleted on a full download. To aid compatibility with previous terminals, all keys that begin with * will automatically be placed in the perm section provided the section parameter is a pointer to an empty null terminated string. (i.e. empty quotes ). The leading * character is not actually stored in this case. It only indicates that the label field should be stored in or retrieved from the perm section. If a section is specified then the value field is stored as it is given to the function, including any * character. This also applies even if the section is specified to be the perm section. It is only if an empty, nullterminated string is specified for the section is any leading * character ignored. All created sections, and label entries will be converted to lower case before being stored to eliminate case sensitivity. The getEnvFile() and putEnvFile() functions will always convert to lower case before searching or storing. The value part of the environment variable is case-sensitive and will always be stored as it is passed to the functions. There are certain reserved characters with the INI parser library that cannot be used in section, label or value fields and there are certain characters that are not accepted. All other characters can be used including non-printable ASCII characters. Please refer to the INI parser html document included in the SDK for basic explanation of how the INI parser works and what is supported. In addition to that documentation, the following characters are reserved and cannot be used within one or more of the fields of the environment variable or have special rules concerning them: Table 4 Character
Null
Hex
0x00
Decimal
0
Usage
Used to terminate string and cannot be stored as part of section, label or value field. Cannot be used in leading and trailing position of section, label or value field. Can only be used in non-leading and trailing positions. This is a reserved character and cannot be used in any field. If used, unexpected and unsupported results may occur. Cannot be used in leading and trailing position of section, label or value field. Can only be used in non-leading and trailing positions. This is a reserved character and cannot be used in any field. If used, unexpected and unsupported results may occur. Cannot be used in leading and trailing position of section, label or value field. Can only be used in non-leading and trailing positions.
Space
0x20
32
Equal (=)
0x3D
61
Horizontal Tab
0x09
Line Feed
0x0A
10
Vertical Tab
0x0B
11
16
Table 4 Character
Form Feed
Hex
0x0C
Decimal
12
Usage
This is a reserved character and cannot be used in any field. If used, unexpected and unsupported results may occur. This is a reserved character and cannot be used in any field. If used, unexpected and unsupported results may occur. 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. 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. This is a reserved character and cannot be used within the section field. This is a reserved character and cannot be used within any field. If used, unexpected and unsupported results may occur. This is a reserved character and cannot be used within the section field.
Carriage Return
0x0D
13
Hash Sign (#)
0x23
35
Semi-colon (;)
0x3B
59
Forward Slash (/) Left Bracket ([)
0x2F 0x5B
47 91
Right Bracket (])
0x5D
93
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.
17
There are also command line versions of these 2 functions below called getEnvFile and putEnvFile that are mainly used for development purposes. When these command line versions are used, it is necessary to double-quote each part, label, and value fields separately to prevent the Linux shell from interpreting the characters. Each part needs to be quoted separately. For example: putenvfile *dhcp 1. Also, these functions do not support the creation of custom sections. For a custom section to be created, use the API function putEnvFile with the label parameter set to an empty, null-terminated string (i.e. ) and the section parameter set to the desired new section name. The custom section will not be created if the label parameter is not an empty string. Each user will have its own configuration file called config.usrx where value of x is 1-8. Root will have its own configuration file. The configuration files will be stored in the file system at /mnt/sram directory. The system limits each configuration variable to a maximum of 8KB, once reached, it is not possible to add and modify configuration variables.
18
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. Points to an area where the value of the environment variable will be copied. Maximum length is 512 bytes. Value will be null terminated.
value
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 0 Less than 0 Length of value Entry not found An error occured: -ENOBUFS Internal message error
19
F ILE S YSTEMS putEnvFile
putEnvFile
Prototype
int result = putEnvFile(char *section, char *label, char *value, unsigned short vlen, unsigned short options);
Parameters
section Points to a null terminated string containing the .ini file section name. Maximum length of the section name is 31 bytes.
Note:
If section is a pointer to null, the system will automatically read from with perm or reg. perm will be selected if the first character of label is an * otherwise section reg is used.
label
Points to a null terminated string containing the label (reference name) of the entry. Maximum length of the label is 32 bytes and will automatically be converted to lowercase before being stored. To create a new section, pass a pointer to null (i.e. empty string ) for the label parameter. 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 ).
value
Return Values
0 Less than 0 No error An error occured: -ENOBUFS No environment variable space
20
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
*GO
Values
Executable name
Definition
The path /home/usr1 is pre-pended to the value set in *GO. Example: *GO=myapp The system will attempt to execute the file: /home/usr1/myapp
Note that Linux is casesensitive. *NETOFF 1 If *NETOFF exists (set to any value), then TCP/IP functions (*DHCP, *IPCONFIG, *GATEWAY) are disabled. If *DHCP is present and the system supports Ethernet, then it will attempt to initialize its connection via DHCP. Use either *DHCP or *IFCONFIG.
*DHCP
Non-zero
*IFCONFIG
Per Linux No need to set MAC address as the system will do this for you. See Chapter 9. IP Address in the form xxx.xxx.xxx.xxx 1
*GATEWAY *TELNET
Used to define the address of the gateway (router). If *TELNET is present and the system supports Ethernet, then it will start the Telnet server daemon. If *DBG is present then the Visual Esto debugger will be enabled Sets the display backlight brightness. Default is 15. Sets the speaker volume. Default is 50. Allows up to 10 mount points to be defined.
*DBG
*BACKLIGHT *VOLUME *MOUNT0 - *MOUNT9
1-31 0-100 Per Linux. Example: -t nfs o nolock 10.64.88.249:/nfs /mnt/ smfnfs
21
Table 5 Variable Name

*USB DEVICE
Values
1
Definition
Enable USB serial device mode. You must reboot after setting this variable. Remove variable and reboot to disable. IF *USBHOST exists, USB host (hotplug) will be disabled. Either IP address or DNS name of FTP server.
*USBHOST
*FTPHOST
xxx.xxx.xxx.xxx or ASCII server DNS name Max length = 96 characters
*FTPPORT *FTPFILE
Default = 21 Default=app.tgz Max length = 96 characters
Port number for FTP connection. Remote file name (and path) of file to be retrieved from the FTP server. FTP password
*FTPPWD
Default = Terminal S/N Max length = 32 characters
*FTPUSER
Default = anonymous Max length = 32 characters
FTP User ID
*SYSLOG_MARK
Default = 30 Min = 10 Max = 1440 Off = 0
Specifies when a MARK timestamp marker is placed in the syslog messages file.
*SYSLOG_RHOST
Default = null
Specify a remote IP address to send syslog messages via a UDP network connection. Specify what port to use when sending syslog messages to remote UDP network connection. Log syslog messages remotely. Log user log messages locally (this option does not affect OS or root generated messages).
*SYSLOG_RPORT
Default = 5140
*SYSLOG_RLOG *SYSLOG_USRLOCAL
Default = TRUE Default = FALSE
22
Table 5 Variable Name

*VPAY
Values
1
Definition
If * VPAY exist and there is no application loaded, the system will attempt to contact the Visual Payments host for an application download. IP address of Visual Payments server. Connection Port address on Visual Payments server. Connection Port address on the Mx800 series terminal.
*VPAYSERVERADDRESS *VPAYSERVERPORT *VPDOWNPORT
xxx.xxx.xxx.xxx xxxxx xxxxx
23
F ILE S YSTEMS getSysctl()
getSysctl()
Reads the value of the kernel parameters in the /proc/sys directory using the sysctl utility.
Prototype
int result = getSysctl(char *var, char *value, int vlen);
Parameters
var Points to a null terminated string containing the kernel parameter to reference. Maximum length of the label is 128 bytes and will automatically be converted to lower case before searching for its value. Points to an area where the value of the kernel parameter will be copied. Maximum length is 128 bytes. Value will be null terminated. 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.
value
vlen
Return Values
>0 =0 <0 Len of value Entry not found. An error has occurred: EINVAL = Invalid parameter ENOENT = Invalid kernel parameter ENOBUFS = Internal message error
24
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 <0 Success An error has occurred: EINVAL = Invalid parameter ENOENT = Invalid kernel parameter ENOBUFS = Internal message error
25
F ILE S YSTEMS Syslog Messages
Syslog Messages
The Mx800 series of terminals supports logging messages generated by syslog() method calls. These messages are stored in chronological order in the file system /mnt/sram/. This file system is located in the battery-backed SRAM. There are up to four file messages that are dependent on the number of messages that have been logged. When this file reaches the maximum size, the files are rotated such that message is renamed to messages.1 and a new messages file is started. If messages.1 already exists, it is renamed to messages.2, if messages.2 already exists, it is renamed to messages.3, and if messages.3 exists, it is removed.
NOTE
Log messages are maintained across boots and power down/up operations.
Remote Logging The syslog daemon on the terminal supports sending the logged messages to a
remote UDP network connection. To enable this feature, there are several config.usr1 parameters that are required to be set, once the terminal is rebooted, remote logging will be enabled. The config.usr1 parameters are described in Chapter 5. The two parameters that must be specified are SYSLOG_RHOST and SYSLOG_LOG.
Downloading
The Mx800 series will support the following methods for downloading files:
1 Zontalk Included for compatibility only. The Linux concepts of file ownership,
privileges, and directory paths will not be fully supported under Zontalk. Files must be converted to .TAR format in order to preserve path and user information. Zontalk will be implemented in system mode as well as be available through a shared library. If files are downloaded without being converted to .tar format, then files with the .SH, .EXE, and .OUT extensions will automatically have their permissions set to executable. All other files will be read/write for the owner only. If a file that is converted to .TAR format is downloaded, permissions will be set according to what they were at the time the file was archived. After an expansion of a .TAR file is completed, the ownership for all files contained within the users home directory will be set to that users ownership, unless they are already owned by root. Filenames of downloaded files are currently limited to 60 characters or less.
2 NFS The Network File System allows for seamless remote access to files.
The Mx800 series of terminals will act as a client and connect to an NFS server. The server will control file access privileges. The files that the Mx800 series of terminals may access on the NFS server appear to be local, thus allowing then to be executed, copied, etc. Windows PCs will require an NFS server to be installed.
26
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 VeriFones 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.
27
F ILE S YSTEMS File Authentication and Certificates
If a .TAR file contains a special file named config.usrx (where x is 1 to 8) the system will read the downloaded config.usrx file and update the users configuration. This feature allows configuration variables to be added/deleted or changed without using Zontalk, or ECR protocol that has built in support for configuration variables. The content of the special config.usrx file is simple ASCII with a <CR> character at the end of each line. An equal = character is used to separate a variable from its value. To delete an entry, enter the variable with an equal = character. An example config.usr1 file: *DHCP= *GO=screen-demo.exe In the example, the *DHCP variable will be deleted and *GO will be set/ changed.
NOTE
Including the variable *usr1pwd, config.usr1 will set the System Mode / login password for usr1 to its value. For example: *usr1pwd=123456 will set usr1 password to 123456. The Mx800 series implements VeriFones VeriShield File Authentication module. All executable code must be authenticated prior to running. File authentication authority is split in to two branches. One branch is owned by VeriFone and encompasses Kernel / OS code. This includes driver modules. The second branch is owned by the customer/VAR and encompasses applications. All directories and files with root ownership are considered Kernel/OS owned and must be authenticated by OS signing authority. Applications will reside in user space directories and will require application signing authority. Application authentication is performed each time an application is executed. The system scans the directory where the application resides for a .p7s file that contains the name of the application. This means that the .p7s and the application do not need to have the same name. Remember that Linux is case sensitive and it is important that the file named in the .p7s have the same case as the application. The system expects certificate files to be placed in a directory named: crt under the base path for the user. For usr1, the path would be /home/usr1/crt. If a file fails authentication, the system automatically scans the crt directory for a certificate that may need to be installed.
File Authentication and Certificates
Package Management
The terminal supports the ability to group or package a collection of files as a single package/file that can be downloaded and installed into the terminal. This package management is called iPKG (The Itsy Package Management System). iPKG is a very lightweight package management system that allows for dynamic installation/removal of packages on a running system.
28
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> remove <pkg> list_installed Install package <file.ipk> Remove package <pkg> 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.
29
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 <[email protected]> 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 [az0-9.+-]\+
30
Version
should have at least one digit and should match "[a-zA-Z0-9.+]*". Version may also contain an optional trailing revision matching "-fam[09]\+". This revision should be incremented each time the package changes but the version does not, (i.e. a packaging tweak). It may be reset, (or simply omitted), each time the version is incremented. should specify the architecture for which the package is compiled. Valid values currently include: arm, i386, m68k, ns32k, sh3, sparc, vax, and all. should be the name and email address of the person responsible for maintaining the package, (not necessarily the author of the program). 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. " ." should be one of: required, standard, important, optional, or extra. Most programs should use optional. can be one of the following: admin, base, comm, editors, extras, graphics, libs, misc, net, text, web, x11. 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.
Architecture
Maintainer Description
Priority Section Depends
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).
31
32
CHAPTER 4
Device Drivers
Device Drivers for the Mx800 series of Terminals
The following device drivers are supported by Mx800 series of terminals:
Ethernet Port Real Time Clock 4 Serial Ports Standard Linux support as /dev/eth0 Standard Linux support as /dev/rtc Standard Linux support as /dev/ttySAC0, ttySAC1, ttySAC2
Note:
Requires Serial Port handshake enhancement COM3 will be supported by the Wrenchman module, device name /dev/ttyWR0
COM1 = /dev/ttySAC0 COM2 = /dev/ttySAC1 COM3 = /dev/ttyWR0 COM4 = /dev/ttySAC2
USB
Standard Linux support as /proc/bus/usb USB device serial port is defined as: COM5 = /dev/ttygser
Display Sound
Standard Linux support as /dev/fb0 Standard Linux support as /dev/dsp
Magnetic Stripe Reader IPP Delta Touch panel
VeriFone unique device /dev/msr VeriFone unique device /dev/ipp VeriFone unique device /dev/delta 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.
33
D EVICE D RIVERS Magnetic Stripe Reader
Magnetic Stripe Reader
All Mx800 series of terminals include a triple track magnetic stripe reader. Accessing the Magnetic Stripe Reader requires linking with the shared library: libvfimsr.so. The header file msrDevice.h is used by the application to access the library. Example Using the Card Reader
// This program reads the card reader device and prints the result to STDOUT main() { int result; charbuffer[200];
result = msrOpen( O_RDONLY, NULL );
while(1) /* infinite loop */ { memset(buffer, 0, sizeof(buffer)); int = msrRead(buffer,sizeof(buffer)); /* wait for input from card reader */ printf("msrRead returned %d bytes of data", result); } }
34
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 O_RDWR O_NONBLOCK Read Only Read and Write 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 <0 Magnetic Stripe Reader is open and ready Error
35
D EVICE D RIVERS msrRead
msrRead
Read the decoded and formatted MSR data. If the device is not opened with the O_NONBLOCK flag set, this call will be blocked until data is available.
Prototype
int bytes_read = msrRead(char *buffer, int size);
Parameters
buffer size Pointer to data area 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 s1 d1 c2 s2 d2 c3 s3 d3 a one byte size of c1+s1+d1 a one byte status of reading track 1 any data read in (might not exist) a one byte size of c2+s2+d2 a one byte status of reading track 2 any data read in (might not exist) a one byte size of c3+s3+d3 a one byte status of reading track 3 any data read in (might not exist)
The data includes the Start Sentinel, End Sentinel, and the LRC characters. They were not included in the Omni 7xxx.
36
D EVICE D RIVERS msrRead
The status byte (s1,s2,s3) can have one of the following values:
0 1 2 3 4 5 NOTE valid data no data missing start sentinel or insufficient data missing end sentinel or excessive data missing BCC or BCC error parity error
The returned error status may not reflect the exact cause because the algorithm tries to decode data in both direction streams. An error in one direction stream may not produce the same error as in the other. The decode algorithm searches the entire data stream for the start sentinel.
Return Values
>=0 <0 Total number of bytes read Error
37
D EVICE D RIVERS msrWrite
msrWrite
This operation transfers data from an application buffer into the device driver's buffer. The data is used for the next read operation.
Prototype
int bytes_written = msrWrite(char *buffer, int size);
Parameters
buffer size Pointer to data area 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 >0 NOTE No data written Number of bytes written
This call is placed to support test program development and debugging modes.
38
D EVICE D RIVERS msrMagneticCardPresent
msrMagneticCardPresent
Prototype
int result = msrMagneticCardPresent(void)
Return Values
0 1 2 No data available Data available Magnetic field present
39
D EVICE D RIVERS msrRaw
msrRaw
Allows an application to retrieve the raw magnetic stripe data and perform a custom decode.
Prototype
int result = msrRaw(MSR_DATA * msr);
Parameters
The MSR_DATA structure is as follows:
typedef struct { unsigned char ucStatus; // status of track unsigned char ucCount; // size in bytes of track data char *cpData; // pointer to track data } MSR_TRACK_DATA;
typedef struct { MSR_TRACK_DATA stTrack1; MSR_TRACK_DATA stTrack2; MSR_TRACK_DATA stTrack3; } MSR_DATA;
Return Values
0 -1 Data available No data available
40
D EVICE D RIVERS msrStructured
msrStructured
Allows an application to retrieve the decoded magnetic stripe data in a structure.
Prototype
int result = msrStructured(MSR_DATA * msr);
Parameters
The MSR_DATA structure is as follows:
typedef struct { unsigned char ucStatus; // status of track unsigned char ucCount; // size in bytes of track data char *cpData; // pointer to track data } MSR_TRACK_DATA;
typedef struct { MSR_TRACK_DATA stTrack1; MSR_TRACK_DATA stTrack2; MSR_TRACK_DATA stTrack3; } MSR_DATA;
Return Values
0 -1 Data available No data available
41
D EVICE D RIVERS msrEnableLicenseDecode
msrEnableLicenseDecode
Enables the decoding of California Drivers License and American Association of Motor Vehicle Administrators (AAMVA) Drivers License.
NOTE
By default, California Drivers Licenses will not be decoded. This is for compatibility with existing terminals and tests.
Prototype
int msrEnableLicenseDecode(void);
42
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);
43
D EVICE D RIVERS msrVersion()
msrVersion()
Prototype
int result = msrVersion(char*version)
Parameters
version Pointer to read in the MSR library version, in the form: xx.yy.zz
Return Values
0 <0 Successful execution Error
44
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
45
D EVICE D RIVERS Internal PIN Pad
Internal PIN Pad
In the Omni 7xxx platform, the IPP7 was implemented in hardware. In the Mx800 series of terminals, the IPP chip is emulated in software. The application interface is similar to the one in the Vx family of terminals. Applications access the IPP through a virtual communication port. The Mx800 series terminal IPP emulation contains most IPP7/IPP8 features, including 3DES master/session, multiple DUKPT, and MAC processing. It does not support the Spain, Interac, or Secure Messaging modes. For information on the supported IPP packets, refer to Appendix A. All IPP functions are defined in the header file svcsec.h. Applications must link with the libvfisec.so library by using -lvfisec.
46
D EVICE D RIVERS int ippOpen(void)
int ippOpen(void)
ippOpen() takes ownership of the IPP and clears the internal IPP FIFO. This function always returns 0.
Return Values
0 Successful execution
47
D EVICE D RIVERS int ippClose(void)
int ippClose(void)
ippClose() releases ownership of the IPP. All unread data is lost. This function always returns 0.
Return Values
48
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 size Pointer to the data area Maximum number of bytes to read
Return Values
>0 0 EBADF Number of bytes returned in buffer No data to read 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() iPS_CancelPIN() in IPP PIN Entry in VSS PIN Entry
After expiration of the OS timeout,

in IPP PIN Entry in VSS PIN Entry the IPP sends an <EOT> (0x04) character 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).
49
D EVICE D RIVERS int ippWrite(char *buffer, int size)
int ippWrite(char *buffer, int size)

ippWrite() transfers a single complete IPP packet or a single character from the buffer into the IPP. Incomplete, incorrectly framed packets, overly large, or multiple packets in a single write are rejected. The valid start-of-packet characters are STX and SI. The valid end-of-packet characters are ETX and SO. The only single characters accepted are ACK, NAK, and EOT.
Parameters
buffer size Pointer to the data area Maximum number of bytes to write
Return Values
=size -EBADF -EACCES The packet was transferred to the IPP. The task does not own the IPP. Too may PIN sessions requested during a short period of time. Try again in a few seconds. See note below. 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.
-EINVAL
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.
50
D EVICE D RIVERS SetSecurePINDisplayParameters()
SetSecurePINDisplayParameters()
setSecurePINDisplayParameters() sets the hot spot table and registers the callback function for the upcoming PIN session. This function must be called each time prior to requesting a PIN session either through an IPP packet (Z60, Z63 or Z69) or through a VeriShield Security Script API (iPS_RequestPINEntry()).
Prototype
void setSecurePINDisplayParameters(struct touch_hs_s *hotspot_table, void *callback);
The touch_hs_s structure is as follows:

struct touch_hotspot_info { unsigned short unsigned short unsigned short unsigned short x1; /* starting x of hotspot */ y1; /* starting y of hotspot */ x2; /* ending x of hotspot */ 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.
51
For PIN entry, the following hotspots must be defined.

CODE Key
=============================== 0x30 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x0D 0 1 2 3 4 5 6 7 8 9 ENTER
Optional keys are:

CODE Key
======================================================= 0x30 0x31 0x32 0x33 0x34 NOTE BACKSPACE CLEAR OTHER1 - Defines OTHER key #1 OTHER2 - Defines OTHER key #2 CANCEL - End PIN Session - 0x?2 - 0x?3 - 0x75 - 0x76 - 0x70
The order in which the hotspot entries are defined is not important.
struct touch_hs_s { short struct }; num_hotspots; /* the number of active hotspots */ touch_hotspot_info touch_spot[MAX_NUM_HOTSPOTS];
52
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
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. 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. CLEAR key was pressed. All PIN digits have been removed from the internal PIN buffer. Application should replace all <echo> characters with <default> characters. 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. 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. Play normal sound Play "error" sound. This is sent when:
BACKSPACE or CLEAR is pressed when there is no PIN digit
Action
0x?2
0x?3
0x?5
0x?6
Upper nibble: 0x7? 0xF?
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*/
53
D EVICE D RIVERS int ippPinEntryStatus(int *count, int *lastNonNumericKey)
int ippPinEntryStatus(int *count, int *lastNonNumericKey)

ippPinEntryStatus() returns the PIN entry status, the number of PIN digits currently in the internal PIN buffer and the code of the last non-numeric key pressed.
count Pointer to an integer that will receive the current count of PIN digits in the internal buffer. Pointer to an integer that will receive the code of the last non-numeric key pressed. It will receive 0 if no new nonnumeric has been pressed since last call.
lastNonNumericKey
Return Values
1 0 <0 PIN entry in progress No PIN entry in progress Error -EBADF The task does not own the IPP
54
D EVICE D RIVERS ippTerminatePinEntry()
ippTerminatePinEntry()
Ends the PIN session, for example, for a time-out.
Prototype
int ippTerminatePinEntry(void)
Return Values
0 <0 successful Error -EBADF The task does not own the IPP
55
D EVICE D RIVERS IPP Differences
IPP Differences
<SI>0103 PROM Checksum
The value of the checksum does not match IPP7 since it is based on the Mx800 series terminal code. 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>0108 IPP ROM Version Number
<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. 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. 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. IPP7 supports one DUKPT engine. The Mx800 series terminal IPP emulation supports three DUKPT engine the same way the IPP8 does.
<SI>17 Set IPP7 Key Management Mode
<SI>02 Set master key
Multiple DUKPT
56
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 Programmers 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 Security Scripts APIs
The Mx800 series of terminals support the VeriShield Security Scripts concept as implemented in the SC 5000 PINpad and Verix V family of terminals. Existing scripts will run on the Mx800 series terminal platform without requiring any modifications. All VSS-related functions listed below are defined in the header file svcsec.h. Applications must link with the libvfisec.so library by using lvfisec. Refer to the document VeriShield Security Scripts, VDN 21883 for detailed information on how to implement a security script. In its default configuration, the unit supports two key management schemes through the IPP emulation: DUKPT and Master/Session. Those two schemes should meet the needs of most of the customers and since they are hard coded, no customization of the security module is required. For customers who need more flexibility, the VeriShield Security Script feature provides support for:
different key management schemes, different PIN block formats such as PVV, CVV, IBM3624, different encryption algorithms such as triple-DES, AES, RSA.
All the information is written in a script file (ASCII) using a .VSS extension. This script is processed by a PC tool and converted into a downloadable file (*.VSO). The download is protected by the PEDguard File Authentication (FA) module. Therefore, the VeriShield Security Script file will have to be downloaded along with its signature file generated with the VeriShield File Signature Tool.
57
D EVICE D RIVERS VeriShield Security Scripts APIs
Up to eight VeriShield Security Scripts can coexist in the unit at a same time. Each script defines its independent key space and defines whether or not those keys can be loaded using the generic key loading functions (iPS_LoadMasterClearKey() and iPS_LoadMasterEncKey()). The VSS Key Loading Key (VSS_KLK) is a double-length key. It is loaded in the clear, but can also be loaded encrypted under its previous value. Since there is no default value in the firmware for the VSS_KLK, the first time it must be loaded in the clear. In that case, other keys in the unit will be erased, so it must be loaded before all other keys. This must be done in a secure environment before deployment. The security scripts master keys can be loaded in the clear or encrypted under VSS_KLK. Loading additional keys without erasing the keys previously loaded must be done in encrypted form and therefore requires the knowledge of VSS_KLK. Each script defines its own set of keys and also defines if the keys may be loaded with those generic key-loading functions. Some scripts may disallow their use and implement custom macro commands for key loading.
58
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 DEL_VSS0 System key (VSS_KLK) Keys associated to VeriShield Security Script loaded in slot #0 Keys associated to VeriShield Security Script loaded in slot #1 Keys associated to VeriShield Security Script loaded in slot #2 Keys associated to VeriShield Security Script loaded in slot #3 Keys associated to VeriShield Security Script loaded in slot #4 Keys associated to VeriShield Security Script loaded in slot #5 Delete all keys in the unit.
DEL_VSS1
DEL_VSS2
DEL_VSS3
DEL_VSS4
DEL_VSS5
DEL_ALL
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
59
D EVICE D RIVERS iPS_LoadSysClearKey()
iPS_LoadSysClearKey()
This function loads the VSS_KLK (i.e. system keys). The values are presented in the clear. Before writing the new value of the key, all other keys in the terminal are erased. This function should be exclusively used in a secure environment.
Prototype
int iPS_LoadSysClearKey(unsigned char ucKeyID, unsigned char * pucINKeyValue)
Parameters
ucKeyID The key identifier. 0x00 VSS_KLK (16 bytes)
pucINKeyValue
16-byte buffer containing the clear-text key
Return Values
0 E_KM_NO_KEY_LOADED E_KM_KEY_INTEGRITY_ERROR E_KM_SYSTEM_ERROR Successful execution VSS_KLK is absent. No encrypted loading possible VSS_KLK is corrupted
60
D EVICE D RIVERS iPS_LoadSysEncKey()
iPS_LoadSysEncKey()
This function loads the system keys. The new values must be presented encrypted under the current value of VSS_KLK. Contrary to the clear text loading, this encrypted loading does not erase all other secrets in the unit. An error code will be returned if the VSS_KLK is not present.
Prototype
int iPS_LoadSysEncKey(unsigned char ucKeyID, unsigned char * pucINKeyValue)
Parameters
ucKeyID The key identifier. 0x00 VSS_KLK (16 bytes)
pucINKeyValue
16-byte buffer containing the clear-text key
Return Values
0 E_KM_NO_KEY_LOADED E_KM_KEY_INTEGRITY_ERROR E_KM_SYSTEM_ERROR Successful execution VSS_KLK is absent. No encrypted loading possible VSS_KLK is corrupted
61
D EVICE D RIVERS iPS_LoadMasterClearKey()
iPS_LoadMasterClearKey()
This function loads the master key of the security script. The values are sent in the clear, but must be all loaded in a same session. Before loading the first key after a power cycle, all keys previously loaded (including the system keys) are erased. This means that loading additional keys in a different session must be done in encrypted form. This function can be used to load the keys defined by the Security Scripts if the option has not been disabled in the script. This function should be exclusively used in a secure environment.
Prototype
int iPS_LoadMasterClearKey(unsigned char ucKeySetID,unsigned char ucKeyID, unsigned char * pucINKeyValue)
Parameters
ucKeyID The key set identifier. 00 01 ... 07 ucKeyID Key set defined in VeriShield Security Script #7 Key set defined in VeriShield Security Script #0 Key set defined in VeriShield Security Script #1
The key identifier. Master key number / Key index in the selected set
pucINKeyValue
pointer to the 8-byte buffer containing the cleartext value Master Key.
Return Values
0 E_KM_OUT_OF_RANGE E_KM_FEATURE_DISABLED E_KM_SYSTEM_ERROR Successful execution ucKeySetID or ucKeyID is out of range or script is not loaded. Master/Session support disabled by a script
62
D EVICE D RIVERS iPS_LoadMasterEncKey()
iPS_LoadMasterEncKey()
This function loads the security scripts master keys without deleting the keys already loaded. The new values must be presented encrypted under the current value of VSS_KLK. This function can be used to load the keys defined by the Security Scripts if the option has not been disabled in the script. An error code will be returned if the VSS_KLK is not present.
Prototype
int iPS_LoadMasterEncKey(unsigned char ucKeySetID, unsigned char ucKeyID, unsigned char * pucINKeyValue)
Parameters
ucKeyID The key set identifier. 00 01 ... 07 ucKeyID Key set defined in VeriShield Security Script #7 Key set defined in VeriShield Security Script #0 Key set defined in VeriShield Security Script #1
pucINKeyValue
pointer to the 8-byte buffer containing the cleartext value Master Key.
Return Values
0 E_KM_NO_KEY_LOADED E_KM_KEY_INTEGRITY_ERROR E_KM_OUT_OF_RANGE E_KM_FEATURE_DISABLED E_KM_SYSTEM_ERROR Successful execution VSS_KLK is absent. No encrypted loading possible VSS_KLK is corrupted ucKeySetID or ucKeyID is out of range or script is not loaded. Master/Session support disabled by a script
63
D EVICE D RIVERS iPS_CheckMasterKey()
iPS_CheckMasterKey()
This function indicates whether a key is present in the specified location. The Key Verification Code (KVC) argument is irrelevant in Mx800 series of terminals because this function is used only for security script keys. The key may be part of a double or triple length DES key, so for security reasons we cannot return the KVC of a portion of the key.
Prototype
int iPS_CheckMasterKey(unsigned char ucKeySetID, unsigned char ucKeyID, unsigned char * pucINKVC)
Parameters
ucKeyID The key set identifier. 00 01 ... 07 08 09 ucKeyID Key set defined in VeriShield Security Script #7 PIN Master Key (Master/Session) MAC Master Key (Master/Session) Key set defined in VeriShield Security Script #0 Key set defined in VeriShield Security Script #1
pucINKVC
not used
Return Values
0 E_KM_NO_KEY_LOADED E_KM_KEY_INTEGRITY_ERROR E_KM_OUT_OF_RANGE E_KM_SYSTEM_ERROR Successful execution The key is not loaded The key is corrupted ucKeySetID or ucKeyID is out of range
64
SetSecurePINDisplayParameters()
setSecurePINDisplayParameters() sets the hot spot table and registers the callback function for the upcoming PIN session. This function must be called each time prior to requesting a PIN session either through an IPP packet (Z60, Z63 or Z69) or through a VeriShield Security Script API (iPS_RequestPINEntry()). See SetSecurePINDisplayParameters().
Prototype
void setSecurePINDisplayParameters(struct touch_hs_s *hotspot_table, void *callback);
65
D EVICE D RIVERS iPS_SetPINParameter()
iPS_SetPINParameter()
This function configures several parameters for the upcoming VSS PIN session. This function has not effect on IPP PIN sessions.
Prototype
int iPS_SetPINParameter( PINPARAMETER * psKeypadSetup)
Parameters
psKeypadSetup typedef struct { unsigned char ucMin, unsigned char ucMax, unsigned char ucEchoChar, unsigned char ucDefChar, unsigned char ucOption, } PINPARAMETER;
where:
ucMin ucMax Minimum number of PIN digits. It must be in the range [4..12]. Maximum number of PIN digits. It must be at least equal to Min but not greater than 12. Not used on Mx800 series. The characters echoing PIN digits are displayed by the SetSecurePINDisplayParameters()s callback function. Not used on Mx800 series of terminals. The default field fill characters are displayed using the SetSecurePINDisplayParameters() callback function. =1 turns Auto Enter feature O =1 accepts NO PIN entry (pressing ENTER before any digit). RFU - Must be 0 =1 makes the <CLEAR> key behave like a backspace key. Only one digit is deleted instead of all the digits entered so far. =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. RFU - Must be 0
ucEchoChar
ucDefChar
ucOption.bit0 ucOption.bit1 ucOption.bit2 ucOption.bit3
ucOption.bit4
ucOption.bit5..7
66
D EVICE D RIVERS iPS_SetPINParameter()
Return Values
0 E_KM_OUT_OF_RANGE E_KM_SYSTEM_ERROR Successful execution At least one of the parameters is out of range
67
D EVICE D RIVERS iPS_SelectPINAlgo()
iPS_SelectPINAlgo()
This function selects the PIN algorithm to be used during the next VSS PIN session. The PIN algorithm cannot be changed during a PIN session In the Mx800 series of terminals, the only supported mode is 0Bh for use with VeriShield Security Scripts. In this mode, the PIN will be saved internally and will be retrieved by a Security Script command for post-processing.
Prototype
int iPS_SelectPINAlgo(unsigned char ucPinFormat)
Parameters
ucPinFormat 0Bh Store the PIN internally for post-processing by a VeriShield Security Script command.
All other modes are not supported in the Mx800 series of terminals.
Return Values
0 E_KM_OUT_OF_RANGE E_KM_BAD_SEQUENCE E_KM_SYSTEM_ERROR Successful execution ucPinFormat is out of range or unsupported PIN algorithm cannot be changed during a PIN session
68
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. RFU this parameter is ignored in Mx800 series of terminals.
pucINPANData
Return Values
0 E_KM_ACCESS_DENIED Successful execution You requested too many PIN sessions in a short period of time. Try again in few seconds. See Note on the PIN session timeout. A PIN session is already started
E_KM_BAD_SEQUENCE E_KM_SYSTEM_ERROR
69
D EVICE D RIVERS iPS_GetPINResponse()
iPS_GetPINResponse()
This function checks the status of the PIN session. It will typically be used by the application in a loop to poll the system until the PIN session ends. The information returned by this function during the PIN session can be used in conjunction with a timer to implement an inter-character timeout as required in certain countries The functions returns the number of PIN digits entered and the last non-numeric pressed.
Prototype
int ippGetPINResponse (int * piStatus, PINRESULT * pOUTData)
Parameters
piStatus OK (0x00) 0x01 0x02 0x05 0x06 0x0A Done. Data contains the result of the comparison/ encryption. Unit is idle Collecting PIN Aborted by user: The <CANCEL> key has been pressed. NO PIN entered (Only if this option is turned on) 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(). The PIN session timed out. See Note on the PIN session timeout.
0x0C
70
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 ->nbPinDigits pOUTData ->encPinBlock 0x01 Unit is idle
Number of PIN digits entered (PIN length). contains no relevant information.
pOUTData ->encPinBlock 0x02: Collecting PIN
contains no relevant information.
pOUTData ->nbPinDigits pOUTData ->encPinBlock
Number of PIN digits entered so far. The first byte of the buffer contains the value of the last non-numeric key pressed. Values can be:
0x00: No non-numeric key
has been pressed since the last call to iPS_GetPINResponse().

0x0D: <ENTER> key 0x0D: <CLEAR> key 0xF9: The user attempted to
enter one more PIN digit than the maximum number allowed (ucMax)
Any other non-numeric key
value defined in the hotspot table.
71
0x05: or 0x0A:
Aborted by user
pOUTData ->nbPinDigits pOUTData ->encPinBlock
0 The first byte of the buffer 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
0 E_KM_SYSTEM_ERROR Successful execution
72
D EVICE D RIVERS iPS_CancelPIN()
iPS_CancelPIN()
This function cancels the PIN processing.
Prototype
int iPS_CancelPIN(void)
Return Values
0 E_KM_SYSTEM_ERROR Successful execution
73
D EVICE D RIVERS iPS_InstallScript()
iPS_InstallScript()
This function authenticates and installs VeriShield Security Script files in the system. The function attempts to authenticate all .VSO files in the vss/ subdirectory in the current users 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 users 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
74
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 pucINName Script number. Range [0..7] The pointer to the application buffer where the 8-character name of the VeriShield Security Script value will be transferred.
Return Values
0 E_VS_SCRIPT_NOT_LOADED Successful execution This script is not installed or not accessible from the current application group.
75
D EVICE D RIVERS iPS_UninstallScript()
iPS_UninstallScript()
This function uninstalls the specified VeriShield Security Script from the unit. The associated keys are deleted. The script file remains in the file system and can be installed again later on.
Prototype
int ippGetScriptStatus(unsigned char ucScriptNumber)
Parameters.
ucScriptNumber Script number. Range [0..7]
Return Values
0 E_VS_SCRIPT_NOT_LOADED E_VS_SYSTEM_ERROR Successful execution This script is not installed, not authenticated, or not accessible from the current application group.
76
D EVICE D RIVERS iPS_ExecuteScript()
iPS_ExecuteScript()
This function spawns the execution of a given macro from a given loaded VeriShield Security Script.
Prototype
int iPS_ExecuteScript(unsigned char ucScriptNumber, unsigned char ucMacroID, unsigned short usINDataSize, unsigmed char * pucINData unsigned short usMaximumOUTDataSize, unsigned short *pusOUTDataSize, unsigmed char * pucOUTData)
Parameters.
ucScriptNumber unsigned char ucMacroID usINDataSize pucINData usMaximumOUTDataSize Script number. Range [0..7] Number of the macro function to be executed. The size of the input data (in bytes). The pointer to the buffer containing the input data. The maximum size of the output data. This typically will be the size of the output buffer. Pointer to number of bytes returned by the macro in the output buffer. 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.
pusOUTDataSize
pucOUTData
77
D EVICE D RIVERS iPS_ExecuteScript()
Return Values
0 Value in the range [0...255] Successful execution 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. This script is not loaded, not authenticated, or not accessible from the current application group. This macro does not exist in this script. 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. Bad sequence of macro (see chaining mechanism in VDN 25883).
E_VS_SCRIPT_NOT_LOADED E_VS_MACRO_NOT_EXIST E_VS_BAD_LENGTH
E_VS_BAD_CHAINING E_VS_SYSTEM_ERROR
78
D EVICE D RIVERS pcPS_GetVSSVersion()
pcPS_GetVSSVersion()
This function returns the version of the VeriShield Security Script interpreter.
Prototype
char* pcPS_GetVSSVersion (void)
Parameters.
ucScriptNumbe r Script number. Range [0..7]
Return Values
It returns a char pointer to the following NULL terminated string: "PSVSSvX.Y"
X Y Major version Minor version
79
D EVICE D RIVERS Security Services APIs
Security Services APIs
The security device (/DEV/IPP) need not be opened to use the functions listed below. All security services functions listed below are defined in the header file svcsec.h. Applications must link with the libvfisec.so library by using lvfisec.
80
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 buffer count File handle Pointer to the buffer holding the input data Number of byes to write
Return Values
0 1 <1 Successful execution File Error, errno is set accordingly. System Error
81
D EVICE D RIVERS cryptoRead()
cryptoRead()
crypto_read reads a maximum of count bytes of encrypted data from the open file associated with handle, decrypts the data and stores the result in buffer. It returns the number of bytes actually read, which may be less than count if fewer bytes are available.
Prototype
int cryptoRead (int handle, char *buffer, int count)
Parameters
handle buffer count File handle Pointer to the buffer holding the input data Maximum number of byes to write
Return Values
0 1 <1 Successful execution File Error, errno is set accordingly. System Error
82
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 mod Pointer to the buffer holding the input data 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 its the case, the function returns an error.
count exp
Length of the modulus and input data in bytes. Minimum 3. Max 256. 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 <0 Successful execution Error - Invalid parameter
83
D EVICE D RIVERS SHA1()
SHA1()
This function performs a SHA-1 computation as described in FIPS PUB 180-2. It returns a 20-byte message digest. Due to the underlying messaging interface, it can process a maximum of 1024 bytes per call.
Prototype
int SHA1 (unsigned char * int option, unsigned char * input_buffer, unsigned long nb, unsigned char * sha20)
Parameters
option SHA1INIT First call. The SHA-1 engine is initialized before processing the data. No digest is returned. Intermediate call. It feeds the SHA-1 engine more data. No digest is returned. Final call. The 20-byte digest is returned after the data is processed. One-step operation combining all the options above.
SHA1BUFF
SHA1TERM
SHA1ALL
input_buffer nb sha20
Pointer to the input buffer holding the message to be processed. Number of bytes in the buffer. Maximum value is 1024. Pointer to the 20-byte buffer where the message digest will be transferred.
Return Values
84
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) DESX1KD(03h) DESX2KE(04h) DESX2KD(05h) DESX3KE(06h) DESX3KD(07h) DESE(08h) DESD(09h) TDES2KE(0Ch) TDES2KD(0Dh) TDES3KE(0Eh) TDES3KD(0Fh) pucDeaKey8N pucInputData pucOutputDat a DEAX encryption with single-length key DEAX encryption with single-length key DEAX encryption with double-length key DEAX encryption with double-length key DEAX encryption with triple-length key DEAX encryption with triple-length key DEA encryption with single-length key DEA encryption with single-length key TDEA encryption with double-length key TDEA encryption with double-length key TDEA encryption with triple-length key TDEA encryption with triple-length key
Pointer to 8N-byte key block (N=1, 2 or 3) Pointer to 8-byte input block Pointer to 8-byte output block
Return Values
0 Less than 0 Successful execution Error
85
D EVICE D RIVERS AES()
AES()
This function performs AES computations on 128-bit data block. The operation type and key length are specified using the parameter ucAesOption.
Prototype
int AES (unsigned char ucAesOption, unsigned char *pucAesKey8N, unsigned char *pucInputData, unsigned char *pucOutputData)
Parameters
ucAesOption Algorithm AES128E (04h) AES128D (05h) AES192E (06h) AES192D (07h) AES256E (08h) AES256D (09h) AES encryption using a 128-bit key AES decryption using a 128-bit key AES encryption using a 192-bit key AES decryption using a 192-bit key AES encryption using a 256-bit key AES decryption using a 256-bit key
pucAesKey8N pucInputData pucOutputData
Pointer to 8N-byte key block (N=1, 2 or 3) Pointer to 16-byte input block Pointer to 16-byte output block
Return Values
86
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
87
D EVICE D RIVERS isAttacked()
isAttacked()
This function indicates if an attack occurred, causing the loss of the transaction keys and/or encrypted files. It returns 0 if no attack occurred since the last key loading or file encryption, otherwise, a value of 1 is returned. It also returns 1 if the unit has never been loaded with a key and no encrypted file has been written.
Prototype
int isAttacked (void)
Return Values
0 1 No attack has occurred since keys have been loaded. An attack has occurred. Keys and encrypted file have been lost.
88
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
89
D EVICE D RIVERS authFile()
authFile()
This function checks if the specified file is authenticated. Internally, the function performs two attempts to authenticate the file. If after the first attempt, the file is not authenticated, the system searches for .CRT files in the crt/ subdirectory in the current user home directory. It tries to add each certificate file to the system certificate tree. Then a second attempt to authenticate the specified file is performed.
Prototype
int authFile(const char *filename)
Parameters
filename Pointer to the name of file to authenticate.
Return Values
0 <0 File is authenticated File failed authentication
90
D EVICE D RIVERS loadOSFiles()
loadOSFiles()
This function attempts to authenticate all files in the os/ subdirectory in the current user home directory. Files must have been signed with an OS signer certificate. Internally the function performs two attempts to authenticate each file. If after the first attempt the file is not authenticated, the system searches for .CRT files in the crt/ subdirectory in the current user home directory. It tries to add each certificate file to the system certificate tree. Then a second attempt to authenticate the file is performed. Upon successful authentication, the file and its signature file are moved into the system directory according to its location in the user os/ subdirectory. For instance, the file /home/usr1/os/lib/modules/DELTA.SCM and its signature file /home/usr1/os/lib/modules/DELTA.SCM.p7s will be moved to system directory /lib/modules/.
Prototype
int loadOSFiles(void)
Return Values
91
D EVICE D RIVERS Delta Smartcard Interface / CardSlot
Delta Smartcard Interface / CardSlot Serial Ports and Protocols
The VeriFone Delta Smartcard module will be used to interface the ARM CPU to the customer smartcard and SAMs. For more details on Smartcard APIs, refer to the Mx CardSlot Library Programmers Guide, VDN 23992. The Linux operating system is divided into two spaces, the kernel space and the user space. The kernel space is used for device drivers that must interact closely with the hardware. This interaction includes handling interrupts, precise timing, and hardware interfaces that require bit flipping. The user space code is easier to debug, maintain, and provides superior protection from bugs. For these reasons, the 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
Packet Mode Protocol
Feature C Protocol (VISA layer)
LINUX KERNEL Character Device UART Driver stty1, stty2 Wrenchman Coprocessor Driver (SPI) stty3
HARDWARE
Samsung ARM9 CPU
Wrenchman Silicon Labs Communication Coprocessor
COM1 RTS/CTS, DCD
COM2 RTS/CTS, DTR, DCD
COM3 RTS/CTS
Figure 1
LINUX operating system structure
92
D EVICE D RIVERS Serial Communication Control Structure
Serial Communication Control Structure
The following are the structures defined for configuring serial ports on the Mx800 series of terminals. They contain all the necessary elements for defining the ports into the different modes that each of them support.
typedef struct{ short status; short comm_handle; short visa_sel; /* 0 - visa not selected, 1 - visa selected */ int port; void (*pEcrReceive) (void); /* ecr rx callback for application */ struct Opn_Blk openBlock; }ECR_INFO;
/* --------------------- Packet Defines --------------------------*/ typedef struct unsigned char stx_char; unsigned char etx_char; unsigned char count; int max_pkt; void (*pPktHandler) (char , int); /* rx callback for packet mode */ } packet_parm_t;
/* --------------------- ECR tailgate Defines ---------------------*/ typedef struct {unsigned char poll_addr; } ECRtailgate_parm_t;
/* -------------------- Open Block Structure ----------------------*/ struct Opn_Blk {unsigned int rate; unsigned int format; unsigned int protocol; unsigned int parameter; packet_parm_t packet_parms; union { ECRtailgate_parm_t ECRtailgate_parms; } trailer; };
The structures defined above comprise the necessary settings needed to configure a serial port for RS232/485, Tailgate, Visa, Packet mode or other protocols.
Protocol The main structure is the Open Block structure (Opn_Blk), which contains an
element called protocol. The protocol variable indicates what mode the port should be configured for and further defines what other fields are applicable for that mode.
93
D EVICE D RIVERS Packet Mode
Trailer The value contained in the trailer field depends on the defined protocol.
Because the trailer field consists of different types, only one type is valid at any time. If tailgate mode is selected as the protocol, then the ECRtailgate_parms will be the valid field. All future mutually exclusive protocols will be defined here.
Packet_parms The packet_parms field is used for Packet Mode. It is defined outside the trailer
field as it is valid for different types of protocols to work in conjunction with packet mode. A serial port may be configured for RS232 packet mode or as tailgate with Visa protocol enabled which uses packet mode. This structure must be filled in prior to calling startPktMode().
Packet Mode
Packet mode protocol manages packet-based protocols over any of the serial ports. It supports the definition of a packet start and end character as well as error detection characters (such as LRC/CRC). The packet mode library will buffer incoming data until a complete packet is received. Once a complete packet is in the receive buffer, the library will call a callback function to deliver the message to the application. Outgoing message must be fully defined including start, end, and error detection characters before writing to the packet library. Packet mode protocol has been implemented as a static library named: libvfiprot.a
94
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 openBlock Handle of a previously opened serial port Serial communication control structure
Return Values
95
D EVICE D RIVERS endPktMode()
endPktMode()
endPktMode() is used to free packet mode buffers once a packet mode session is completed.
Prototype
void endPktMode(void);
96
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 rxLength Pointer to a char buffer with received message Length of received message
97
D EVICE D RIVERS COM Ports on the M x 800 series of Terminals
COM Ports on the Mx800 series of Terminals
There are 4 COM ports on the Mx800 series of terminals labeled COM1 COM4 plus an additional USB device serial port, COM5. They are referenced in software as the following devices:
COM1 = /dev/ttySAC0 COM2 = /dev/ttySAC1 COM3 = /dev/ttyWR0 COM4 = /dev/ttySAC2 COM5 = /dev/ttygser
Some ports are optional depending on the specific Mx800 series of terminals configuration. All ports can be used as a general RS232 port which can be configured for different baud rates, character sizes, parity, and stop bits using either standard Linux calls or the svcSetOpenBlock() call. They can also be configured to work in character or packet mode, such as the Visa protocol, and with or without flow control if that port supports it. The baud rates supported on all ports are: 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. COM5 is a special USB port that acts as a serial port and baud rate settings do not apply. Unlike other VeriFone terminals, the serial port devices can be opened for control by more than one process at a time. To prevent others from using the port at the same time, use the following ioctl() calls to have exclusive access to the opened port.
TIOCEXCL Put the ttySACx into exclusive mode, where no further open() operations are permitted. They will fail with EBUSY, except for root. Disable exclusive mode.
TIOCNXCL
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 UARTs Auto Flow Control. In this mode, the UART will control the RTS line automatically, and cannot be set by the application.
98
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. Ioctls 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. 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.
NOTE
99
D EVICE D RIVERS IBM ECR Tailgate & Feature C
COM4 - Optional I/O COM4, or device /dev/ttySAC2, is available only to the I/O Module and is Module dedicated for RFID capability. A physical serial port connector maybe available as
a future enhancement to this module so that it may be connected to a variety of devices.
COM5 COM5, or device /dev/ttygser, is actually a serial device that transmits and
receives data over a USB cable using the USB Gadget technology. This allows the Mx800 series of terminals to act like any other serial port when connected to a USB host port. The Mx800 series of terminals can be configured to become a USB device that can emulate being a serial port and be connected to a USB host. The Mx800 series terminals USB device cable can be connected to a Windows or Linux based OS machine and look like another COM port to that machine. This allows serial transfer of data back and forth between the Mx800 series terminal and a PC. Serial Gadget uses the bulk transfer method as defined in USB 2.0 specification. This transfer method is fixed to a 512 byte maximum packet size. The user/ application should be aware of this limitation when using this COM port to transfer data making sure that any remote communication program does not set its packet size greater than this maximum size.
IBM ECR Tailgate & Feature C
The succeeding section lists the IBM ECR APIs used both in Tailgate and Feature C mode.
100
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 -1 -2 -3 -4 -5 -6 -7 -8 I4683 environment variable NOT found. Device driver not installed L4683 environment variable NOT found. Invalid port number in L4683. Invalid port name argument. Invalid L4683 environment variable length. Invalid I4683 slot specified or not initialized. Visa protocol NOT started. Initialization failed of Polling semaphore. erno = -EINVAL errno = -ENXIO erno = -EINVAL erno = -EINVAL erno = -EINVAL erno = -EINVAL erno = -EBADSLT erno = -EPROTO erno = -EPERM
101
D EVICE D RIVERS ecrRead
ecrRead
Prototype
short bytes_read = ecrRead(char *buffer, short size);
Size is the maximum number of bytes to read, and buffer is a pointer to the data area. Each invocation of ecrRead() will transfer data from the port into the buffer, and return the number of bytes actually read or a negative value if an error occurred.
102
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.
103
D EVICE D RIVERS ecrStatus
ecrStatus
The information returned from ecrStatus() varies depending on whether the port is in Tailgate or Feature C mode and if VISA is enabled. If in Tailgate mode and VISA is enabled:
Prototype
struct vficomErrCounts *result = ecrStatus(int *buf);
Copy current status information to callers 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 3rd The number of bytes available (free) in the output buffer. 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. Status of ecrWrite() message: 0 1 2 message ACKed message pending message rejected
4th
Return Values
The result return code is a pointer to vficomErrCounts structure which is defined as:
struct vficomErrCounts { int frame_err; int over_err; int parity_err; };
The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function. The error counts provided are for framing, overrun and parity errors detected for that port. The counts provided are always total errors counted for that port since it was opened which allows the application to track if any new errors were detected for that port since the last time this function was called. If in Tailgate mode and VISA is not enabled:
104
Prototype
struct vficomErrCounts *result = ecrStatus(int*buf);
Copy current status information to callers 4-byte buffer.

1st 2nd 3rd The number of bytes pending in the input buffer. The number of bytes available (free) in the output buffer. Indicates if ECR is online. A non-zero value indicates the ECR is online (default is 0x37). A value of zero indicates ECR is offline.
Return Values
The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function. The error counts provided are for framing, overrun and parity errors detected for that port. The counts provided are always total errors counted for that port since it was opened which allows the application to track if any new errors were detected for that port since the last time this function was called. If in Feature C mode and VISA is enabled:
Prototype
struct vficomErrCounts *result=ecrStatus(int*buf);
105
Copy current status information to callers 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. 2nd 3rd The number of bytes available (free) in the output buffer. 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 0x40 0x20 0x10 0x08 0x04 0x02 0x01 4th set if DTR detected set if RTS detected set if CTS is detected set if Ring Indicator is present set if Carrier Detect (CD) set if DSR detected Reserved Reserved
Status of ecrWrite() message: 0 1 2 message ACKed message pending message rejected
Return Values
The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function. The error counts provided are for framing, overrun and parity errors detected for that port. They counts provided are always total errors counted for that port since it was opened which allows the application to track if any new errors were detected for that port since the last time this function was called.
106
If in Feature C mode and VISA is not enabled:
Prototype
struct vficomErrCounts *result = ecrStatus(int*buf);
Copy current status information to callers 4-byte buffer.

1st 2nd 3rd The number of bytes pending in the input buffer. The number of free bytes available in the output buffer. 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 0x40 0x20 0x10 0x08 0x04 0x02 0x01 set if DTR detected set if RTS detected set if CTS detected set if Ring Indicator is present set if Carrier Detect (CD) present set if DSR detected Reserved Reserved
107
Return Values
The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function. The error counts provided are for framing, overrun and parity errors detected for that port. The counts provided are always total errors counted for that port since it was opened which allows the application to track if any new errors were detected for that port since the last time this function was called.
108
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 Message too big or driver busy sending last message A rejected message must be read before sending another message. Use: ecrReadReject() Specific error that occurred
-ENOBUF -EBUSY
Any other negative errno error code
109
D EVICE D RIVERS ecrClose
ecrClose
This function closes the ECR port. Returns 0 if successful. Returns a negative errno error code if an error occurred.
Prototype
short result = ecrClose();
NOTE
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().
110
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 applications 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()
111
D EVICE D RIVERS ecrDownload
Return Values
0 -1 -EBUSY -EINVAL download started successfully the download process failed to start an ECR download process is already running invalid ECR Download End callback specified
Callback Return Values

1 0 -1 -2 A negative errno value download completed successfully never received an Online packet from the ECR or abort download download type not recognized expansion of archived/expressed file, failed specific error that occurred
112
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)
113
D EVICE D RIVERS Signals
Signals
Signals are present in practically all Unix/Linux systems and are a mechanism to inform processes of an event that has occurred. Signals have default behavior and documentation on all the signals available and their default actions can be found in practically any Linux/Unix programming book. If an application would like to be informed of an event that there is a signal available for, then the application can define a handler that would be executed upon receipt of that particular signal. This allows the application to trap on events and handle them as desired. The Mx800 series of terminals has the ability to use signals. As long as that event is triggered by the OS or any application, then an application can define a handler to trap on the desired signal. An example of this would be the SIGINT signal which is issued whenever an interrupt is received. A common way to receive an interrupt is when the user presses Ctrl-C on the keyboard. A way to trap on this event would be to add the following code to the application:
void sigHandler(void) { printf("Got Interrupt Signal!\n"); do desired cleanup stuff here exit(0); } int main(void) { struct sigaction mySig; int i; mySig.sa_handler = (void *)sigHandler; sigemptyset(&mySig.sa_mask); mySig.sa_flags = 0; i = sigaction(SIGINT, &mySig, 0); }
One of the restrictions of using signals is that there can only be one handler per process and all of its child process this includes processes created by fork() and any thread that is spawned with pthread_create(). The application programmer should be aware that any handler that they create for a particular signal would also have to handle that signal issued by any threads created by that application. Likewise, there are also Mx800 series terminal libraries that use signals. If an application links with this library and also wants to use the same signal then there has to be a mechanism to determine which process sent the signal and what action to take. The Mx800 series of terminals OS has implemented two such mechanisms for the SIGIO and SIGALRM signals. These signals inform an application when any I/O of data has occurred on a particular device and when an Alarm event has occurred, respectively.
114
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.
115
D EVICE D RIVERS ECR Environment Variables
The Mx800 series of terminals OS has provided a function that conveniently does this for the application called svcAlarm(). This function must be used in conjunction with the svcSetAlarmCallback() function. When the application no longer needs to be notified of an Alarm signal, it must unregister its callback function with using svcReleaseAlarmCallback().
ECR Environment Variables
There are required environment variables set when the ECR connection is established. They reside in config.usrx (where x is number of user account 18) and they follow INI parser rules. Some are set in the terminals 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 2B23 2A25 2B25 R232 tailgate port responding to poll address 0x68. tailgate port responding to poll address 0x69 tailgate port responding to poll address 0x64 tailgate port responding to poll address 0x65 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 Application Version YYYY Parameter ID
Application Version Parameter ID
is 4 bytes, which can contain any 4 byte alphanumeric string. is 4 bytes, which can contain any 4 byte alphanumeric string.
116
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 COM port B Baud Rate Word Size Parity Stop Bits Auto Enable RTS NOTE B Baud Rate Word Size Parity Stop Bits Auto Enable RTS
1 byte RS-232 port, either: 1 2 3 or 4 1 byte pad (space character) that is mandatory 6 bytes which can be set to 1200, 2400, 4800, 9600, 19200, 38400, 57600, or 115200 1 byte which can be set to either 7 or 8 1 byte which can be set to Even, None, or Odd, as E, N, or O respectively 1 byte, which can be set to either 1 or 2 1 byte which can be set to A, to enable RTS/CTS flow control 1 byte which can be set to R, to hold RTS in enabled state
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.
117
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 3 2400 7E1A 1 9600 7E1 R this string is 11 bytes in length and Auto Enable and RTS are not set. this string is 12 bytes in length and Auto Enable (flow control) is enabled. RTS is held asserted whenever flow control is enabled. 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 (ACKed). The timeout value indicates how much time should lapse between retransmissions. Setting the retry count to 0 or the timeout value to 0 will cause no retransmissions. The default value is: 39 (3 retries and 9-second timeout)
NOTE
If the application does not want the default value, then it must be set either in system mode, downloading its value or setting this environment variable to the desired value following INI parser rules. G4683 Set via a System Mode ECR download. If a Full download is selected then G4683 is set to FULL. If a Partial download is selected then G4683 is set to PART. This variable is not read by the operating system and exists so that the application can determine the download mode. When the download starts either by System Mode ECR/Serial download or a call to the ecrDownload() function, the G4683 variable is read. If its value is set to FULL, then all files and sub-directories will be deleted.
118
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>
119
D EVICE D RIVERS Touch Panel / Signature Capture/TIFF
Touch Panel / Signature Capture/TIFF
The touch panel is calibrated (also called compensated) at the factory. The factory calibration is used by the system until it is periodically updated. VeriFone strongly recommends that the touch panel be calibrated daily during a period of inactivity. During calibration, the unit must not be touched. VeriFone also recommends that the display backlight be turned off during calibration. Use the setDspBrightness() function to turn off the backlight. Use the touchCompNSave() function to perform the daily touch panel calibration.
Touch Panel Specifications

X-axis values are 0 2047 (460 DPI) Y-axis values are 0 1535 (460 DPI) Z-axis values are 0 127 (0 = Max force) Sample rate is 100 per second The maximum active area is: 113mm x 85mm
Linux interface is via: /dev/input/mice - The touch panel emulates a PS2 mouse. Use FancyPants GUI API to access touch activity and position.
120
D EVICE D RIVERS touchCmd()
touchCmd()
touchCmd() is used to set and get touch panel functionality per the following table: Table 7 cmd
2
value
N.A
return
Bit values
Notes
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);
0 or 1
N.A
Set input method: 0 = Finger or Stylus (Automatic) 1 = Stylus only
N.A
N.A
All cmd values not listed are RESERVED
Prototype
int touchCmd(int cmd, int value)
121
D EVICE D RIVERS touchCompNSave()
touchCompNSave()
touchCompNSave() is used to perform a touch panel calibration. The terminal must not be touched between the time this function is called and the time it returns. VeriFone recommends that touchCompNSave() be called once per day. VeriFone also recommends that the backlight be turned off during touch panel calibration.
Prototype
int touchCompNSave(void)
Return Values
0 Success Error
122
D EVICE D RIVERS Signature Capture
Signature Capture
Signature Capture is implemented as a widget at the FancyPants GUI level. The widget supports the definition of a signing region as well as the ability to track stylus movement. Note that the strokes returned by the Signature Capture widget are scaled to 320x234 (72dpi). If a higher resolution image is desired, use the API defined below to read and process the raw data. During signature capture, the unit will switch to stylus only mode only if there is one attached.
NOTE
#include svc.h #include sig.h typedef struct { long x : 12; // X co-ordinate 02047 of touched point long y : 12; // Y co-ordinate 01535 of touched point long z : 8; // Z co-ordinate/pressure 0127 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.
123
D EVICE D RIVERS SigCapCount()
SigCapCount()
Returns the number of signature points that are currently available.
Prototype
int SigCapCount(void)
124
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)
125
D EVICE D RIVERS SigCapBoxApply()
SigCapBoxApply()
This function takes the results of SigCapGet() and applies a signature box to the data. Data outside the box is replaced by PENUP. The data is also compressed to remove adjacent duplicate points and adjacent PENUPs. The function returns the new number of unique points. It is up to the application to supply the signature box to the function call. The box coordinates are in screen form, i.e. x 0319 and y 0239. Signature data is in touchpad coordinates 02047 and 01535 to maintain best resolution. It is not necessary to call this function before calling SigCap2Tiff().
NOTE Extra notes on using this function with SigCapGet and SigCapCount:
By design, a single pen up (-1,-1,-1) is inserted at the beginning of the buffer as soon
as signature capture is started. That is why a count of 1 is returned and the point is returned as (-1,-1,-1). As long as the pen stays up, no further points are inserted. Once the pen goes down, new data (x,y,z) are added. A pen up is also always inserted at the end of the buffer so that if the pen were able to go down and up again fast enough for just one down point to be registered, the count would be 3 (initial pen up, the down point, and another pen up). This mimics Omni 7X00 behavior and is not a bug.
SigCapGet and SigCapCount always return the total number of raw points collected.
The longer the pen is in contact with the keypad, the higher the count will be -- it does not matter if the points are in the box or not. Part of this count will be the residue from the initial pressing of the STROKES button in the test program. Those points will be replaced by -1,-1,-1 when SigCapBoxApply is called refer to the next bullet item. The positive result of the above function should be passed as the count parameter to SigCapBoxApply.
SigCapBoxApply does two things on the fly:
- It replaces all points outside the box by -1,-1,-1 - It compresses (shuffles toward the beginning of the buffer) the data so that all adjacent duplicates (for example several -1,-1,-1 in a row after applying the box) are replaced by a SINGLE copy of the data (in this case a single -1,-1,-1). This function returns the new total number of points after compression.
The original and compressed counts will almost certainly differ. When displaying the compressed data, the return value of SigCapBoxApply should
be used as the new size unless one deliberately wants to display the raw data.
Prototype
int SigCapBoxApply(xyz_t *Sig, int count, SigCapBox_t *box);
126
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;
127
D EVICE D RIVERS int SigCap2Tiff()
int SigCap2Tiff()
This function creates a file fname in TIFF format. Setting fname to 0 is an error.
Prototype
int SigCap2Tiff ( char *fname,xyz_t *sig, int count,short compression_scheme, xy_t *dpi,SigCapBox_t *box, SigCapOptions_t *options, void (*setTiffUserTags)(TIFF *) );
Parameters
sig is a pointer to the users 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. is the number of signature points in the callers buffer. A negative value is an error. 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. 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. is a pointer to a signature box specified in QVGA display coordinates {.x=0319, .y=0239). Data outside the box is interpreted as PENUP. Set to 0 to make the box be the entire screen. is a pointer to a structure that specifies whether points are joined (using Bresenhams 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. 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.
count
compression_scheme
dpi
box
Options
setTiffUserTags
128
D EVICE D RIVERS int SigCap2Tiff()
Return Values
0 <0 NOTE Success Error
The setTiffUserTags function can override the default date/time tag that is automatically inserted into the file. This is an optional user-supplied function that can over-ride standard tags (but be careful or the TIFF image may be affected or unusable) and can also define and specify new user tags in the range MIN_TIFFTAG_USER to MAX_TIFFTAG_USER (both defined in sigtiff.h.) An example of the setTiffUserTags function calling the structure containing the user-specified tags. The example TIFFTAG_GEO user defined tags below should be given values in the range MIN_TIFFTAG_USER to MAX_TIFFTAG_USER. Consult the tiffio.h header file for a summary of the meanings of the fields in the TIFFFieldInfo structure used in the table below.
CAUTION The open source TIFF library does not implement complete error checking. Be
careful to use only TIFF tag values within the range defined above. Unpredictable results will occur with other tag values.
static const TIFFFieldInfo xtiffFieldInfo[] = { /* XXX Insert Your tags here */ { TIFFTAG_GEOPIXELSCALE,-1,-1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE, "GeoPixelScale" }, { TIFFTAG_GEOTRANSMATRIX,-1,-1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE, "GeoTransformationMatrix" }, { TIFFTAG_GEOTIEPOINTS,-1,-1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE, "GeoTiePoints" }, { TIFFTAG_GEOKEYDIRECTORY,-1,-1,TIFF_SHORT,FIELD_CUSTOM,TRUE,TRUE, "GeoKeyDirectory" }, { TIFFTAG_GEODOUBLEPARAMS,-1,1,TIFF_DOUBLE,FIELD_CUSTOM,TRUE,TRUE, "GeoDoubleParams" }, { TIFFTAG_GEOASCIIPARAMS,-1,-1,TIFF_ASCII,FIELD_CUSTOM,TRUE,FALSE, "GeoASCIIParams" }, };
static void setTiffUserTags(TIFF *tif) { TIFFMergeFieldInfo(tif,xtiffFieldInfo,N(xtiffFieldInfo)); TIFFSetField(tif,TIFFTAG_GEOASCIIPARAMS,"Geo ASCII Params (Custom)Field"); TIFFSetField(tif,TIFFTAG_DOCUMENTNAME,"Document Name Field"); }
129
D EVICE D RIVERS Display
Display
The user interface is managed by the FST FancyPants GUI.
130
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 <0 OK Brightness at max/min setting
131
D EVICE D RIVERS Audio / Beeper
Audio / Beeper
At the lower level, the Mx800 series terminal kernel will implement a sound device using the Open Sound System (OSS) specification. See: http:// www.opensound.com/ Applications written to the OSS specification should run on the Mx800 series of terminals. The sound device is located at: /dev/dsp The FancyPants GUI will include a media player widget that supports the .WAV audio format.
132
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 100 bass treble Sound off Maximum volume
Accepted values: 50-100 Accepted values: 50-100
Return Values
0 Less than 0 No error Error occurred
133
D EVICE D RIVERS speaker()
speaker()
The VeriFone supplied library (libvfisvc.so) contains support for enabling / disabling the built in speakers. Disabling the built in speakers may be desirable if external speakers are connected to the Audio lineout connector on the multi-port cable.
Prototype
void speaker(int mode)
Parameters
mode 0 1 Disbale Internal Speakers Enable Internal Speakers
All other values are not supported and will give unexpected results.
134
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.
135
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.
136
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 LED2 LED3 Top LED Middle LED Bottom LED
To turn on all three LEDs, set PARM = LED1|LED2|LED3
137
D EVICE D RIVERS ledOff
ledOff
ledOff() is used to turn 1 or more of the LEDs off. A bit mask is used to select the LED(s) to turn off.
Prototype
void ledOff(int parm)
Parameters
parm LED1 LED2 LED3 Top LED Middle LED Bottom LED
To turn off all three LEDs, set PARM = LED1|LED2|LED3
138
D EVICE D RIVERS Real-Time Clock (RTC)
Real-Time Clock (RTC)
Linux has a rich API to support RTC functionality, so we will not be supplementing or modifying that API. The Mx800 series of terminals include VeriFone specific RTC hardware required to keep the time accurate when the unit is turned off. On power up, the operating system will automatically set the Linux (soft) RTC from the Mx800 series terminal RTC hardware. The setRTC() function must be called immediately after any call that sets the time/date of the Linux RTC or the updated time/date will be lost when the unit is turned off.
139
D EVICE D RIVERS setRTC()
setRTC()
Used to set the RTC hardware to the Linux RTC time/date. This function must be called immediately after any function that sets the Linux RTC time/date. There are no parameters or return codes from setRTC().
Prototype
void setRTC(void)
140
D EVICE D RIVERS setDateTime()
setDateTime()
As user processes are not allowed to set the Linux RTC, applications must call setDateTime() passing the date and time in the same format used in the shell command date. Format: MMDDhhmmYYYY.ss

NOTE
MM = Month DD = Day hh = Hour (24-hour format) mm = Minute YYYY = Year ss = Seconds
setDateTime only sets the Linux RTC. To set the H/W RTC, application must follow setDateTime with a call to setRTC.
Prototype
int setDateTime(char *dateTime)
Return Values
0 Success Error
Less than 0
141
D EVICE D RIVERS setDateTime()
142
CHAPTER 5
Service Functions
Service Functions for the Mx800 series of Terminals
This chapter lists the service function APIs used in the Mx800 series of terminals.
143
S ERVICE F UNCTIONS svcCrcCalc()
svcCrcCalc()
Prototype
checksum = svcCrcCalc(type, buffer, size) int checksum, type, size; char*buffer;
Parameters
This routine returns the cyclic redundancy check for a string contained in buffer of a length specified by size. Each type is now specified by referring to a standard CRC description model which can be found by searching the Internet for A Painless Guide to CRC Error Detection Algorithms (August 1993) by Ross N. Williams. The model has the following description parameters: width (of CRC/LRC in bits), poly(nomial), (init)ialization value generally 0 or -1, refin (whether each input byte is reflected about its center before being applied to the algorithm), refot (whether the calculated CRC gets reflected about its center), xorot (the value generally 0 or -1 that gets exclusive-ored to the final result before being returned to the caller, check (the CRC/LRC produced by applying this algorithm to the 9-character ascii string 0123456789. The type parameter specifies what type of calculation is to be employed:
0 Longitudinal Redundancy Check. This is simply the exclusive OR'ing of all bytes in the string. The result of the LRC will be stored in the lower byte. The upper byte will be set to zero. Model: width=8,poly=0x01,init=0,refin=0,refot=0,xorot=0,check=0x31. 1 Cyclic Redundancy Check, based on the standard CRC16 polynomial, X^16+X^15+X^2+1. Bits are read least-significant-bit first, as is traditional in hardware implementations. The CRC1 value is returned in the low byte and the CRC2 value is returned in the high byte. Model: width=16,poly=0xA001,init=0,refin=0,refot=0,xorot=0,check=0xA47b 2 CRC16, most-significant-bit first, as is often used in software implementations. The CRC1 value is returned in the high byte and the CRC2 value is returned in the low byte. Model: width=16,poly=0x8005,init=0,refin=0,refot=0,xorot=0,check=0xFEE8 3 CCITT polynomial, X^16+X^12+X^5+1, lsb-first Model: width=16,poly=0x8408,init=-1,refin=0,refot=0,xorot=0,check=0x0520 4 CCITT, msb-first Model: width=16,poly=0x1021,init=-1,refin=0,refot=0,xorot=0,check=0x29B1
144
S ERVICE F UNCTIONS svcCrcCalc()
CRC32, lsb-first, reflected input and output Model: width=32,poly=0x04C11DB7,init=0,refin=1,refot=1,xorot=0, check=0x2DFD2D88
CRC32, lsb-first, reflected input & output, inverted result Model: width=32,poly=0x04C11DB7,init=-1,refin=1,refot=1,xorot=-1, check=0xCBF43926
CRC16, msb-first, reflected input and output Model: width=16,poly=0x8005,init=0,refin=1,refot=1,xorot=0,check=0xBB3D
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.
145
S ERVICE F UNCTIONS svcDsp2Hex()
svcDsp2Hex()
This command causes the data at dsp to be converted and stored at location hex. The presumption is that the input (at dsp) consists of count pairs of bytes, with each byte in the range of 30h-90h (ASCII 0-9) or 42h-46h (ASCII A-F). Each byte will then be converted to the corresponding hexadecimal nibble (hex 0-9, AF). This function will convert up to a long hex value for the corresponding ASCII array. It will only convert up to the number of pairs specified even if the ASCII string is longer. This function is a void function and does not return any error or success code. It expects all values to be legal hex values.
Prototype
void svcDsp2Hex(dsp, hex, count)
Example
Suppose dsp contains ASCII array 12345F and we execute SVC_DPS_2_HEX(dsp, hex, 3). Then the value of hex will be 12345h.
146
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);
147
S ERVICE F UNCTIONS svcInfoKernel() / svcInfoEprom()
svcInfoKernel() / svcInfoEprom()
This function fills buffer with the current firmware ID in null-terminated string format.
Prototype
svcInfoKernel(buffer); svcInfoEprom(buffer); char *buffer;
The Mx800 series of terminals has been assigned the identifier, Mx. Released OS versions will be MxXxYyAa.
Parameters
Xx Yy Aa reserved (00) Version Number Country Code
The length will always be eight characters.
148
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;
149
S ERVICE F UNCTIONS svcInfoSerialNum()
svcInfoSerialNum()
This function fills buffer with the units 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;
150
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
151
S ERVICE F UNCTIONS svcInfoPlatform()
svcInfoPlatform()
This function provides information about the terminal running the application. feature can be one of the following values: Table 8 Feature
0 1 2 3 4 5 6 7-15
Definition
Unit Configuration Lithium Battery Status Lithium Battery Voltage in tenths of a Volt SDRAM size in KB Multi-port Cable Status I/O Module Configuration Smart Card Version 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
0 1 2 3-15
Definition
Ethernet Smartcard Audio Reserved
Value
1 = installed 1 = installed 1 = installed, 0 = buzzer
If feature = 1, then the value in result for the lithium battery status will be: 1 0
NOTE If the lithium battery is OK If the lithium batter is bad
The lithium battery is used to preserve the SRAM on the Mx800 series terminal when the power is off. If feature = 2, then the value in result will be the lithium battery voltage, in tenths of a Volt (0.1V).
152
S ERVICE F UNCTIONS svcInfoPlatform()
If feature = 3, then the value in result will be the amount of static RAM currently installed in kilobytes. If feature = 4, then the following bit values are returned, for multi-port cable status: Table 10 Bits
0
Definition
Multi-port cable type*
Value
0 = Everest 1 = Mx800 series
1 2 3 4 5 6-15
USB Type** COM1 Configuration COM3 Configuration COM1 Connection Detected** COM2 Connection Detected** Reserved
0 = Host 1 = Client 0 = RS-232 1 = RS-485 (LAN) 0 = RS-232 1 = RS-485 (ECR Tailgate) 1 = YES 1 = YES
NOTE
If Everest type multi-port, then USB and Ethernet ports are not available.
NOTE
Connection to a powered DTE or DCE. These bits are valid only if the Mx800 series terminal multi-port cable is detected. If feature = 5, then the following bit values are returned, for I/O module configuration: Table 11 Bits
0 1 2 3-14 15
Definition
Contactless/RFID 802.11 Biometrics Reserved O7xxx I/O module
Value
1 = YES 1 = YES 1 = YES 1 = YES
If feature = 6, then the following bit values are returned, for smart card version: Table 12 Bits
0 1 2-15
Definition
Smart Card Version 1 (Delta) Smart Card Version 1 (Delta2) Reserved
Value
1 = YES 1 = YES
153
S ERVICE F UNCTIONS svcInfoType()
svcInfoType()
This function provides more information about the terminal running the application. feature can be one of the following values: 0 1
Processor type: 6 = S3C2410 Platform: 1000 = Mx800 series of terminals
Prototype
result = svcInfoType(feature); int result, feature;
Return Values
The information is returned in result.
154
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 1
2 3 4 5 6 7 Characters / row (0 if variable) Characters / column (0 if variable) Pixels / row (0 if not pixel variable) Pixels / column (0 if not pixel variable) Packed tail characters (0=no, 1=yes) Number of fonts supported Display type (0=segmented, 1=pixel) Contrast adjustable (0=no, 1=yes)
Prototype
result = svcInfoCard(feature); int result, feature;
Return Values
The information is returned in result. 0 1
2 3 4 5 6 7 0 0 320 240 0 0 1 1
155
S ERVICE F UNCTIONS svcInfoCard()
svcInfoCard()
This function provides information about the type of card reader supported by the terminal on which the application is running. feature must be a value of 0. feature = 0 Bit map of supported track options
0x01 0x02 0x04 0x08 0x10 Dual track track 1 track 2 track 3 Triple track
Prototype
int return = svcInfoCard(int feature);
Return Values
The information returned in result will be the ORed value of all tracks supported. Since all Mx800 series terminals support triple track reading, the value returned is the ORed value of track 1, track 2, track 3, and triple track support which is 0x1E.
156
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 1
2 3 4 number of standard keys: returns 0 number of non-screen-addressable function keys: returns 0 number of screen-addressable function keys: returns 0 keypad layout (0=telco, 1=calculator, 2=Touch): returns 2 If return value is >0 then a touch panel is installed: returns 1
Prototype
result = svcInfoKey(feature); int result, feature;
Return Values
The information is returned in result.
157
S ERVICE F UNCTIONS svcInfoSerialNum
svcInfoSerialNum
Returns the serial number of the unit. This is the same serial number that is on the units label. The returned string is null-terminated. Format of buf: xxx-xxx-xxx xxx-xxx-xxx is an ASCII 11-digit string. (e.g. 000-012-030)
Return Values
result = svcInfoSerialNum(char *buf);
158
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. 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. F P endCallback Full download Partial download
dspCallback
type
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. 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.
ZA
159
S ERVICE F UNCTIONS svcZontalkRcv()
If the server application supports embedding environment variables in the download stream, then svcZontalkRcv() will set these environment variables in the users configuration file. If any of the above two environment variables are already set prior to initiating a download, then their values will be used as described above. If these environment variables are not present, then the terminal and application ID will default to the strings DEFAULT and 1, respectively. This function is the same function used in a System Mode download. A System Mode download will display DOWNLOAD SUCCESSFUL, DOWNLOAD FAILED, or DOWNLOAD CANCELLED message indicating the completion of the download and its status.A user can cancel the download by touching the System Mode screen before the download is completed. Filenames of downloaded files are limited to 60 characters or less.
NOTE
The port should be configured for character mode and 8 bit, no parity, 1 stop. The baud rate may be any rate supported.
160
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.
161
S ERVICE F UNCTIONS svcSetOpenBlock()
svcSetOpenBlock()
The svcSetOpenBlock() function accepts a pointer to an Open Block structure that has been populated by the application to the desired port settings. This function then takes the open block settings and properly maps them to Linux serial port settings and sets the port to these values. The port to be set is described by the fd parameter. The function will automatically configure the port according to the open block structure values passed in. If the open block format variable is set to Fmt_auto, then the port is automatically configured to use RTS/CTS flow control and will also hold the RTS line asserted. All ports configured with Fmt_auto will hold the RTS line asserted regardless if the Fmt_RTS value is specified or not. This is required for all ports to transmit and receive data correctly. The application is not required to specifically set Fmt_RTS if Fmt_auto is specified. However, if this function is not used to configure a COM port on the Mx800 series terminal and the application wants to enable flow control, it is the responsibility of the application to issue the proper Linux calls to set flow control AND assert RTS in order for COM port communication to function properly. If RTS is not asserted when flow control is desired, the port will not work. If flow control is not desired, but RTS asserted is, then Fmt_RTS should only be specified. It is highly recommended that applications use this function to configure a COM port to desired settings.
Prototype
short svcSetOpenBlock(int fd, struct Opn_Blk *pOpenBlock)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen(). Pointer to Open Block structure that has been populated with desired settings.
*pOpenBlock
Return Values
The function returns 0 on success or a negative errno value if unsuccessful.
162
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(). Function pointer which points to function to be called when data is available.
(*rxfp) (void)
Return Values
163
S ERVICE F UNCTIONS svcReleaseRxCallback()
svcReleaseRxCallback()
The svcReleaseRxCallback() function must be used when the application no longer needs to know if data I/O has occurred on a particular device associated with the file descriptor (handle) given. The file descriptor (fd) passed to this function should be the same one that was used to register a callback function for the device with svcSetRxCallback().
Prototype
short svcReleaseRxCallback(int fd)
Parameters
fd File descriptor returned when opening a device, with either open() or ecrOpen().
Return Values
164
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 (*rxfp) (void) Process ID of the process that will issue the SIGALRM signal. Function pointer which points to function to be called when SIGALRM signal has been issued.
Return Values
165
S ERVICE F UNCTIONS svcReleaseAlarmCallback()
svcReleaseAlarmCallback()
The svcReleaseAlarmCallback() function must be used when the application no longer needs to know if the SIGALRM signal has been issued for a particular process. The process ID (pid) passed to this function should be the same one that was used to register a callback function for the device with svcSetAlarmCallback().
Prototype
short svcReleaseAlarmCallback(int pid)
Parameters
pid Process ID that was used to register the callback with svcSetAlarmCallback().
Return Values
166
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 applications 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.
167
S ERVICE F UNCTIONS svcGetPortStatus()
svcGetPortStatus()
The svcGetPortStatus() function returns the following information regarding the port:
NOTE
The Mx800 series terminal does not support the detection of parity errors on the COM ports due to the limitations of the ARM processor.
Prototype
struct vficomErrCounts *svcGetPortStatus(int inFd, int *buf)
Parameters
inFd buf The file descriptor associated with the open port device. 4 integer buffer used to return the port signal status information
Return Values
buf[0] buf[1] Number of received bytes pending in its input queue. 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. 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.) 0x80 0x40 0x20 0x10 0x08 0x04 0x02 0x01 buf[3] Reserved set if DTR detected set if RTS detected set if CTS detected set if Ring Indicator present set if Carrier Detect (CD) present set if DSR detected Reserved Reserved
buf[2]
168
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:
The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function. The error counts provided are for framing, overrun and parity errors detected for that port. The counts provided are the total errors counted for that port since it was opened which allows the application to track if any new errors were detected for that port since the last time this function was called.
169
S ERVICE F UNCTIONS svcGetInQ()
svcGetInQ()
The svcGetInQ() function returns the number of bytes pending in the ports input queue.
Prototype
int svcGetInQ(int inFd)
Parameters
inFd The file descriptor associated with the open port device.
170
S ERVICE F UNCTIONS svcGetOutQ()
svcGetOutQ()
The svcGetOutQ() function returns the number of bytes pending in the ports output queue.
Prototype
int svcGetOutQ(int inFd)
Parameters
inFd The file descriptor associated with the open port device.
171
S ERVICE F UNCTIONS svcExpand()
svcExpand()
Prototype
int svcExpand(char *inFile, int keepinFile, char *uowner)
Parameters
inFile Pointer to a string containing the name of the file to expand. This file should be in a tar format with or without either GNU zipped or binary zipped compression. The file should be named appropriately with the correct extension following customary Linux naming conventions regarding tar files. Either .TAR for a regular tar archive or .TGZ or .GZ for a GNU zipped format. For a binary zipped format, it should have the extension .BZ2. These are the only formats supported at this time. The file extension is not case sensitive. A flag to indicate whether to keep the tar file after expansion takes place. Default is to delete the tar file. 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.
keepinFile uowner
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 users home directory are set to the users ownership. Permissions are set for each file to what they were at the time the file was archived.
172
S ERVICE F UNCTIONS svcUsbStorPresent()
svcUsbStorPresent()
The svcUsbStorPresent() function determines how many USB storage/ memory devices are currently plugged into the USB host port, mounted properly and ready for access. If so, then it sets a value of 1 in each byte of the array pointed to by usbStorDevPresent. A value of 1 indicates that a device is mounted on that particular directory and ready for access. Each byte of the array corresponds to the directories as follows: /mnt/usbstor1 = usbStorDevPresent[0] /mnt/usbstor2 = usbStorDevPresent[1] /mnt/usbstor3 = usbStorDevPresent[2] /mnt/usbstor4 = usbStorDevPresent[3] The files can be accessed at these mount points if there is a value of 1 in the corresponding array byte.
Prototype
int svcUsbStorPresent(char *usbStorDevPresent)
Parameters
usbStorDevPresent Pointer to char of at least 4 allocated bytes
Return Values
Return value is 0 on success, -EINVAL if invalid parameter passed.
173
S ERVICE F UNCTIONS COM3 Service Functions
COM3 Service Functions
The COM3 service functions are for tuning and configuring the communication processor used on the COM3 port. These functions were brought up to the API level in case there is a need to use them directly in an application for a special architecture/configuration. Otherwise, the following COM3 service functions should not have to be used directly by an application. All other API calls that require COM3 configuration/tuning, use these functions and do the necessary work for the application. Depending how the COM3 port is opened, the required configuration is done automatically as long as the Mx800 series of terminals API functions are utilized. It is only a rare occasion or special architecture that may require special tuning where the default settings may have to be changed directly by the application using these service functions. All COM3 service functions operate strictly on the communication processor and from the perspective of the communication processor. These service functions have nothing to do with the operating system. For instance, flushing the COM3 buffer using the svcCOM3FlushRxBuf() does not flush the operating system buffer, it flushes the remaining data from the communication processor buffer into the OS buffers.
174
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 ioctlMode File descriptor returned when opening a serial port with either open() or ecrOpen(). Value indicating the mode to set the port to as defined as follows: MODE_CLOSE_CHANNEL MODE_R232_INT MODE_R485_INT MODE_SIO_INT Port is set to not valid mode RS232 mode RS485 mode SIO Tailgate mode
Return Values
This function returns 0 upon success and a negative value if unsuccessful.
175
S ERVICE F UNCTIONS svcCom3ReqExtStatus()
svcCom3ReqExtStatus()
The svcCom3ReqExtStatus() function will return the value of the extended status report into the buffer pointed to by esBuf. The extended status report is a 2byte value that indicates the configuration and handshake settings for the port. This function returns 0 upon success and a negative value if unsuccessful. The Extended Status report is defined as follows: Table 13 Entry
<DevStat1> <DevStat2>
Status Record Structure: <DevStat1> <DevStat2> Size

byte byte
Description
Configuration status Handshake status
Where: DevStat1 = Configuration Status Where: Table 14 Bit

b7
Mnemonic Description
FAM Access mode 0 1 Polled access mode On Demand access mode
b6
FWDS Watchdog Status 0 1 Disabled Enabled
b5
FOPEN Channel status 0 1 Channel is closed Channel is active
b4
FRST Reset path 0 1 Reset via Host control Reset via Watchdog event
b3
FXDR External Device reset status 0 1 No device reset received Device reest received
b2 b1 b0
* Reserved * Reserved * Reserved
176
S ERVICE F UNCTIONS svcCom3ReqExtStatus()
Where: DevStat2 = Handshake Status Where: Table 15 Bit

b7
RE Receive enable 0 1 Receive disabled Receive enabled
b6
FHW Trransmit wait status 0 1 Transmit wait on handshake disabled Transmit wait on handshake enabled
b5
FAO Auxiliary Out state 0 1 Aux Out is in idle state Aux Out is in Asserted state
b4
FCO Control Out state 0 1 Control Out is in Idle state Control Out is in Asserted state
b3
FRO Ready Out state 0 1 Ready Out is in Idle state Ready Out is in Asserted state
b2
AI Auxiliary In status: (N/A) 0 1 Aux In is in Idle state Aux In is in Asserted state
b1
CI Control In status: (CTS) 0 1 Control In is in Idle state Control In is in Asserted state
b0
RI Ready In status: (N/A) 0 1 Ready In is in Idle state Ready In is in Asserted state
Prototype
short svcCom3ReqExtStatus(int fd, char *esBuf)
177
S ERVICE F UNCTIONS svcCom3ReqTallyInfo()
svcCom3ReqTallyInfo()
The svcCom3ReqTallyInfo() function allows the application to request the Tally Information report which is comprised of a listing of counters that track ECR events. This function returns 0 upon success and a negative value if unsuccessful. The Tally Record report is defined as follows: Tally Record Structure: <Ntallies> <Id> <Count> . . . <Id> <Count> The tally record is a listing of the current tally counters. The record is open ended and allows for additional tally counters to be added. Each tally count is uniquely identified and is followed with a 16 bit binary value in MSB/LSB order. The tally counters are up counters that increment with each detected event and will clamp at 0xFFFF to indicate overflow. Where: Table 16 Entry
<Ntallies>
Tally Record Size

byte
Range
00 FF
Description
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. FF Tally code identifier (see table below) 16 bit tally count. Order is MSB/LSB.
<Id> <Count>
byte word
00 FF 0000 FFFF
Table 17 <ID>
1 2 3 4 5
Mnemonic
ODP LDP MSE SCE POR
Description
Number of other device polls. Number of local device polls. Number of message structure errors. Number of sequence count errors. 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(). pointer to a buffer that will hold the Tally Information report.
*tiBuf
178
S ERVICE F UNCTIONS svcCom3ResTallyData()
svcCom3ResTallyData()
The svcCom3ResTallyData() function resets all the tally counters to zero.
Prototype
short svcCom3ResTallyData(int fd)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen().
Return Values
179
S ERVICE F UNCTIONS svcCom3ReqFirmVers()
svcCom3ReqFirmVers()
The svcCom3ReqFirmVers() function requests the current firmware version within the communication processor. This call can be used to verify the current firmware version. The function will write the firmware version string to the log file and will also return the string in the buffer pointed to by *fwBuf. It is a null terminated string that can be printed or displayed.
Prototype
short svcCom3ReqFirmVers(int fd, char *fwBuf)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen(). Pointer to a buffer that is at least 16 bytes in size, that will hold the nullterminated current communication processor firmware version string.
*fwBuf
Return Values
180
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 da File descriptor returned when opening a serial port with ecrOpen(). 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.
181
S ERVICE F UNCTIONS svcCom3SetECLevel()
svcCom3SetECLevel()
The function svcCom3SetECLevel() function sets the ECR engineering change level that is reported to the ECR in response to the Request EC command. This value is logged by the ECR and may be used to invoke version specific drivers. The legal values are 00-FF and the default is FF corresponding to an OEM device.
Prototype
short svcCom3SetECLevel(int fd, char ec)
Parameters
fd ec File descriptor returned when opening a serial port with ecrOpen(). A 1 byte value to set the ECR engineering change level.
Return Values
182
S ERVICE F UNCTIONS svcCom3SetHandshake()
svcCom3SetHandshake()
The svcCom3SetHandshake() function sets the handshake byte to the value indicated.
Return Values
This function returns 0 upon success and a negative value if unsuccessful. The value of the handshake control byte can be read using the svcCom3ReqExtStatus() function. Each bit of the handshake value indicates a specific state defined as follows: Where: Table 18 Bit
b7
RE Receive enable 0 1 Receive disabled Receive enabled
b6
HW Handshake wait 0 1 Transmit unconditionally Transmit waits on Handshake
b5
AO Auxiliary Out (N/A) 0 1 Aux Out is in Idle state Aux Out is in Asserted state
b4
CO Control Out 0 1 Control Out is in Idle state (RTS) Control Out is in Asserted state (RTS)
b3
RO Ready Out (N/A) 0 1 Ready Out is in Idle state Ready Out is in Asserted state
b2 b1 b0
* Reserved * Reserved * Reserved
183
S ERVICE F UNCTIONS svcCom3SetHandshake()
Prototype
short svcCom3SetHandshake(int fd, char hs)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen(). A 1 byte value that indicates the handshake control.
ec
184
S ERVICE F UNCTIONS svcCom3FlushRxBuf()
svcCom3FlushRxBuf()
The svcCom3FlushRxBuf() function allows the application to manually flush the receive buffer internal to the communication processor. This command is meaningful only in RS232 mode: MODE_R232_INT.
Prototype
short svcCom3FlushRxBuf(int fd)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen().
Return Values
185
S ERVICE F UNCTIONS svcCom3SetRxRecThresh()
svcCom3SetRxRecThresh()
The svcCom3SetRxRecThresh() function allows the application to set the receive record threshold (RRT). This threshold is used to set the minimum size of receive records returned to the host from the communication processor. This command is not valid in COM3 tailgate mode: MODE_SIO_INT and has no effect if used in this mode. The value can be in the range of 01-FF and defaults to decimal value of 96. If this value is set too large then a loss of data can occur due to the time required to process the larger receive record. If the value is set too small, then a contention for resources could occur due to the time required to process the interrupt for each receive record. A value of 0 is not allowed as this would effectively shut off reception of all data. This value, in conjunction with the Buffer Flush Interval (BFI), controls how received data is released to host driver for processing.
Prototype
short svcCom3SetRxRecThresh(int fd, char rrt)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen(). a 1 byte value that indicates the receive record threshold to be set.
rrt
Return Values
186
S ERVICE F UNCTIONS svcCom3SetBufFlushInt()
svcCom3SetBufFlushInt()
The svcCom3SetBufFlushInt() function allows the application to manually set the buffer flush interval. This value indicates when a record that is less in size than the Receive Record Threshold is to be released to the host. It sets the maximum latency, in milliseconds, for receive characters to reside in the communication processor receive buffer before a record is released. This function is not valid in tailgate mode: MODE_SIO_INT and will have no effect if used in this mode. The BFI value is automatically set to the optimum value by the Mx800 series terminal according to the baud rate and the RRT values. This function should only be used to manually override the automatically calculated value.
Prototype
short svcCom3SetBufFlushInt(int fd, char bfi)
Parameters
fd File descriptor returned when opening a serial port with either open() or ecrOpen(). A 1 byte value that indicates the buffer flush interval to be set.
rrt
Return Values
187
S ERVICE F UNCTIONS svcCom3Polled()
svcCom3Polled()
The svcCom3Polled() function allows the application to check if the ECR address the Mx800 series terminal is being polled by the ECR. The terminal must be configured for tailgate mode and set to a particular address. This function when called, will return the number of polls that occurred since the last time it was requested. The internal poll count is only updated at most, once per second. So, if this function is called more than that frequency, it will return the last value reported. This same function is used during a System Mode ECR Download in tailgate mode to check if the terminal is being polled. If the terminal is being polled by the ECR, then the message POLLED will be displayed on the Mx800 series terminal screen.
Parameters
int svcCom3Polled(int fd)
Parameters
fd File descriptor returned when opening a serial port with open() or ecrOpen()
188
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();
189
S ERVICE F UNCTIONS enableProcessMonitor()
enableProcessMonitor()
Enabling a process monitor causes the system to periodically check the health of the calling process. If the process has exited, the system will detect the failure and force a system reboot. The purpose of monitoring a process is to prevent the terminal from hanging if a bug or unexpected event occurs causing a critical process to exit.
NOTE
A maximum of 50 processes can be monitored at any time. If a process spawns processes the new processes will need to register themselves if it is desired that they also be monitored.
WARNING If a process naturally exits or is replaced, it is up to the application to call
disableProcessMonitor() prior to exiting. Otherwise, the system will interpret that a failure has occurred and will force a reboot.
Prototype
void enableProcessMonitor(void)
190
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)
191
S ERVICE F UNCTIONS enableButtonSig()
enableButtonSig()
Calling enableButtonSig() causes the signal SIGINT to be sent to the registering process when the recessed button is pressed for less than two seconds. Sending a SIGINT to a process when the recessed button is pressed is done so that the application can implement a setup/configuration mode. The application receiving the SIGINT can drive the GUI as desired.
NOTE
If the user presses the recessed button for longer than two seconds, the normal system mode password display will be called.
192
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.
193
S ERVICE F UNCTIONS disableButtonSig()
194
CHAPTER 6
System Mode
System Mode for the Mx800 series of Terminals
The Mx800 series of terminals System Mode will be a departure from previous products in that a graphical user interface will be used for presentation. The System Mode idle display will have pertinent terminal configuration and status information on the top and bottom border of the display and task driven icons in the center. Title Area
Date / Time
The idle screen icons will be used to access critical features such as:
Information Detailed Hardware / Software Configuration Display. Buttons support the display of the current Cable, COM3 firmware and Ethernet status. 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. Refer to the Mx800 series Reference Manual, VDN 23754. 195
Configure
Diagnostics
S YSTEM M ODE System Mode for the M x 800 series of Terminals
File Transfer File Manager Security
Direct load, ECR download, FTP. Supports launching the application associated with *GO and rebooting the system. VeriShield Security, displays the certificate IDs and serial numbers. Key Status Displays the status of the 10 master key and 3 DUKPT key slots, Key injection permits security key loading, and password management allows the user and key loading passwords to be changed.
196
CHAPTER 7
Root File System
The Embedded Linux OS is much more than a kernel. A number of significant applications and modules are required to complete the system. These applications, libraries and driver modules reside in the root file system.
1 BusyBox - Combines tiny versions of many common UNIX utilities into a single
small executable. It provides replacements for most of the utilities you usually find in GNU fileutils, shellutils, etc. The utilities in BusyBox generally have fewer options than their full-featured GNU cousins; however, the options that are included provide the expected functionality and behave very much like their GNU counterparts. BusyBox provides a fairly complete environment for any small or embedded system. BusyBox has been written with sizeoptimization and limited resources in mind. It is also extremely modular so you can easily include or exclude commands (or features) at compile time. This makes it easy to customize your embedded systems. To create a working system, just add some device nodes in /dev, a few configuration files in /etc, and a Linux kernel. See: http://www.busybox.net/about.html
2 uClibc A C library for embedded Linux. uClibc (aka Clibc/pronounced yewsee-lib-see) is a C library for developing embedded Linux systems. It is much smaller than the GNU C Library, but nearly all applications supported by glibc also work perfectly with uClibc. Porting applications from glibc to uClibc typically involves just recompiling the source code. uClibc even supports shared libraries and threading. See: http://www.uclibc.org/about.html
197
R OOT F ILE S YSTEM Directory Structure
Directory Structure
Linux / Unix has a long history with respect to the root file system directory structure. This document will not attempt to explain this history. If you are interested, see: http://www.pathname.com/fhs/.
/
bin
boot
dev
etc
home lib initrd
mnt
proc root
sbin sys
usr
var
usr1
usr2
bin
sbin
Organization of Files in the Standard Directory Structure
/bin
stores essential binaries (programs) needed when booting the system or working in single user mode to maintain the system. stores kernel images and boot configuration files. stores device special files used to access hardware devices. stores system configuration files. stores the home directories for the individual users. not used. stores library modules used by the commands. a mount point for other storage devices. a pseudo file system for conveying data about processes. home directories for root. stores commands required to administer the system. system resource configuration. used for programs, libraries, documentation, etc used by normal users. stored system data that varies or changes frequently such as system logs, etc.
/boot /dev /etc /home /initrd /lib /mnt /proc /root /sbin /sys /usr
/var
198
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.
199
200
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. (Theres 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 Microsofts 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 Microsofts 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.
201
USB - D EVICE / H OST USB Host
USB Host
The Mx800 series of terminals supports USB host functionality and can run specific drivers for a multitude of different devices that can be plugged into the Mx800 series terminal. Currently, the Mx800 series of terminals has been tested with the following devices:
USB Keyboard and Mice (HID Class) USB Memory Sticks and hard drives - Using MSDOS compatible FAT32/VFAT format
Specific support for most USB devices requires the necessary drivers to be manually loaded into the system and manually configured. Support for USB memory and mass storage devices has been built into the Mx800 series unit and requires little or no manual intervention. This described in more detail in the next section. IBM AT keyboard and scanners that use the AT keyboard scan codes are also supported under the Mx800 series USB host. If a USB keyboard or a scanner is plugged into the Mx800 series USB host port, the necessary HID drivers to support the device are automatically loaded. To open and read data from these devices, the API function calls: inputOpen(), inputRead() and inputClose() should be used. Detailed explanation of these functions are described in more detail under their respective sections. USB HID device support is described below.
NOTE
USB host is only supported on specific Mx800 series cables. Currently, these cables are the Mx800 series of terminals: - Red cable P/N 23739-02 - Green cable P/N 23740-02
USB Mass Storage The Mx800 series of terminals has built-in automatic support for USB mass and Memory storage and memory devices. The unit will support a single memory device Devices plugged into the USB host port on a Mx800 series terminal cable or up to 4
memory devices at any one time plugged in via a USB hub. The Mx800 series terminal does not support more than 4 USB memory/mass storage devices at this time, but they can be plugged into the unit in any configuration of single or multiple hubs. The Mx800 series of terminals will automatically detect any memory/mass storage device plugged into the unit and will automatically mount the device on one of the 4 directories located under the /mnt directory. The directory names for the memory devices are:
/mnt/usbstor1 /mnt/usbstor2 /mnt/usbstor3 /mnt/usbstor4

202
USB - D EVICE / H OST USB Host
Each directory will be used in order as the devices are plugged into the unit. If a device is removed, it is automatically unmounted from the directory mount point and the data on it is no longer accessible. While the device is plugged in, the data can be accessed by an application. The application can determine if a memory/ mass storage device has been detected, mounted properly, and is ready to be accessed by making a call to the function svcUsbStorPresent(). This function call is described in greater detail in Chapter 5. It expects a pointer to a char which can hold at least 4 bytes. When the function is called, it determines which mount points have a device currently plugged in and mounted on its directory and available for access. It will return the pointer with a value of 1 for each device that is mounted and a 0 for each device that is not. All files located on the device can be accessed at that mount point. For example, if the function returns the values: 0, 1, 0, 1 then,
/mnt/usbstor1 does not have a usb memory/storage device plugged in and mounted on this directory. does have a device plugged in and the files located on the memory device can be accessed at this point. does not have a usb memory/storage device plugged in and mounted on this directory. does have a device plugged in and the files located on the memory device can be accessed at this point.
/mnt/usbstor2
/mnt/usbstor3
/mnt/usbstor4
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. 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.
NOTE
203
USB - D EVICE / H OST USB Human Interface Device (HID) Support
USB Human Interface Device (HID) Support
The Mx800 series terminal also has built in USB HID support for some devices through the Linux kernel Input Event module. When a HID is plugged into the USB Host port, it is automatically detected and the appropriate USB HID and event drivers are loaded. It is then possible to open, read/write, and close these devices from an application. Currently, the Mx800 series of terminals either partially or fully supports HIDs:
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. 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. 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.
USB Host Scanner
USB Host Mouse
204
CHAPTER 9
TCP/IP Ethernet
The Mx800 series terminal supports TCP/IP networking on the Ethernet port. The network configuration and program APIs are contained in this chapter. The Mx800 series fully support the Linux sockets interface for client and server network programming. The networking API is contained in the svc.h header file and the libvfisvc shared library. Networking is currently supported only on the Ethernet port, the eth0 device.
Network Configuration
Configuration variables are read for network configuration in bringing the interface up at boot time and user control.
Network The following table of configuration variables is read by the system on power up/ Configuration reboot and in bringing the interface up. Either the *DHCP or *IFCONFIG Environment environment variable must be defined to bring up the eth0 network interface. Variables
These configuration variables must be set within the usr1 account. Table 19 Variable Name
*DHCP
Values
1
Definition
If *DHCP is present and the system supports ethernet, then it will attempt to initialize its connection via DHCP. If not DHCP, DNS1 is used as the name server IP address. If not DHCP, DNS2 is used as the name server IP address. If not DHCP, use *IFCONFIG to set the following parameters:
host static IP address netmask broadcast (optional)
*DNS1 *DNS2 *IFCONFIG
IP Address in the form xxx.xxx.xxx.xxx IP Address in the form xxx.xxx.xxx.xxx Per Linux No need to set MAC address as the system will do this for you. Typically used: eth0 xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx
*GATEWAY *TELNET
IP Address in the form xxx.xxx.xxx.xxx 1
Use to define the address of the gateway (router). If *TELNET is present and the system supports Ethernet, then it will start the Telnet server daemon.
205
TCP/IP E THERNET netUP()
netUP()
Activates the Ethernet network interface eth0 for sending and receiving.
NOTE
This function uses the Network Configuration environment variables and either the *DHCP or *IFCONFIG variable must exist. *DHCP takes precedence if both variables exist
Prototype
int result= netUp(void)
Return Values
0 <0 Success Error
206
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 <0 Success Error
207
TCP/IP E THERNET netGetConfig()
netGetConfig()
Returns the network configuration parameters of the eth0 network interface. The network interface must be up.
Prototype
int result = netGetConfig(net_conf_t *net)
Parameters
net
typedef struct { int dhcp; char MAC[18]; char ipaddr[16]; char netmask[16]; char gateway[16]; char dns1[16]; char dns2[16]; } net_conf_t;
Pointer to the network configuration structure to be filled: net_conf_t members short dhcp char MAC[18] char ipaddr[16] char netmask[16] char gateway[16] char dns1[16] char dns2[16] Description 1=DHCP, 0=Static format xx:xx:xx:xx:xx:xx format xxx.xxx.xxx.xxx format xxx.xxx.xxx.xxx format xxx.xxx.xxx.xxx format xxx.xxx.xxx.xxx format xxx.xxx.xxx.xxx
Return Values
0 <0 Succes, interface is up. Error, probably network interface is down.
208
TCP/IP E THERNET netLinkStatus()
netLinkStatus()
Returns the link status of the specified network interface.
Prototype
int result = netLinkStatus(void)
Return Values
1 0 <0 Link is up. Interface down or Ethernet cable is unplugged. Error
209
TCP/IP E THERNET getSysctl()
getSysctl()
Returns the value of the specified kernel parameter.
Prototype
int result = getSysctl(char * varSysctl)
Return Values
1 0 <0 Link is up. Interface down or Ethernet cable is unplugged. Error
210
TCP/IP E THERNET Supported Network Programs
Supported Network Programs
The Mx800 series of terminals API includes support for common networking programs such as ping and FTP file transfers. For FTP file transfers, the FTP server must support passive mode for the data socket connection and the file transfers are always in binary mode. The FTP server must support the following FTP commands:
USER PASS TYPE I PASV RETR CWD STOR QUIT
211
TCP/IP E THERNET netPing()
netPing()
Tests whether the remote host is reachable.
NOTE
This program sends an ICMP message to the remote host asking for acknowledgement.
Prototype
int result = netPing(char *host)
Parameters
host Pointer to remote host either in the xxx.xxx.xxx.xxx IP address format or fully qualified domain name.
Return Values
0 <0 Success Error
212
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
typedef struct{ char ftpHost[32]; char port[8]; char userID[32]; char password[32]; char localFile[64]; char remoteFile[64]; char errorMsg[64]; } ftp_parm_t;
Pointer to the FTP parameter structure. ftpHost In the xxx.xxx.xxx.xxx IP address format or the fully qualified domain name format ftp.site.com FTP port. Defaults to 21 if not specified. FTP user name FTP password Local file name, with directory path (relative to /home/ usr1/) Remote file name:
For ftpGet(), this is the
port userID password localFile
remoteFile
directory pathname and filename.

For ftpPut(), this is the
directory pathname only. errorMsg Returns the verbose error message
Return Values
0 <0 Success, network interface is up. Error, probably network interface is down.
213
TCP/IP E THERNET ftpPut()
ftpPut()
Transfers a file from the terminal to the FTP server.
NOTE
This function logs in to the FTP server, sends the file to the server, and logs off.
Prototype
int result = ftpPut(FTP_parm_t *ftp)
Parameters
ftp Pointer to FTP parameter structure (see ftpGet()). The remoteFile field is the directory pathname only. The resultant filename is the same as the source filename.
Return Values
0 <0 Success Error
214
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 7xxxs does. For instance, value -3, 4 and -5 are never returned by ipp_read() on the Mx800 series of terminals.
215
IPP L EGACY L IBRARY IPP Support for the M x 800 series of Terminals
There is no IPP trap mechanism on the Mx800 series of terminals. The Interac mode support functions are not implemented on the Mx800 series of terminals. Interac support is done through Security Script.
All legacy IPP functions are defined in the header file ippleg.h. Applications must link with the libvfileg.so and libvfisec.so libraries by using -lvfileg and -lvfisec. Applications must call ippOpen() before using the legacy IPP functions listed below.
216
IPP L EGACY L IBRARY ipp_getpin()
ipp_getpin()
This command passes the appropriate parameters to define PIN entry.
Prototype
result = ipp_getpin(key_type, disp_line, min_pin_len, max_pin_len, zero_pin_ok, max_time, pan, working_key, master_key);
int result, key_type, max_time, master_key; char dsp_line, min_pin_len, max_pin_len, zero_pin_ok, *working_key, *pan);
Parameters
key_type dsp_line min_pin_len max_pin_len zero_pin_len max_time pan pointer to Personal Account Number 8...19 characters - null terminated working_key 1DES Mode 3DES Mode 16 characters - null terminated in case of Master Key Session, ignored in case of DUKPT. 120 characters - null terminated, GISKE data block in case of Master Key Session, ignored in case of DUKPT. 0 for Master Key Management, 1 for DUKPT Not used on the Mx800 series of terminals. minimum length of the PIN (4 .. max_pin_len) maximum length of the PIN (min_pin_len ..12) 0 - not permitted, 1 - permitted 1...300 max time in seconds for timeout abort
master_key
1 character: (0...9) in case of Master Key Session, (0...2) in case of DUKPT to select DUKPT engine.
217
IPP L EGACY L IBRARY ipp_getpin()
Return Values
0 -1 -2 -3 Successful PIN Entry Occurring Too many PIN entry requests in a short period - Retry later. Invalid parameter or IPP communication error.
Prior to issuing this command, the setSecurePINDisplayParameters() function must be used to register the PIN feedback callback function and to load the hotspot table. See SetSecurePINDisplayParameters(). Once this function is executed, the touch panel data is no longer accessible to the application and it is routed directly to internal software. As each digit of the PIN is entered, an event is echoed to the application through the callback function. Illegal keys are ignored. Pressing [CLEAR] will abort the session Encryption of the PIN is performed internally by the system hardware immediately after the PIN is entered and [ENTER] is pressed. Raw PIN data is never made available to the Application. After issuing this command, the ipp_read() function must be used to collect the encrypted PIN information.
218
IPP L EGACY L IBRARY ipp_read()
ipp_read()
This function returns the encrypted PIN block generated by ipp_getpin().
Prototype
result = ipp_read(buffer, size);
intresult; unsigned int size; char *buffer;
Parameters
buffer User defined buffer in the application space where the information is to be stored. The number of bytes to be read.
size 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 0 -1 -2 -6 -7 -8 -9 -10 -11 -12 NOTE Number of bytes read IPP is idle Waiting for PIN entry PIN entry occurring Abort PIN entry by Timeout Abort PIN entry by Program Abort PIN entry by CLEAR key Abort with data IPP Communication Error IPP Command Error Zero PIN length Error
Some of the above events occur so quickly that it may not be possible to see every status code. If the return value is >0, the packet is interpreted as given below.
219
For Master Session Key Management, the buffer contains the following packet:
STX packet type delimiter Function key PIN length PIN Block Format Encrypted PIN Block ETX 1H 2AN 1A 1N 2N 2N 16H 1H Start of text, value 02h value 71' value '.' value 0 if function key feature not implemented value 00 or 04 -12 value 01 - format prior to encryption encrypted PIN End of text, value 03h
In case of an input error, the packet looks like:

STX packet type error code 1H 2AN 1N Start of text, value 02h value 71' "1" = No Master Key "2" = account / working key error "3 = PIN length over Max "4 = PIN length under Min / non decimal digit in PIN "6" = Master Key Attributes error "7 = KOF/GISKE Working Key Attributes error ETX 1H End of text, value 03h
For DUKPT Key Management:

STX packet type packet delimiter 00000 KSN 1H 2AN 1A 5N 10-20H Start of text, value 02h value 73' value '.' value: 00000' Key Serial Number: Hex (Leading F's suppressed) Presented only if PIN entered Length is 0 if no PIN entered Encrypted PIN 16H 1H The 64 bit encrypted PIN block represented as 16 hexadecimal digits. End of text, value 03h
ETX
220
In case of an input error, the packet looks like:

STX packet type error code 1H 2AN 1N Start of text, value 02h value 73' "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
221
IPP L EGACY L IBRARY ipp_mac()
ipp_mac()
This function performs a MAC calculation on the user data and returns the resultant value.
Prototype
return = ipp_mac(master_key, working_key, second_key, message, message_length, result); int return; unsigned int message_length; char master_key, second_key, *working_key, *message, *result;
Parameters
master_key working_key 1DES Mode 3DES Mode 16 characters, null terminated 20 characters, null terminated GISKE data block ASCII "0...9" selects master key number
second_key message message_length result
ASCII "0...9" selects second key number message to calculate MAC on max 3200, number of characters in message buffer pointer to contain the resultant MAC value
Return Values
1 -1 -2 -3 -4 -5 Successful Master Key Pointer Error Second Key Pointer Error Message length too large Wrong Block Size Communication Error
222
IPP L EGACY L IBRARY ipp_mac()
The resultant MAC value is placed in the users result buffer and is formatted as follows:
Process code field One character, indicates status "0" = no error and MAC follows MAC field 16 character MAC value
The message parameter is blocked into 32-byte blocks and a running calculation is performed on each block. Maximum number of blocks = 100, so maximum message length is 3200 bytes. If the second_key parameter is non-zero then MAC generation starts with the master_key and if the message is longer than 1 32-byte block, the final block will be processed using the second_key for enhanced security.
223
IPP L EGACY L IBRARY ipp_abort()
ipp_abort()
This function aborts PIN collection.
Prototype
return = ipp_abort(void); int return;
Return Values
0 -1 Successfully aborted Failure to abort
On successful return, the Application gets control of the keyboard and display.
NOTE
If PIN collection is not running when this function is called, then a 0 is returned.
224
IPP L EGACY L IBRARY ipp_diag()
ipp_diag()
This function executes various IPP diagnostics. The application can use this function to check information on the IPP firmware as well as perform 1DES test encryptions.
Prototype
return = ipp_diag(test_type, result, master_key); int return, test_type, master_key;
char *result;
Parameters
test_type Type of test that the user wants to perform: 0 1 2 3 4 result ROM Checksum Test Serial Number Test ROM Version Number Test Master/Session Encryption Test DUKPT Encryption Test
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 slot # to use when performing test #3. DUKPT engine to use when performing test #4.
master_key
Return Values
0 -1 Success Error
The result buffer will contain the following, according to the test_type specified: Table 20 Test_type
0 1 2 3-4
Result buffer
Buffer contains checksum Serial number if present Version number Refer to the Remarks section of ipp_read().
225
IPP L EGACY L IBRARY ipp_diag()
All strings are null terminated. For DUKPT and Master/Session Encryption tests, the usual prompts for necessary information have been hard coded for the purpose of this diagnostic. The values for this information are:
M/S working_key DUKPT working_key Card Number PIN NOTE 1234567890123456 DUKPT ENCRYPTION 4012345678901 1234
Keys loaded for Master/Session and DUKPT must be 1DES compatible.
226
IPP L EGACY L IBRARY select_key_mgmnt()
select_key_mgmnt()
This function selects the Key Management method. It allows selection of Master/ Session and DUKPT methods, either Single DES (1DES) or Triple DES (3DES) as well as Secure Messaging and Zero Key support.
Prototype
return = select_key_mgmnt(kmm, demf); int return; unsigned char kmm, demf;
Parameters
kmm 1 char binary encoded 7 6 5 4 3 2 1 0 -------------------000 -----001 -----010 -----011 ----0------1-----0------1-----0------1-----0------1-----0------1------1DES Master/Session (default) Mixed Mode (1DES & 3DES GISKE) 3DES GISKE Master/Session Secure Messaging (not supported on Mx800 series) DUKPT Engine "0" 1DES (default) DUKPT Engine "0" 3DES Zero Key Support OFF (default) Zero Key Support ON Empty GISKE session key support OFF (default) Empty GISKE session key support ON Do not clear the keys Clear all MS keys and KLK key MAC Empty Working Key Support OFF (default) MAC Empty Working Key Support ON
227
IPP L EGACY L IBRARY select_key_mgmnt()
demf
1 char binary encoded 7 6 5 4 3 2 1 0 DUKPT Engine "1" -------0 -------1 DUKPT Engine "2" ------0------11DES DUKPT (default) 3DES DUKPT 3DES GISKE Master/Session 1DES DUKPT (default) 3DES DUKPT
XXXXXX--
Reserved
Return Values
0 -10 -11 Success IPP Communication Error IPP Command Error
228
IPP L EGACY L IBRARY get_key_mgmnt()
get_key_mgmnt()
This function is used to check the current Key Management settings.
Prototype
return = get_key_mgmnt(kmm, demf); int return; char *kmm, *demf;
Parameters
kmm 1 char binary encoded 7 6 5 4 3 2 1 0 -------------------000 -----001 -----010 -----011 ----0------1-----0------1-----0------1-----0------1-----0------1------1DES Master/Session (default) Mixed Mode (1DES & 3DES GISKE) 3DES GISKE Master/Session Secure Messaging (not supported on Mx800 series) 1DES DUKPT (default) 3DES DUKPT Zero Key Support OFF (default) Zero Key Support ON Empty GISKE session key support OFF (default) Empty GISKE session key support ON MS keys or KLK key present All MS keys and KLK key are clear MAC Empty Working Key Support OFF (default) MAC Empty Working Key Support ON
229
IPP L EGACY L IBRARY get_key_mgmnt()
demf
1 char binary encoded 7 6 5 4 3 2 1 0 DUKPT Engine "1" -------0 -------1 DUKPT Engine "2" ------0------11DES DUKPT (default) 3DES DUKPT 1DES DUKPT (default) 3DES DUKPT
XXXXXX--
Reserved
Return Values
0 -10 -11 Success IPP Communication Error IPP Command Error
The returned values will be placed in the users variables kmm and demf.
230
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 Functions
The succeeding sections discusses the library API functions used in the Mx800 series of terminals to support the RF Card Reader.
231
C ONTACTLESS RF C ARD R EADER M ODULE RFCRlibVersion()
RFCRlibVersion()
Prototype
int RFCRlibVersion(char *libVersion)
Parameters
libVersion Pointer to read in the RFCR library version, in the form: xx.yy.zz
Return Values
>=0 <0 Success Error
232
C ONTACTLESS RF C ARD R EADER M ODULE RFCRInit()
RFCRInit()
RFCRInit() performs device initialization, opens, and configures the serial port. The device handle that is returned on success can be used by the applications.
Prototype
int RFCRInit(void);
Return Values
>0 <0 Success, and the device handle is returned. Error -ENXIO if no RFCR Module detected
233
C ONTACTLESS RF C ARD R EADER M ODULE RFCRGetVersion()
RFCRGetVersion()
Prototype
int RFCRGetVersion(char *fwVersion);
Parameters
fwVersion Pointer to read in the RFCR firmware version
Return Values
0 <0 Success Error -EBADF if not initialized >0 NAK error
234
C ONTACTLESS RF C ARD R EADER M ODULE RFCRPing()
RFCRPing()
Tests if the RFCR module is alive and responding
Prototype
int RFCRPing(void);
Return Values
0 <0 Success Error -EBADF if not initialized
235
C ONTACTLESS RF C ARD R EADER M ODULE RFCRReset()
RFCRReset()
Configures the RESET line of the RFCR module.
Prototype
int RFCRReset(int onOffPulse);
Parameters
onOffPulse 0 = OFF 1 = ON 2 = PULSE (OFF then ON)
Return Values
0 >0 <0 Success, for OFF Success, for ON or PULSE. Return value is the RFCR handle Error -EBADF if not initialized
236
C ONTACTLESS RF C ARD R EADER M ODULE RFCRSetAntenna()
RFCRSetAntenna()
Configures the Antenna control of the RFCR module.
Prototype
int RFCRSetAntenna(short onOff);
Parameters
onOff 0 = Disable the RF Antenna 1 = Enable the RF Antenna
Return Values
0 <0 Success, for OFF Error -EBADF if not initialized >0 NAK status
237
C ONTACTLESS RF C ARD R EADER M ODULE RFCRSetIndicator()
RFCRSetIndicator()
Configures the optional indicator controls of the RFCR module. The controllable optional LED is located on the right side of the reader face. The LED on the top left side of the reader face is not controllable.
NOTE
The current RFCR hardware does not support the optional buzzer control.
Prototype
int RFCRSetIndicator(int led, int buzz);
Parameters
led 0 = disable LED 1 = enable LED for 100 ms 2 = enable LED for 200 ms ... 15 = enable LED for 1500 ms buzz Not used at this time
Return Values
0 <0 Success Error -EBADF if not initialized >0 NAK status
238
C ONTACTLESS RF C ARD R EADER M ODULE RFCRGetCardPayload()
RFCRGetCardPayload()
Prototype
int RFCRGetCardPayload(char* buff, int maxlen);
Parameters
buff maxlen Pointer to store the Card Payload Packet Maximum size of buff
Return Values
>0 <0 Success, with the length of the Card Payload Packet data read. Error
239
C ONTACTLESS RF C ARD R EADER M ODULE RFCRParseCardPayload()
RFCRParseCardPayload()
Parses the Card Payload Data to the CardPayload structure.
Prototype
int RFCRParseCardPayload(CardPayload* payLoad, char* buff, int len);
Parameters
payload buff len Pointer to CardPayload structure to store the data Pointer to Card Payload Packet data Size of the Card Payload Packet data in buff
Return Values
1 not 1 Success Any return value that is not 1 (either < = 0 or >1) are considered errors.
The CardPayload structure is:

typedef struct { char status;// see below char cardType;// see below short trk1Start;// index to beginning of Track 1 data short trk1Length;// length of Track 1 data short trk2Start;// index to beginning of Track 2 data short trk2Length;// length of Track 2 data unsigned char crc1;// LSB of CRC unsigned char crc2;// MSB of CRC } CardPayload;
Please refer to the Omni 7xxx and Mx800 Contactless Modules Programmers Manual, VPN 23309 for the latest status code and the card type values. Track 1 and Track 2 data will contain the Start and End Sentinels.
240
C ONTACTLESS RF C ARD R EADER M ODULE RFCRUpdateFW()
RFCRUpdateFW()
Upgrades the RFCR Module firmware.
Prototype
int RFCRUpdateFW(char* fileName, int removeFile, FWUpdateCallback *displayProgress);
Parameters
fileName Pointer to name of the update hex file. The filename shall not have any path prefix, and the file is assumed to be in the /lib/ modules directory. 0 = do not remove the file 1 = remove the hex file after a successful update displayProgre ss Pointer to callback function to process the progress messages. If NULL, no progress or error messages are provided (except the return code).
removeFile
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 not 1 Success Any return value that is not 1 (either < = 0 or >1) are considered errors.
241
C ONTACTLESS RF C ARD R EADER M ODULE RFCRPurge()
RFCRPurge()
Purges any pending input from the reader.
Parameters
void RFCRPurge(void);
242
C ONTACTLESS RF C ARD R EADER M ODULE RFCRInputPending()
RFCRInputPending()
Returns the number of bytes available for reading.
Prototype
int RFCRInputPending(void);
Return Values
0 >0 <0 No data available Number of bytes available for reading Error
243
C ONTACTLESS RF C ARD R EADER M ODULE RFCRRawWrite()
RFCRRawWrite()
Sends raw data to the RFCR module.
Prototype
int RFCRRawWrite(unsigned char *buff, int len);
Parameters
buff len Pointer containing the data to send to the RFCR module Number of bytes to send
Return Values
>0 <0 Number of bytes written Error
244
C ONTACTLESS RF C ARD R EADER M ODULE RFCRRawRead()
RFCRRawRead()
Reads raw data from the RFCR module.
Prototype
int RFCRRawRead(unsigned char *buff, int maxlen, int msecs);
Parameters
buff maxlen msecs Pointer to store the data read from the RFCR module Maximum size of the buffer Maximum wait time for data to arrive
Return Values
>=0 <0 Number of bytes read Error
245
C ONTACTLESS RF C ARD R EADER M ODULE RFCRAddCRC()
RFCRAddCRC()
Calculates the CRC of the data contained in buff and insert it at the offset position of the buffer.
Prototype
void RFCRAddCRC(char* buff, int offset);
Parameters
buff size Buffer containing the Command Frame to calculate the CRC. The position in the buffer to insert the CRC (and the size of the data to CRC), usually 14 for Command Frame.
246
C ONTACTLESS RF C ARD R EADER M ODULE RFCRCheckCRC()
RFCRCheckCRC()
Prototype
int RFCRCheckCRC (char* buff, short len, unsigned short* calcCRC);
Parameters
buff Buffer containing the data and CRC, with the CRC being the last 2 bytes of the buffer data. Length of the data including the CRC Pointer to store the calculated CRC
len calcCRC
Return Values
1 0 CRC is valid CRC did not match
247
C ONTACTLESS RF C ARD R EADER M ODULE RFCRReceiveACKFrame()
RFCRReceiveACKFrame()
Receives an ACK frame from the RFCR module. The contents of the ACK frame specify whether the reader accepted the command. Depending upon the command, the ACK frame may provide additional information.
Prototype
int RFCRReceiveACKFrame (char* buff);
Parameters
buff len calcCRC Pointer to store the ACK frame. It should have space for 16 bytes. Length of the data including the CRC Pointer to store the calculated CRC
Return Values
>0 <0 Success, with the number of bytes read Error
248
C ONTACTLESS RF C ARD R EADER M ODULE RFCRReceiveDataFrame()
RFCRReceiveDataFrame()
Receives a data frame from the RFCR device. The Size of the data frame may vary.
Prototype
int RFCRReceiveDataFrame (char* buff, int maxlen);
Parameters
buff Pointer to store the ACK frame. The number of bytes returned may vary, but the buff should be able to accept the maximum possible size of the data frame. Maximum size of buff.
maxlen
Return Values
>0 <0 Success, with the number of bytes read Error
249
C ONTACTLESS RF C ARD R EADER M ODULE RFCR Return Values
RFCR Return Values
Along with the generic error returns in errno.h, the RFCR specific error returns are as follows (most are from the RFCRUpdateFW() routine): Table 21 Error
No File Bad File Enter ISP Error Autobaud Error Frequency Error Erase Error Receive Timeout File Read Error Big Record Error Burn Error Cleanup Error Invalid Data Frame Invalid Card Payload Buffer Too Small
RFCR Return Values Value

-401 -402 -403 -404 -405 -406 -407 -408 -409 -410 -411 -420 -422 -430
250
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 HIDs 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.
251
I NPUT E VENTS inputOpen
inputOpen
Prototype
int inputOpen(int vfi_device)
Parameters
vfi_device The device desired to open as defined in vfiInputAPI.h header file as follows:
VFI_TOUCHPAD VFI_USB_KBD VFI_USB_SCANNER VFI_USB_MOUSE
Return Values
This function will return a value greater than 0 upon successful execution, corresponding to the handle of the opened device, otherwise, it will return a negative value.
252
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.
253
I NPUT E VENTS inputClose()
inputClose()
Prototype
int inputClose(int inHdl)
Parameters
inHdl The device handle obtained from opening the device with inputOpen().
Return Values
The function will return a 0 upon success or a negative value if an error occurred while trying to close the device. When the device is closed, any illuminated LEDs are turned off.
254
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. vpInit() vpParseFields()
Visual Payments Library Functions
vpSendPacket() vpExit() vpVersion() netUp() netPing()
255
V ISUAL P AYMENTS vpInit()
vpInit()
Connects to Visual Payment and starts a thread to monitor the connection. Callback functions for:
Up Channel data received Disconnect Down Channel Request received Down Channel File Status Timeout
Environment variables for XTRMCFG:
*VPAPPNAME = string for TERMINALAPPLICATIONNAME *VPAPPVERSION = string for TERMINALAPPLICATION *VPDOWNPORT = string for Down Channel Port Number. Default is 5016. *VPSERVERADDRESS = string for VP Server Address *VPSERVERPORT = string for VP Server Port. Default is 5014.
Prototype
int vpInit(vp_parm_t *pstVP); typedef struct { int iOptions;
char chSeperator; void *fnUpData; void *fnUpDisconnect; int *fnDownReq;
void *fnDownFileStatus; void *fnTimedOut; } vp_parm_t;
Parameters
iOptions Bit defined options: 0x0002 Disable Auto ACKs 0x0001 Force Download chSeparator Field separator character
Return Values
0 256
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 pszField chSep Input Data Stream to parse Pointer to array of vp_field_t to store parsed strings Pointer to field separator character string
Return Values
First index usually returns the command in key, with no value.
257
V ISUAL P AYMENTS vpSendPacket()
vpSendPacket()
Sends the packet to VP server after adding the wrappers. This is used for both Up and Down Channel messages.
Prototype
int vpSendPacket(int iFd, int iOptions, unsigned short ushMsgNum, char *pchOutBuf, unsigned short ushLength);
Parameters
iFd iOptions Socket fd Bit defined options: 0x0002 Wait for ACK ushMsgNum 0 = Message Number included 0 > Insert this Message Number pchOutBuf ushLength Pointer to data buffer to send Length of payload data
Return Values
Returns bytes sent or error. The VP library will wait for the ACK and do the retries, if required, before returning.
258
V ISUAL P AYMENTS vpExit()
vpExit()
Closes the VP connections, frees the memory, and then exits the application.
Prototype
int vpExit(int iFd);
259
V ISUAL P AYMENTS vpVersion()
vpVersion()
Returns the VP library version string in the form xx.xx.xx.
Prototype
void vpVersion(char *pchVersion);
260
V ISUAL P AYMENTS Visual Payments Callback Functions
Visual Payments Callback Functions
fnDownReq() fnDownFileStatus()
fnUpData() fnUpDisconnect() fnTimedOut()
261
V ISUAL P AYMENTS fnDownReq()
fnDownReq()
Called after a REQ packet is received on the Down Channel. The application can:
allow or disallow this command to proceed perform the request and detail the result.
If this callback function is not provided, all REQ commands will be allowed to run. VP library will send the ACK prior to issuing this callback.
NOTE
System mode may use this to put up downloading status.
Prototype
int fnDownReq(int iDownFd, int iFieldCount, vp_field_t *pszFields);
typedef struct { char key[MAX_KEY_SIZE]; char value[MAX_VALUE_SIZE]; } vp_field_t;
Parameters
iDownFd iFieldCount pszFields Socket fd of Down Channel. Number of fields in the array. Pointer to array of field structure.
Return Values
>0 0 -1 -2 -3 -4 Allow Success, application performed the request Disallow, and dont ask again Disallow, terminal busy, try again Failure, application performed the request Failure
262
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 pszFields Number of fields in the array. Pointer to array of field structure
263
V ISUAL P AYMENTS fnUpData()
fnUpData()
Called when response data is received on the Up Channel. VP library will send the ACK prior to issuing this callback.
Prototype
int fnUpData(unsigned short ushDataSize, unsigned short ushMsgNum, char *pchData);
Parameters
ushDataSize ushMsgNum Contains the size of data in pchData. Contains the Message Number.
264
V ISUAL P AYMENTS fnUpDisconnect()
fnUpDisconnect()
Called when the Up Channel is disconnected. Application should call vpExit() to clean up.
Prototype
void fnUpDisconnect(void);
265
V ISUAL P AYMENTS fnTimedOut()
fnTimedOut()
Called when ACKs are not received within the timeout period for the Down Channel Response message.
NOTE
For the Up Channel, the application is responsible for the protocol timeouts.
Prototype
void fnTimedOut(void);
266
V ISUAL P AYMENTS Network/Ethernet Library Functions Required by Visual Payments
Network/ Ethernet Library Functions Required by Visual Payments
ftpPut() ftpGet() netLinkStatus() netDown() netUp() netPing()
267
V ISUAL P AYMENTS ftpPut()
ftpPut()
Gets a file from the VP Server. FTPHost in form of IP address xxx.xxx.xxx.xxx or fully qualified domain name ftp.site.com. Translation of directory path / to \ to be done by the VP server. VP server must support the following FTP commands:
USER PASS TYPE I PASV RETR CWD STOR QUIT
Prototype
int ftpPut(FTP_parm_t *pstFTP);
typedef packed struct{ char ftpHost[]; char port[]; char userID[]; char password[]; char localFile[]; char remoteFile[]; char errorMsg[]; } FTP_parm_t;
268
V ISUAL P AYMENTS ftpGet()
ftpGet()
Sends a file to the VP Server.
Prototype
int ftpGet(FTP_parm_t *pstFTP);
269
V ISUAL P AYMENTS netLinkStatus()
netLinkStatus()
Returns the link status of the eth0 network interface.
Prototype
int netLinkStatus();
270
V ISUAL P AYMENTS netDown()
netDown()
Deactivates the network interface.
Prototype
int netDown();
271
V ISUAL P AYMENTS netUp()
netUp()
Activates the network interface.
Prototype
int netUp();
272
V ISUAL P AYMENTS netPing()
netPing()
Pings the remote host.
Prototype
int netPing(char *host);
273
V ISUAL P AYMENTS XFTP Commands
XFTP Commands
The succeeding sections lists all XFTP commands.
XFTPGET XFTPPUT XFTPDEL
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. 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. 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.
274
APPENDIX A
IPP MS and DUKPT Communications Packets
This appendix describes the required packet commands of the IPP for MS (Master Session) or DUKPT operations supported by the Mx800 series.
Advanced Programming in IPP
The differences between the Verix and Verix V IPP MS and DUKPT from the Mx800 series IPP (XMIPP8) are summarized in Table 22. Table 22 IPP
Secure Message Mode Spain SEMP/4B Key tagging DUKPT Engines
Differences in Mx800 series IPP IPP6

No Yes Yes 1
IPP7
Yes Yes No 1
VVIPP
No No No 1
IPP8
Yes Yes No 3
VVIPP8
No No No 3
MXIPP8
No No No 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.
275
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS Packets
<SI>15SPAIN<SO> Set IPP6 Key Management Mode Spain mode is not supported and switching to Spain mode erases keys. This is done because some programs depend on this feature to erase keys. <SI>17xyz<SO> Set IPP7 Key Management Mode SM mode is not supported but switching to SM mode erases keys. This is done because some programs depend on this feature to erase keys. <SI>02<SO> Set Master Key IPP7 can hold a maximum of three (3) triple-length keys. In VVIPP, all ten key locations can hold a single-, double-, or triple-length key. <STX>75..<ETX> DUKPT Accept and Encrypt PIN/Data Authentication Response ANSI DUKPT MAC is only defined for 3DES DUKPT. VVIPP returns error code 8 if ANSI DUKPT MAC is requested when using 1DES DUKPT. IPP7 returns undefined results in this case.
Packets
The packet set is similar to that used for external PIN pads, such as the PINpad 1000, however, unlike previous IPPs, the Omni 33XX IPP is a software module running on the main CPU. Previous IPPs used dedicated microcontrollers connected to the main CPU through a serial port. In Omni 33XXIPP the COM5 serial port is emulated in software along with all IPP functionality. The IPP command and response packets can be divided into the following categories:

NOTE
Common Packets: Packets used in both MS and DUKPT. MS-Specific Packets: Packets used while doing MS. DUKPT-Specific Packets: Packets used while doing DUKPT. MAC-Specific Packets: MAC generation of received message packets. Omni 33XX IPP does not support Spain SEMP/4B mode or Secure Messaging (SM) mode.
The IPP supports both MS and DUKPT key management modes concurrently. Also, the IPP supports MAC processing while doing MS or DUKPT. Table 23 lists packets used in both MS and DUKPT sessions. Table 23 Packet
01 05 06 276
Common Packets Description

Interactive diagnostic routine Transfer serial number Request PIN pad serial number
Table 23 Packet
09 11 12 13 14 15 17 18 M04
Common Packets (Continued) Description

Response to Packet 01 PIN pad connection test Dummy packet Select baud rate Response to Packet 01 Set IPP key management mode Set IPP7 key management mode Check IPP7 key management mode Read Permanent Unit Serial Number (IPP8 Emulation)
Table 24 lists packets supported by IPP for MS. Table 24 Packet

02 04 07 08 Z60 Z63 71 Z66 Z67 72
IPP Supported Packets for MS Description

Load/set master key Check master key 'Dummy' DES reliability test Select master key Accept and encrypt PIN (VISA mode) Accept and encrypt PIN, custom PIN entry requirements (VISA mode) Response PIN block MAC processing Return MAC Cancel MAC session
Table 25 lists packets supported by IPP for DUKPT. Table 25 Packet

90 91 75 78 76 71 Z60 Z63 Z69 73 19 25
IPP Supported Packets for DUKPT Description

Load initial key Confirm initial key Encrypt PIN/authentication data response Encrypt PIN/authentication data test request PIN entry test request Response PIN entry test request of 76 Accept and encrypt PIN request (VISA mode) Accept and encrypt PIN, custom PIN entry requirements (VISA mode) Accept and encrypt PIN/data authentication request (VISA mode) Response PIN block Select a DUKPT Engine (IPP8 Emulation) Check the DUKPT Engine (IPP8 Emulation)
277
Packet The IPP only responds to commands that have the proper packet format. The Acknowledgement packet can be in the form of <STX>msg<ETX>[LRC]or <SI>msg<SO>[LRC] and Timing according to the specific command.
The IPP returns <ACK> within 20ms to the terminal when it receives a properly framed packet with a valid LRC. When other framing is received for a command that requires <STX><ETX> framing (for example, <SI><SO>, <SI><ETX>, or <STX><SO>), <ACK> is returned if the LRC is valid; only the specified framing is processed. This rule also applies to <SI><SO> packet commands. The IPP does not act on an incorrectly formatted packet. This includes a packet with a wrong header, wrong trailer, wrong field separator, an out of range indexing, or incorrect packet length. An example of a packet that has an out of range indexing would be packet 02, master key address = 15. The response message from the IPP follows the <ACK> if the packet command has a response. However, the timing varies from different commands.
Encryption There are two methods of PIN encryption in IPP:

MS DUKPT
MS Method IPP encrypts the customer's PIN according to the ANSI X9.8 standard and the ANSI X9.24 master key management method, based on the ANSI X3.92 DES algorithm implemented in the IPP firmware. The encryption during a transaction is as follows:
1 The master device sends a private communication key (or working key) to the
IPP, where it is decrypted using the currently selected master key. An account number and PIN are also entered to IPP through the master device.
2 The IPP generates the clear text PIN block using the account number and
PIN.
3 Using the decrypted working key, the IPP encrypts the PIN block using the
DES algorithm and working key, then sends the encrypted PIN block to the master device.
4 The master device appends the encrypted PIN block to a request packet and
forwards the completed request packet to the host.
278
The following illustrates an MS encryption session. Master Device

1 Forwards the encrypted working
IPP
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.
279
The following illustrates the DUKPT method of encryption.

Master Device
1 Forwards the account number
IPP
and PIN to the IPP.
1 Creates the PIN block. 2 Encrypts PIN block with the
generated PEK.
3 Sends the PIN block and current
KSN (key serial number) to the master device.

2 Appends the PIN block and KSN
to the request packet.

3 Forwards the packet to the host.
Figure 2
DUKPT Session Encryption Example
Constraints The known software constraints for IPP are:

All communication must be asynchronous, half-duplex, 1200/2400/4800/9600/ 19200 baud, 7 data bits, even parity, and 1 stop bit (7E1). Packet length is limited to 255 characters.
NAKs When the IPP receives NAK, it retransmits the last message and increments a
NAK counter for that communication session. If more than three NAKs are received during any attempt to transmit the same item, the transmitting party send an EOT, terminating the session.
Time Outs During a communication session, the IPP or the terminal times out if it does not
receive the expected communication within 15 seconds. The unit sends an EOT to terminate the communication session.
Key Insertion This section describes MK insertion and DUKPT initial PIN encryption key
insertion. Master Key Insertion For each master key injection session, the IPP checks to see if it is the first time that user tried to load the master key. If it is the first time, the IPP clears all master keys to zero before loading a new master key.
NOTE
All master keys must be loaded in the same key injection session, otherwise the previous master key is erased in the next master key injection session. A master key injection session is the duration of the power level is maintained in the IPP. The master key insertion rule does not apply to the GISKE key loading key (KLK).
280
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS IPP7
The terminal or master device uses Packet 02: Transfer Master Key to transfer the master keys into the IPP for MS. DUKPT Initial PIN Encryption Key Insertion The terminal or master device uses DUKPT Packet 90: Load Initial Key Request to load the initial PIN encryption key into the IPP for DUKPT.
Entering a PIN Packets Z60, Z63, and Z69 are used to get and encrypt a PIN from the user. Z63
is similar to Z60, but allows more options for PIN entry, such as minimum and maximum PIN length and echo character. Z69 is similar to Z60, but does DUKPT MAC processing as well as PIN encryption using the same DUKPT key.
Restrict the Speed PIN encryption is limited to one per 30 seconds on average to deter an exhaustive of the PIN PIN search. The algorithm is best explained in terms of tokens in a bucket. Encryption A PIN encryption request is only accepted if there is a token in a bucket. A token Operation
is placed in the bucket every 30 seconds, with a maximum of 127 tokens allowed in the bucket. (The number of tokens in the bucket is maintained across power cycles.) Every time a PIN is entered, a token is removed from the bucket. If there is no token in the bucket, the PIN entry request returns an error. This allows an average of one PIN encryption per 30 seconds, but over a long period of time. The intention is that under normal use PIN entry is not denied.
IPP7
This section discusses IPP7-specific features for Omni 33XX IPP. Omni 33XX IPP7 is backward compatible with IPP6 and IPP5. Exceptions to this rule are noted.
GISKE GISKE (Global Interoperable Secure Key Exchange) is an industry standard key
block format for secure transfer of secret keys between two devices that share a secret key. Both master and session keys can be in GISKE format. The GISKE KLK (Key Loading Key) is used to encrypt and authenticate master keys. Master keys can be remotely updated using this key. GISKE is designed for secure transfer of double- and triple-length 3DES keys. For more details on GISKE refer GISKE Key Block Spec, VPN 22986.
Key Management The rules for key management switching (see Packet 17: Set IPP7 Key Switching Management Mode) are shown in Table 26.
Key NC = no change E = all keys erased 1K = valid 1DES keys (single-length keys) retained, other keys erased 2/3K = valid 3DES keys (double- and triple-length keys) retained, other keys erased
281
Table 26 Rules
Key Management Switching Rules To 1DES (VISA)

NC E 1K E E
To 1DES (SPAIN)a
E NC E E E
To Mixed Mode
NC E NC E E
To 3DES
2/3K E 2/3K NC E
To SMa
E E E E NC
From 1DESb (VISA) From 1DESa (SPAIN) From Mixed modec From 3DESd From SMa
Key Mode
1DES onlyb
1DES and 3DES Key Usage Rulese

Load and use of 1DES MS keys allowedf Load KLK allowed Load 3DES master keys allowed Use of 3DES master keys not allowed Load 3DES session keys not allowed Use of 3DES session keys not allowed Key attributes verifiedg, except key usage = AN ANY is allowed GISKE key block verifiedh
Mixed modec
Load and use 1DES or 3DES MS keys allowed Load KLK allowed 1DES master keys used for 1DES session keys 3DES master keys used for 1DES and 3DES keys Key attributes verified, except: key usage = AN ANY is allowed GISKE key block verified
3DES onlyd
Load and use 3DES MS keys allowed Load KLK allowed Load 1DES master keys not allowed Use of 1DES master keys not allowed Load 1DES session keys not allowed Use of 1DES session keys not allowed Key attributes verified; no exceptions allowed GISKE key block verified
a. b. c. d. e. f. g. h.
Spain and SM modes not supported in Verix V. Keys are erased as specified. Least secure mode. For transition period. Most secure mode. The key management register is set using Packet 17: Set IPP7 Key Management Mode. All DUKPT related keys, counters, and registers are erased when the IPP KM switches between 1DES DUKPT and 3DES DUKPT. Other MS related information remains untouched. Key attributes verified means that when a key stored in the IPP is used, the IPP must validate the content of all key attributes. The attributes of the key are validated against the GISKE specification acceptable for that command. GISKE key block verified means that when receiving a key block, the IPP must validate both the key block binding method of the key block and the content of the header. The header of the key is validated against a list of headers acceptable for that command.
282
Using a Session Key Loading the Session Key

3DES session keys are only loaded in GISKE cipher text under the protection of the indexed master key, as long as that key has its attribute set to KEK (key usage attributes = K0). The master key must be 3DES. The version of the incoming key is not checked or saved. The usage attribute of the incoming working key is checked, but is not saved. The GISKE key length decryption rule is applied. The length of the master key must be greater or equal to the length of the working key. 1DES session keys in key-only format are loaded in cipher text under the protection of the indexed master key, if that key has its attribute set to ANY or KEK (key usage attributes = K0). The master key can be a single-, double-, or triple-length key. 1DES session keys in GISKE format are loaded in cipher text under the protection of the indexed master key, if that key has its attribute set to KEK (key usage attributes = K0). The version of the incoming key is not checked or saved. The usage attribute of the incoming working key is checked, but not saved. The master key can be a single-, double-, or triple-length key. Master Key for PIN Encryption Where the PIN Entry zero session key method for 1DES is used, the current master key must be tagged ANY or PIN ENCRYPTION. Where the tagged zero GISKE session key method for 3DES is used, the current master key must be tagged for the specified purpose key usage =

NOTE
P0 - PIN ENCRYPTION Key Algorithm = 'T' -TDES for double or triple-length keys D - DES for single-length key AN ANY Zero GISKE session key for 3DES means all fields are zero in the GISKE key block.
If zero GISKE support is disabled, the zero GISKE session key causes an error response from the IPP. The zero session key support is enabled or disabled through the KM flag. Zero GISKE session key support (PIN entry) is enabled or disabled through the KM flag.
283
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 Attribute Register
[XX]
Key Attributes Value

AN D0 I0 T0 K0 G0 M0 P0 V0 C0 B0 00 10 20 30 40 50 60
Definition
ANY: Key is available in IPP, but the Key was not loaded using GISKE format. Data encryption IV Control vector Key encryption or wrapping MAC generation MAC verification PIN encryption PIN verification CVK: card verification key BDK: base derivation key [A] ISO 9797-1, MAC algorithm 1 56 bits ISO 9797-1, MAC algorithm 1112 bits ISO 9797-1, MAC algorithm 2112 bits ISO 9797-1, MAC algorithm 3112 bits ISO 9797-1, MAC algorithm 4112 bits ISO 9797-1, MAC algorithm 556 bits ISO 9797-1, MAC algorithm 5112 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
284
when the version is less than the current key version, an error returns and the IPP rejects the new key The key version comparison is only compared to the key it is replacing, not to any other keys.
NOTE
Table 28 lists the key length register values for 1DES, 3DES, and three-key 3DES. Table 28 Length
1DES 3DES 3-Key 3DES Reserved
Key Length Register Values Comments

Single-length key: Key length register = 00 Double-length key: Key length register = 01 Triple-length key: Key length register = 10 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.
285
KLK is present and cipher text is being loaded that is encrypted with the previous KLK, has the correct key version and the key attribute is not equal to KEK, the IPP returns an error. KLK is present and cipher text is being loaded that is encrypted with the previous KLK, has the correct key version and the key attribute is equal to KEK, the IPP stores the KLK and its attributes. KLK is not present and cipher text is being loaded that is encrypted with the previous KLK, has the correct key version, the key attribute KEK value has no effect, the IPP returns an error.
3DES All 3DES key loads are in GISKE format. 3DES master keys are loaded in clear
text without cryptographic protection if the KLK present flag is clear in the IPP. The MAC value is all zero bytes. The version of the incoming key is checked against the stored version. The version of the stored key is the version carried in the GISKE message. The stored key attribute is set to that in the GISKE message. 3DES master keys load in cipher text under the protection of the KLK if the KLK present flag is set. The KLK must be 3DES. The version of the key is checked against the stored version. The version of the stored key is the version carried in the GISKE message. The stored key usage attribute is set to that in the GISKE message. The rules for 3DES are:
KLK is present (the current key attribute register in the IPP is GISKE format) and clear text 3DES master key is being loaded, the IPP returns error KLK is not present (the IPP KLK present flag is clear) and clear text 3DES master key is being loaded, the IPP stores the 3DES key KLK is present (the current key attribute register in the IPP is GISKE format) and cipher text 3DES master key is being loaded with an incorrect key version, the IPP returns an error KLK is present (the current key attribute register in the IPP is GISKE format) and cipher text 3DES master key is being loaded with the correct key version, the IPP decrypts and stores the 3DES key master key attribute equal to the GISKE format length and equal to 3DES KLK is not present (the IPP KLK present flag is clear) and cipher text 3DES master key is being loaded, the IPP returns an error
286
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 09 can hold single-, double-, or tripleAddressing length DES keys. Omni 33XX IPP7 can hold at most three triple-length keys. Clear Text GISKE The following are VeriFone-proprietary rules for GISKE key block loading, and are Key Block Loading not part of the ANSI GISKE specification. Rule If the KLK is not loaded, the GISKE key block is loaded in clear text.
The clear-text GISKE key bock must be padded to a length of 120 bytes, as shown in the following examples.
Key
HB KB eHB eKB indicates the header block indicates the key block indicates the encrypted header block indicates the encrypted key block.
GISKE key block: Cipher text GISKE key block for transmit (encrypted with KLK or KEK): Clear text GISKE key block (MAC is all zeros):
8 HB + 24 HB + 24 KB + 8 MAC 8 HB + 48 eHB + 48 eKB + 16 MAC
8 HB + 24 HB + 48 KB + 16 MAC To pad the clear text GISKE key block to a total length of 120 bytes and be consistent with its counterpart (that is, the cipher text GISKE key block), 24 HB is expanded to 48 HB. The high and low nibbles of ASCII are converted to an individual hex value. For example:
D 0x44 expanded HB = 0x34 0x34 0 0x30 0x33 0x30 A 0x41 0x34 0x31 ... (ASCII) (hex) 287
Padded clear text GISKE key block (MAC is all zeros):
8 HB + 48 HB + 48 KB + 16 MAC
288
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS Common Packets
Common Packets
This section presents the packets common to all protocols.
Packet 01: Packet 01 has the IPP run a specified self-diagnostic test. Information on the test Interactive in progress is provided using response packets 9 and 14, depending on the Diagnostic Routine selected test.
Table 29 Packet 01 Format Characteristic
1H 2AN 2N 1H 1H
Data Element
<SI> Packet Type Diagnostic # [dd] <SO> {LRC}
Comments
Shift In, Value: 0Fh Value: 01 2-byte ASCII code of the diagnostic test to run. Shift Out, Value: 0Eh 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
Data Element
<SI> Packet Type [vvv] [dddddd] [p] [bb] [nnnn] <SO> {LRC}
Characteristic
1H 2AN 3AN 6N 1AN 2AN 4N 1H 1H
Comments
Shift in, value: 0Fh Value: 05 PINpad version number Release date -- format: YYMMDD Production facility code Production batch code Serial # for group ID 00019999 Shift out, value: 0Eh Error check
Packet 05 Length:
Packet 05 Example: Set the IPP serial number to 246880401A001234:

<SI>05246880401A001234<SO>{LRC}
289
Table 31
Packet 05 Communication Protocol Transmit Direction IPP
Master Device
<SI>05[vvv][dddddd][p][bb][nnnn] <SO>{LRC}
ACK if LRC NAK if LRC incorrect EOT after 3 NAKs

<SI>05[vvv][dddddd][p][bb][nnnn] <SO>{LRC}
ACK if LRC NAK if LRC incorrect; the IPP
saves serial number

EOT after 3 NAKs
EOT
Packet 06: Request The master device uses this packet to request the serial number from the IPP. If PIN Pad Serial no serial number stored in the IPP, 16 bytes of ASCII zeros will be returned to the Number master device.
Table 32 Packet 06 Format Characteristic
1H 2AN 1H 1H
Data Element
<SI> Packet Type <SO> {LRC}
Comments
Shift In, value: 0Fh Value: 06 Shift out, value: 0Eh Error check
Packet 06 Length:
Request Sample <SI>06<SO>{LRC} Packet Table 33 Packet 06 Format Data Element

<SI> Packet Type [vvv] [dddddd] [p] [bb] [nnnn] <SO> {LRC}
Characteristic
1H 2AN 3AN 6N 1AN 2AN 4N 1H 1H
Comments
Shift In, Value: 0Fh Value: 06 PIN Pad version number Release date, format: YYMMDD Production facility code Production batch code Serial # for Group ID 0001 - 9999 Shift out, value: 0Eh Error check
290
Packet 06 Length:
Response Sample <SI>06246880401A001234SO>{LRC} Packet Table 34 Packet 06 Communication Protocol Master Device
<SI>06<SO>{LRC}
Transmit Direction
IPP
<SI>06[vvv][dddddd][p][bb][nnnn]<SO>{LRC}
ACK if LRC NAK if LRC incorrect,
the IPP saves serial number

EOT after 3 NAKs
EOT
Packets 09 and 14: In response to packet 01, the IPP returns packets 09 and 14 to the master device: Response Packet to Packet 09 is the response packet to packet 01 with diagnostic # 07 (UART Packet 01
Loopback Test).
Packet 14 is the response packet to the packet 01 with diagnostics #00, 01, 02, 03, 06, 08, 09, and 10.
Packets 09 and 14 are in the format shown in Table 35.
291
Table 35
Packets 09 and 14 Communication Protocol Transmit Direction IPP
Master Device 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}
292
Table 35
Packets 09 and 14 Communication Protocol (Continued) Transmit Direction IPP
Master Device 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}
03 PROM Checksum Test

<SI>0103<SO>{LRC}
IPP7 ACK/NAK/EOT
<SI>14xx<SO>{LRC}
where, xx is the one-byte PROM internal checksum. There are two checksums inside the IPP:
The PROM checksum, which is 2-bytes
long and is located at 7FFE/7FFF. This checksum is for manufacturing purposes.

The PROM internal checksum.
293
Table 35
Master Device 06 Serial Number Check

<SI>0106<SO>{LRC}
IPP6 and earlier ACK/NAK/EOT
<SI>14xxxxxxxxxxxxxxxx<SO>{LRC}
where, xxxxxxxxxxxxxxxx indicates the serial number of the IPP. Length is 16 digits, for example, 1234567890123456. ACK/NAK/EOT EOT to terminate process.
07 UART Loopback Test

<SI>0107<SO>{LRC}
IPP7 ACK/NAK/EOT
<SI>09<SO>{LRC}
ACK/NAK/EOT
<SI>09<SUB>PROCESSING<SO>{LRC}
ACK/NAK/EOT
<SI>09<SUB>PROCESSING<SO>{LRC}
294
Table 35
Master Device
08 IPP PROM Version Number

<SI>0108<SO>{LRC}
IPP7 ACK/NAK/EOT
<SI>14IPPx vvvvxxx MM/YY<SO>{LRC}
where:
vvvv: 4-digit software ID number. For
IPP5, 0PGP.
xxx: 3-digit software version number.
For example, xxx = 011 indicates the software version number is 1.1; if 11A (11B, 12D, 21A, and so on), the software is not ECO released and is for test and qualification purposes only. For formal ECO released versions, xxx is all numbers.
MM/YY: date of software.
For example, MM/YY = 05/95 means the software was created May 1995. ACK/NAK/EOT EOT to terminate process.
09 Reset IPP
<SI>0109<SO>{LRC}
IPP7 ACK/NAK/EOT
<SI>14RESET COMPLETE<SO>{LRC}
ACK/NAK/EOT EOT to terminate process. (The IPP restarts. Insert a delay before sending data to the IPP.)
295
Table 35
Master Device 10 Clear IPP

<SI>0110<SO>{LRC}
IPP7 ACK/NAK/EOT
<SI>14CLR COMPLETE<SO>{LRC}
Packet 11: PIN Pad The master device uses this packet to check the connection with the IPP. If the Connection Test connection is good, the master device receives an ACK from the IPP within one
second. Else, it assumes that the IPP is not connected. Table 36 Packet 11 Format Characteristic
1H 2AN 1H 1H
Data Element
Comments
Shift in, value: 0Fh Value: 11 Shift out, value: 0Eh Error check
Packet 11 Length:
Sample Packet <SI>11<SO>{LRC} Table 37 Packet 11 Communication Protocol Transmit Direction IPP
Master Device
<SI>11<SO>{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.
296
Packet 13: Select Omni 33XX supports this packet but it has no effect. Verix-based Omni series Baud Rate terminals do not use an RS-232 interface so do not need this setting. However, it
is supported for compatibility with other IPPs. This packet command selects the baud rate for the RS-232 communication interface. Through packet command 01 diagnostic 00, the current baud rate can be determined. The factory default is 1200 bps. The baud rate setting is stored in backup RAM. After a power cycling memory test or loss of backup battery power, the baud rate setting is reset to the default. Table 38 Packet 13 Format Characteristic
1H 2AN 1N
Data Element
<SI> Packet Type Packet Data
Comments
Shift in, value: 0Fh Value: 13 Baud rate codes: 1 - 5
1 = 1200 bps (default) 2 = 2400 bps 3 = 4800 bps 4 = 9600 bps 5 = 19200 bps
<SO> {LRC}
1H 1H
Shift out, value: 0Eh Error check
Packet 13 Length:
297
Table 39
Master Device
<SI>13x<SO>{LRC}
ACK if LRC okay; NAK if LRC incorrect.
<SI>14yyyyy<SO>{LRC}
where, x = baud rate code

1 2 3 4 5
yyyyy = string for selected baud rate

1200 (default) 2400 4800 9600 19200
The baud rate code must be in the range 15; 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
<SI> 15
Field
Start of packet Packet type
Length
1 2
Comments
Shift in. Control character- 0Fh Set IPP key management mode
298
Table 40
IPP Request Packet 15 Format Field

Packet parameters
Data Element
[Key Code]
Length
4 or 5
Comments
The key management operation mode for the IPP
SPAIN Spain SEMP/4B
mode
VISA IPP mode Other characters no change
[SO] {LRC}
End of packet Block code check
1 1
Shift out. Control character- 0Eh Error check character
Response Packet <SI>15[Key Code]<SO>{LRC} Format Table 41 IPP Response Packet 15 Format Field
Start of packet Packet type Packet parameters
Data Element
<SI> 15 [Key Code]
Length
1 2 4 or 5
Comments
Shift in. Control character- 0Fh Set IPP key management mode The key management operation mode for the IPP:
SPAIN Spain SEMP/4B
mode
VISA IPP mode Other characters no change
[SO] {LRC}
End of packet Block code check
1 1
Shift out. Control character- 0Eh Error check character
If the terminal receives the response without any errors, then it sends ACK to the IPP. The IPP then sends <EOT> { ASCII CODE is 04 } to terminate the session. Packet 15 Example: <SI>15SPAIN<SO>{LRC}
<SI>15VISA<SO>{LRC} ( set Spain SEMP/4B mode) ( 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.
299
Table 42
Packet 15 Format Characteristic

1H 2AN 4AN 1H 1H
Data Element
<SI> Packet Type Packet Data <SO> {LRC}
Comments
Shift In, Value: 0Fh Value: 15 Value: 'IPP2', fixed as password Shift Out, Value: 0Eh Error Check
Packet 15 Length:
MAX: 9 characters MIN: 9 characters Packet 15 Communication Protocol Transmit Direction IPP
Table 43
Master Device
<SI>15IPP2<SO>{LRC}
ACK if LRC NAK if LRC incorrect
<SI>15IPP2<SO>{LRC}
ACK/NAK EOT to terminate process.
Packet 17: Set IPP7 This packet sets or clears a number of control switches in the key management Key Management options register for IPP7 key management configuration. IPP7 supports the Mode following additional functions (as compared to IPP6):
Triple DES (3DES) DUKPT support GISKE MS Key support Zero (0) key support
Note that the new MAC alternatives apply only when GISKE is active, and are selected by key attributes and not the key management switch. For compatibility, the default key management mode for IPP7 is set to IPP5 mode (MS- DUKPT or single DES mode). Once a new key management scheme is selected, it is retained during power cycles. Setting a new mode causes the IPP7 to erase all existing keys or non-volatile security values stored for secure messaging. Incoming Packet <SI>17[KMM][PINER]<SO>{LRC} Format:
300
Table 44
Packet 17 Format Characteristics

1H 2AN 2AH
Data Elements
<SI> Packet Type Key Management Mode [KMM]
Comments
Shift In, value: 0Fh Value: 17 The two ASCII hex digits are concatenated big-endian, to produce a single control byte. The key management mode register (8 bits) in IPP7 is as follows: Bit 0 0 1 0 1 1 0 0 1 1 2 0 0 0 0 Description 1DES MS (default) Mixed mode (1DES and 3DES GISKE) 3DES GISKE MS Secure messaging (not supported in Omni 33XX.
Bit 3 0 1 Bit 4 0 1
Description 1DES DUKPT (default) 3DES DUKPT Description Zero key support off (default) Zero key support on
Bit 5 0
Description Zero GISKE session key support off (default) Zero GISKE session key support on Description N/A Clear all MS master keys and KLK
Bit 6 0 1
301
Table 44
Packet 17 Format (Continued) Characteristics Comments

Bit 7 0 Description MAC empty working key support off (default) MAC empty working key support on
Data Elements
1 DUKPT Engine 1/2 Mode Flag [DEMF]

Note:
1AH
The one ASCII-Hex digit is used produce half of a control byte. Bit 0 0 1 ( DUKPT Engine "1") Description 1DES DUKPT - Default 3DES DUPKT
This field was added for IPP8 emulation.
Bit 1 0 1
( DUKPT Engine "2") Description 1DES DUKPT - Default 3DES DUPKT
Bit 2 ~ 3 ---------Reserved Example Engine= DEMF = 0x30 0x31 0x32 0x33 <SO> {LRC} 1H 1H 0 1 2 3 1 1DES 3DES 1DES 3DES 2 1DES 1DES 3DES 3DES
Shift Out, value: 0Eh Error Check
Packet 17 Length:
302
Packet 17 Set IPP Key Management Mode Master Device

<SI>17[KMM][PINER]<SO>{LRC}
Transmit Direction
IPP
<SI>17[KMM][PINER]<SO>{LR C}
ACK if LRC and key management echo
is OK
NAK if LRC incorrect EOT after 3 NAKs EOT if LRC is correct, but key
management echo is not OK. EOT to terminate process. The IPP saves the new key management accordingly.
NOTE
The default setting of the IPP KM mode is old single DES mode (IPP5/6 = all zeros in the KMM register). When defaulting to IPP5/6 mode, the IPP is also set to default to VISA mode (not SPAIN). When the IPP receives packet 17 to change KM modes (for example, to 3DES or SM mode). the master device must know the new specification and functions associated with the IPP. If the IPP is not in the old single DES mode (IPP5/6), the IPP ignores packet 15 and will not allow itself to be switched to SPAIN mode unless the KMM register is set to IPP5/6 mode. SPAIN mode is a submode of the single DES (IPP5/6) KMM register setting. A change from 1DES to 3DES or mixed mode will disable SPAIN mode. When zero GISKE session key support is enabled (that is, on), the current master key is used for PIN encryption only if packet Z60 has a zero GISKE (3DES) session key and the current master key has its key attribute set to PIN Encryption or ANY. A zero GISKE (3DES) session key means that all fields are zero in the GISKE key block. The master device must delay for at least 500 msec before send a packet to the IPP when the KMM is switched from IPP7 to SM or from SM to IPP7. Switching from SM to IPP7 mode causes a factory reset. The IPP clears the contents of RAM and communication to the IPP is reset to the default, 1200 baud, 7 data bits, even parity, and 1 stop bit (7E1). Changing the MAC empty working key support flag erases all keys (that is, the KLK, MS key, and DUKPT key)
303
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}
304
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 1 KMM setting MS/DUKPT mode vs. SM mode Notes 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. Zero key support is not applicable in 3DES MS mode, due to the key usage rule (that is, single-length key use is not allowed in 1DES MS mode). The IPP stores the setting, but it has no affect on the MS function. 3 MS mode vs. zero GISKE session key support Zero GISKE session key support is not applicable in 1DES MS mode, due to the key usage rule (triple-length key use is not allowed in 3DES MS mode). The IPP stores the setting, but it has no affect on the MS function.
MS mode vs. zero key support
Packet 18: Check Checks the setting in the IPP7 key management options register. IPP7 Key Management Mode
Request Packet <SI>18<SO>{LRC} Format Table 45 Packet 18 Format Data Elements
<SI> Packet Type
Characteristics
1H 2AN
Comments
Shift In, value: 0Fh Value: 18
305
Table 45

2AH
Data Elements
Key Management Mode [KMM]
Comments
The two digits are concatenated bigendian, to produce a single control byte. The key management mode register (8 bits) in IPP7 is as follows: Bit 0 0 1 0 1 1 0 0 1 1 2 0 0 0 0 Description Old single DE Mixed mode (1DES and 3DES GISKE). 3DES GISKE MS Secure messaging (not supported in Omni 33XX)
Bit 3 0 1 Bit 4 0 1
Description 1DES DUKPT 3DES DUKPT Description Zero key support off Zero key support on.
Bit 5 0
Description Zero GISKE session key support off Zero GISKE session key support on Description At least one MS key or KLK key has been loaded. All MS master keys and the KLK are clear (no keys loaded). Description MAC empty working key support off. MAC empty working key support on.
Bit 6 0
Bit 7 0
306
Table 45

1AH
Data Elements
DUKPT Engine 1/2 Mode Flag [DEMF]
Note:
Comments
The one ASCII-Hex digit is used produce half of a control byte. Bit 0 0 1 ( DUKPT Engine "1") Description 1DES DUKPT - Default 3DES DUPKT
This field was added for IPP8 emulation.
Bit 1 0 1
( DUKPT Engine "2") Description 1DES DUKPT - Default 3DES DUPKT
Bit 2 ~ 3 ---------Reserved Example: Engine= DEMF = 0x30 0x31 0x32 0x33 <SO> {LRC} 1H 1H 0 1 2 3 1 1DES 3DES 1DES 3DES 2 1DES 1DES 3DES 3DES
Packet 18 Length:
MAX: 8 characters MIN: 8 characters Packet 18 Check IPP7 Key Management Mode Transmit Direction IPP
Table 46
Master Device
<SI>18<SO>{LRC}
<SI>18[KMM][PINER]<SO>{LRC}
307
Table 46
Packet 18 Check IPP7 Key Management Mode Transmit Direction IPP
Master Device
ACK/NAK
EOT to terminate process.
Packet 18 Examples: The following examples show the response packet, <SI>18[KMM][PINER]<SO>{LRC} from the IPP.
<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}
308
<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 users PIN from the keyboard, and Encrypt PIN echoing to the display an asterisk for each digit accepted. The PIN length can be (VISA Mode) between 4 and 12 digits. There are two variations of the request packet: Master/
Session and DUKPT. Sample Packet Z60 Request <STX>Z60.[acct num]<FS>[working key]<ETX>{LRC} for MS Response <STX>71.0[PIN len][PIN block format]
[encrypted PIN block]<ETX>{LRC}
Sample Packet Z60 Request <STX>Z60.[acct num]<FS>DUKPT ENCRYPTION<ETX>{LRC} for DUKPT Response <STX>73.00000[key serial number]
[encrypted PIN block]<ETX>{LRC}
On receipt of a packet Z60 that contains the account number and working key (if MS) or DUKPT ENCRYPTION (if DUKPT), the IPP gets the PIN from the user then checks if MS or DUKPT is selected.
If MS is selected, the IPP encrypts the formatted PIN block using the working key that was decrypted using the selected master key. The IPP returns the cipher-text PIN block using packet 71 (see MS Packet 71: Transfer PIN Block). If DUKPT is selected, the IPP encrypts the formatted block using the DUKPT algorithm. The IPP returns the key serial number and cipher-text PIN block using packet 73 (see DUKPT Packet 73: Transfer PIN Block (for Packets Z60 or Z63)).
Packet Z60 Format <STX>Z60.[aaaaaa]<FS>[wwwwww]<ETX>{LRC} MS
309
Packet Z60 Format <STX>Z60.[aaaaaa]<FS>[DUKPT ENCRYPTION]<ETX>{LRC} DUKPT Table 47 Packet Z60 Format Data Elements
<STX> Packet Type Packet Delimiter [aaa...aa] <FS> [www...www] or DUKPT ENCRYPTION
Characteristics
1H 3AN 1A 8-19N 1H 16AH or 120AH
Comments
Start of Text, Value: 02h Value: Z60 Value: (.), 2Eh Card account number Field Separator, Value: 1Ch [www.www] encrypted working key (encrypted session key) DUKPT ENCRYPTION means DUKPT is selected. Otherwise, it is the working key of MS encrypted under the master key. GISKE is used here for 3DES session key support. Size of [wwwwww] 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> {LRC} 1H 1H End of Text, Value: 03h Error Check
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}
310
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
No <FS> PIN entry too fast. See Restrict the Speed of the PIN Encryption Operation.
errno
EINVAL EACESS
Packet Z63: Accept and Encrypt PIN Custom PIN Entry Requirements (VISA Mode)
On receipt of the Z63 packet, Omni 33XX reads the users PIN from the keyboard, echoing to the display [echo char] for each digit accepted. The PIN length can be between [min len] and [max len] digits, inclusive, or 0 if the [NULL allowed flag] is set. There are two variations of these request packets: MS and DUKPT.
Sample Packet Z63 Request <STX>Z63.[acct num]<FS>[working key][min len][max len] for MS [NULL allowed flag][echo char]<ETX>{LRC}
Response <STX>71.0[PIN len][PIN block format] [encrypted PIN block]<ETX>{LRC} <STX>Z63.[acct num]<FS>DUKPT ENCRYPTION[min len][max len] [NULL allowed flag][echo char]<ETX>{LRC} <STX>73.00000[key serial number][encrypted PIN block]<ETX>{LRC}
Sample Packet Z63 Request for DUKPT

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

1H 3AN 1A
Data Elements
<STX> Packet Type Packet Delimiter
Comments
Start of Text, Value: 02h Value: Z63 Value: (.), 2Eh [aaa...aa] 8-19N Card account number
311
Table 48
Packet Z63 Format (Continued) Characteristics

1H 16AH or 120AH
Data Elements
<FS> [www...www]
Comments
Field Separator; Value: 1Ch 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 [wwwwww] 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). session key support are controlled by a switch in the key management option register set using packet 17 and checked using packet 18.
Zero key support and zero GISKE
[min len] [max len] [Null PIN allowed] [echo char] <ETX> {LRC}
2N 2N 1A 1AN 1H 1H
Minimum PIN length. 0412 Maximum PIN length. 0412 Null (zero length) PIN allowed. Y or N. Echo character. End of Text, Value: 03h Error Check
No <FS> invalid MIN, MAX, echo character, or null PIN flag PIN entry too fast. See Restrict the Speed of the PIN Encryption Operation. 312
errno
EINVAL EACESS
Packet M04: Read This command is used to check the permanent unit serial number. Permanent Unit Serial Number
NOTE
This packet is added for IPP8 emulation.
Request Packet <SI>M04<SO>{LRC} Format Table 49 Packet M04 Format Data Element
Characteristic
1H 3AN 1H 1H
Comments Shift In, value: 0Fh Value: M04 Shift Out, value: 0Eh Error Check
Packet M04 Length:
Response Packet <SI>M04[PUSN]<SO>{LRC} Format Table 50 Packet M04 Format Data Element
<SI> Packet Type Permanent Unit Serial Number [PUSN] <SO> {LRC}
Characteristic
1H 3AN 11AN
Comments Shift In, value: 0Fh Value: M04 Unit Serial Number format: xxx-xxx-xxx
1H 1H
Packet M04 Length:
Maximum: 17 characters Minimum: 17 characters Packet M04 Communication Protocol Transmit Direction IPP
Table 51
Master Device
<SI>M04<SO>{LRC}
ACK if LRC okay. NAK if LRC incorrect (EOT after 3 NAKs).
<SI>M04[PUSN]<SO>{LRC}
313
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS MS-Specific Packets
Table 51
Packet M04 Communication Protocol (Continued) Transmit Direction IPP
Master Device
ACK if LRC okay NAK if LRC
incorrect (EOT after 3 NAKs). EOT terminates session.
MS-Specific Packets
The following packets are specific to MS 1DES and 3DES operations. The default mode for the IPP at power up is MS 1DES.
Packet 02: Transfer The master device uses this packet to send a master key to the IPP. The response Master Key from the IPP to the master device depends on the value of the key management
option register. Table 52 MS Packet 02 Format Characteristic
1H 3AN 1N
Data Element
<STX> Packet Type [n]
Comments
Shift In, Value: 0Fh Value: 02 Address or key usage identifier. 1DES:
Master key address is 0-9
3DES:
Master key address for double- or triple-length
keys is 09, 'Fa [hhh...hh] 16H Master key in ASCII.

16Ah: 1DES mode for single-length key 120Ah: GISKE mode for double- and triple-
length key, including key block header, master key, and MAC. For more details on GISKE refer GISKE Key Block Spec, VPN 22986. <SO> {LRC}
a.
1H 1H
Shift Out, Value: 0Eh Error Check
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:
Communication Protocols Each key stored in the IPP contains its own key attributes.
314
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 Value
AN D N 00 1
Key Attributes
Key usage Key Algorithm Key mode of use Key version Key length
Hex
0x41, 0x4E 0x44 0x4E 0x30, 0x30 0x31
Definition
Any; no special restrictions DES No special restrictions version = zero 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 Direction IPP
Master Device
<SI>02[n][hhhhhhhhhhhhhhhh]<SO>{LRC}

<SI>02[n][hhhhhhhhhhhhhhhh]<SO>{LRC}
ACK if LRC and key echo
are okay
NAK if LRC incorrect EOT after 3 NAKs EOT if LRC correct, but key
echo incorrect
IPP saves the new master key only
on receipt of ACK
EOT terminates session
315
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 Characteristic

1H 2AN 1N
Data Element
<SI> Packet Type [n]
Comments
Shift In, Value: 0Fh Value: 02 Response code (07):
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 <SO> {LRC} 1H 1H Shift Out, Value: 0Eh Error Check
Packet 02 GISKE Key Block Format Length:
Packet 02 GISKE Key <SI>020<SO>{LRC} Block Format Example:
316
Table 56
Packet 02 GISKE Key Block Format Communication Protocol Transmit Direction IPP
Master Device
<SI>02[r][hhh.hhh]<SO>{LRC}

<SI>02[n]<SO>{LRC}
ACK if LRC, no errors, and key
echo okay
NAK if LRC incorrect EOT after 3 NAKs EOT if LRC correct, but key echo
incorrect
IPP saves new key only on
receipt of ACK
EOT terminates session
Packet 04: Check The master device sends this packet to check if the IPP has a master key stored Master Key at a designated master key address. To avoid an overwrite, this packet must be
sent before sending packet 02 to check that a valid master key is already stored in the designated address. Table 57 MS Packet 04 Format Characteristic
1H 2AN 1N 1H 1H
Data Element
<SI> Packet Type [a] <SO> {LRC}
Comments
Shift In, Value: 0Fh Value: 04 Master Key address: 09 KLK: F Shift Out, Value: 0Eh Error Check
317
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 1DES mode Key Length at Address [a] 1DES (single-length key) 3DES (single-, double, or triple-length key) Mixed or 3DES mode 1DES (single-length key) 3DES (single-, double, or triple-length key)
a.
Communication Protocol Used Key-only format (IPP5/ IPP6) GISKE key block formata GISKE key block format GISKE key block format
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 Characteristic

1H 2AN 1AN
Data Element
<SI> Packet Type [r]
Comments
Shift In, Value: 0Fh Value: 04 Response code:
0 = No master key at address [a] F = Master key present at address [a]
<SO> {LRC}
1H 1H
318
Table 59
Response Packet 04 Key-only Format Communication Protocol Transmit Direction IPP
Master Device
<SI>040<SO>{LRC}
ACK if LRC okay NAK if LRC incorrect EOT after 3 NAKs PIN pad checks requested address [a].
<SI>04[r]<SO>{LRC}
ACK if LRC okay NAK if LRC incorrect EOT after 3 NAKs
EOT
Response Packet 04 Key-only Format Length:
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 Data Element

<SI> Packet Type [r]
Response Packet 04 GISKE Key Block Format Characteristic

1H 2AN 1AN
Comments
Shift In, Value: 0Fh Value: 04 Response code:
0 = No master key at address [a] F = Master key present at address [a]
319
Response Packet 04 GISKE Key Block Format (Continued) Characteristic

2AH
Comments
Only when master key is present at address [a]:
AN: ANY: The key is available in the IPP, but
Key Usage Attribute (KUA)
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 (156 bits) 10: ISO 9797-1 MAC algorithm 1 (1112 bits) 20: ISO 9797-1 MAC algorithm 2 (2112 bits) 30: ISO 9797-1 MAC algorithm 3 (3112 bits) 40: ISO 9797-1 MAC algorithm 4 (4112 bits) 50: ISO 9797-1 MAC algorithm 5 (556 bits) 60: ISO 9797-1 MAC algorithm 5 (5112 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 0F (4 bits). In the response packet (to packet 04), the IPP converts the number back to characters used in GISKE specification.
320

Mode of Use Attribute (MOUA)
Response Packet 04 GISKE Key Block Format (Continued) Characteristic

1AH
Comments
(optional) Only if the master key present at address [a]. The value is stored in the key attributes register.
N: No special restrictions [0] E: Encryption only [1] D: Decryption only [2] S: Signature only [3] 0: IV [4] G: MAC generate [5] V: MAC verify [6] C: Calculate = generate or verify) [7] [6][F]: Reserved Note:
To save storage space in RAM, the mode of use attribute is converted to [x], a hex number ranging form 0F (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 (KV)
2AH
(optional) Only if the master key present at address [a]. The 2-digit ASCII character version number is optionally used to reinject old keys. If not used, this field is filled with ASCII 0 (0x30).
Note:
The IPP allocates 1 byte per key for each key version register.
Key Length (KL)
1AH
(optional) Only if the master key present at 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.
<SO> {LRC}
1H 1H
Response Packet GISKE Block Format 04 Length:
Response Packet 04 <SI>040[KUA][MOUA][MACMA][KV][KL]<SO>{LRC} GISKE Block Format Example:
321
Table 61
Response Packet 04 GISKE Block Format Communication Protocol Transmit Direction IPP
Master Device
<SI>04[a]<SO>{LRC}
ACK if LRC okay NAK if LRC incorrect EOT after 3 NAKs PIN pad checks requested address [a].
<SI>04[r][KUA][MOUA][MACMA][KV][KL]<SO>{L RC}
ACK if LRC okay NAK if LRC incorrect EOT after 3 NAKs
EOT
MS Packet 08: The master device sends this packet to the IPP to select one of the ten possible Select a Master Key master keys (09). It is recommended that the master device should always send
this packet first before sending a packet (for example, Packet Z60: Accept and Encrypt PIN (VISA Mode)) to request for PIN entry. Table 62 MS Packet 08 Format Characteristic
1H 2AN 1N 1H 1H
Data Element
Comments
Shift In, Value: 0Fh Value: 08 Master Key address: 09 Shift Out, Value: 0Eh Error Check
MS Packet 08 To select Master Key 7: Example:

<SI>087<SO>{LRC}
322
Table 63
MS Packet 08 Communication Protocol Transmit Direction IPP
Master Device
<SI>08[a]<SO>{LRC}
ACK if LRC NAK if LRC incorrect EOT after 3 NAKs PIN pad makes master key [a] active.
EOT
Notes 1
The 1DES and 3DES key usage rules (see Rules for Loading the Master Key (MS only)) applies when selecting a master key. If the selecting master key is not available or is not applicable due to the 1DES or 3DES key usage rule, no response is returned to the master device. currently selected key as the active master key due to a backward compatibility requirement.
2 If the master key address does not contain any key, the IPP still sets the
MS Packet 71: Response packet to Packet Z60: Accept and Encrypt PIN (VISA Mode) and Transfer PIN Block Packet Z63: Accept and Encrypt PINCustom PIN Entry Requirements (VISA
Mode). The IPP encrypts the formatted clear-text PIN block and sends the ciphertext PIN block to the master device. Table 64 MS Packet 71 Format Characteristic
1H 2AN 1A 1N 2N 2N 16H
Data Element
<STX> Packet Type Packet Delimiter Function Key Indicator PIN Length PIN BLock Format Encrypted PIN Block <ETX> {LRC}
Comments
Start of Text, Value: 02h Value: 71 Value: (.), 2Eh Value is 0; Function key feature not implemented. Range 00, 04 to 12 Value: 01; Format of PIN block prior to encryption The 64-bit encrypted PIN block represented as 16 hexadecimal digits. Present only if PIN entered. End of Text, Value: 03h Error check
1H 1H
323
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS DUKPT-Specific Packets
MS Packet 71 <STX>71.000010123456789123456<ETX>{LRC} Example: This packet 71 is the response packet to PIN request Z60 and Z63 when no errors are detected in the Z60 or Z63 packet. If errors are detected in the Z60 or Z63 packet, the response packet is in the following format: Table 65 MS Response Packet 71 Format: Errors in Z60 or Z63 Packets Characteristic
1H 2AN 1N
Data Element
<STX> Packet Type Error Code
Comments
Start of Text, Value: 02h Value: 71
1 = no master key 2 = account or working key error 3 = PIN too long. 4 = PIN too short / non-decimal digit(s) in PIN. 5 = PIN pad used as DUKPTa 6 = Master key attributes error 7 = KOF/GISKE working key attributes error,
key attributes: key usage, algorithm, mode of use, key version, or key length <ETX> {LRC}
a.
1H 1H
End of Text, Value: 03h Error Check
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 Packets
The following packets are specific to DUKPT operation. Two DUKPT modes are implemented in IPP7: 1DES or 3DES. All keys associated with DUKPT are erased when switching between 1DES and 3DES DUKPT modes.
Packet 19: Select a The application sends this packet to the IPP to select one of the DUKPT engines DUKPT Engine ("0", "1", or "2"). It is recommended that the application always send this packet
first before sending a DUKPT packet (eg. packet Z60, Z63, 76, Z69 and 90).
NOTE
This packet was added for IPP8 emulation.
324
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS DUKPT-Specific Packets
Table 66
DUKPT Packet 19 Format Characteristic

1H 2AN 1N 1H 1H
Data Element
Comments
Shift In, Value: 0Fh Value: 19 DUKPT Engine: "0", "1",or "2" Shift Out, Value: 0Eh Error Check
DUKPT Packet 19 Length: Maximum: 6 characters Minimum: 6 characters Sample Packet: To select second DUKPT Engine:
<SI>192<SO>{LRC}
Table 67
DUKPT Packet 19 Communication Protocol Transmit Direction IPP
Master Device
<SI>19[a]<SO>{LRC}
ACK if LRC okay NAK if LRC incorrect (EOT after 3 NAKs).
Echo packet 19 setting <SI>19[a]<SO>{LRC}

ACK if LRC okay NAK if LRC incorrect
(EOT after 3 NAKs) IPP changes DUKPT engine EOT to terminate process.
NOTE
If there is any packet format error, IPP does not echo the response packet back to the
master device. The incorrect packet format includes out of range DUKPT engine, incorrect packet type, incorrect packet length, etc.
The default DUKPT engine is set to "0".
325
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS Packet 25: Check the DUKPT Engine
Packet 25: Check The application sends this packet to the IPP to check the current active DUKPT the DUKPT Engine engines ("0", "1", or "2").
NOTE
This packet is added for IPP8 emulation.
Request Packet <SI>25<SO>{LRC} Format Table 68 Packet 25 Format Data Element

Characteristic
1H 2AN 1H 1H
Comments
Shift in, value: 0Fh Value: 25 Shift out, value: 0Eh Error check
Packet 25 Length:
Response Packet <SI>25[PUSN]<SO>{LRC} Format Table 69 Packet 25 Format Data Element

Characteristic
1H 2AN 1N 1H 1H
Comments
Shift in, value: 0Fh Value: 25 Active DUKPT Engine: "0", "1",or "2" Shift Out, value: 0Eh Error Check
Packet 25 Length:
Sample Packet: To Check DUKPT Engine:

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

<SI>251<SO>{LRC}
326
Table 70
Master Device
<SI>25<SO>{LRC}
ACK if LRC okay. NAK if LRC incorrect (EOT after 3
NAKs). Response current active DUKPT engine. <SI>25[a]<SO>{LRC}

ACK if LRC okay NAK if LRC incorrect (EOT
after 3 NAKs). EOT terminates session.
DUKPT Packet 73: Transfer PIN Block (for Packets Z60 or Z63)
Response packet to Packet Z60: Accept and Encrypt PIN (VISA Mode) and Packet Z63: Accept and Encrypt PINCustom PIN Entry Requirements (VISA Mode). The IPP encrypts the formatted clear-text PIN block and sends the ciphertext PIN block to the master device. Table 71 DUKPT Packet 73 Format Characteristic
1H 2AN 1A 5N 1020AH
Data Element
<STX> Packet Type Packet Delimiter 00000 [KSN]
Comments
Start of text, Value: 02h Value: 73 Value: (.), 2Eh Value: 00000 Key serial number; hex. (leading Fs suppressed). Presented only if a PIN is entered; length is 0 if no PIN is entered. The 64-bit encrypted PIN block represented as 16 hexadecimal digits. End of text, Value: 03h Error check
Encrypted PIN Block <ETX> {LRC}
16AH 1H 1H
DUKPT Packet 73 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:
327
Table 72
MS Response Packet 73 Format: Errors in Z60 or Z63 Packet Characteristic

1H 2AN 1N
Data Element
Comments
Start of text, value: 02h Value: 73
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> {LRC}
a.
1H 1H
End of text, value: 03h Error check
Error code 5 do not occur in the IPP, since the IPP supports simultaneous DUKPT and MS.
DUKPT Packet 73 <STX>731<ETX>{LRC} Example:
DUKPT Packet 90: Loads initial key to the IPP. After the initialization of packet 21, future keys, the IPP Load Initial Key responds with packet 91 with confirmation status. Request
Table 73 DUKPT Packet 90 Format Characteristic
1H 2AN 16H 20H 1H 1H
Data Element
<STX> Packet Type [IPEK] [KSN] <ETX> {LRC}
Comments
Start of text, Value: 02h Value: 90 Initial PIN Encryption Key, hexadecimal Key Serial Number; hex (leading Fs included) End of text, value: 03h Error check character
DUKPT Packet 90 Length
MAX: 57 characters MIN: 41 characters The difference between DUKPT 1DES mode and DUKPT 3DES mode is in the size of the initial PIN encryption key and the sizes of the future keys.
NOTE
328
Table 74
Master Device
90 Packet
ACK if LRC NAK if LRC incorrect EOT after 3 NAKs Initialization of 21 Future Keys
Packet 91 with confirmed status

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.
1H 2AN 1N
Data Element
<STX> Packet Type [CS]
Comments
Start of text, Value: 02h Value: 91 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 encryption key length (through packet 90) sent by the master device IPP7 Current DUKPT Mode [CS] response from the IPP
16AH 32AH <ETX> {LRC} 1H 1H
3DES 1DES End of text, value: 03h Error check character
2 2
329
Table 76

Packet 91
Master Device
DUKPT Packet 76: Directly presets the PIN code '1234' to do encryption and send response PIN Entry Test packet 71. Request
1H 2AN 8-19N 1H 1H 3-7N 1H 1H
Data Element
<STX> Packet Type [account#] <FS> [C/D] [amount] <ETX> {LRC}
Comments
Start of text, value: 02h Value: 76 Card account number Field separator, value: 1Ch Credit/Debit indicator, value: 43h/44h Transaction amount must include the decimal point. End of text, value: 03h Error check
NOTE
The amount filed must be present in the packet command, but the format is not confirmed.
Table 78
Master Device
76 Packet
Packet 71 with PIN = 1234

330
DUKPT Packet 71: Response packet to packet 76, request for PIN. The IPP encrypts the formatted Transfer PIN Block - clear-text PIN block and sends the cipher-text PIN block to the master device. (for Packet 76) (refer to the VISA PIN Processing and Data Authentication specification,
International version 1.0) Packet 71 has a different packet format and meaning than the response PIN block 71 in MS. This is for compatibility with existing third parties (for example, Racal) to initialize the DUKPT key. Table 79 DUKPT Packet 71 Format Characteristic
1H 2AN 1N 10-20H
Data Element
<STX> Packet Type Function Key Key Serial Number Encrypted PIN Block <ETX> {LRC}
Comments
Start of text, value: 02h Value: 71 Value: 0, function key indicator feature not implemented Hexadecimal (leading Fs suppressed.); Included only if PIN entered; length is 0 if no PIN entered The 64-bit encrypted PIN block represented as 16 hexadecimal digits; length is 0, if no PIN entered. End of text, value: 03h Error check
16H
1H 1H
MAX: 42 characters MIN: 6 characters (if NULL entered)
DUKPT Packet 71 <STX>710[KSN]0123456789123456<ETX>{LRC} Example: When no errors are detected in packet 76, the IPP returns response packet 71. If errors are detected in packet 76, response packet 71 is in the following format: Table 80 DUKPT Packet 71 Format: Errors Detected in Packet 76 Characteristic
1H 2AN 1N
Data Element
Comments
1 = no key 2 = account error 5 = C|D field error 6 = PIN pad has over 1 million transactions
<ETX> {LRC}
1H 1H
MAX: 6 characters MIN: 6 characters (if NULL entered)
331
DUKPT Packets 92 The DUKPT reinitialization request and reinitialization response packets are not and 93 supported in Omni 33XX. DUKPT Z69 Packet: Accept and Encrypt PIN / Data Authentication Request
On receipt of the Z69 packet, Omni 33XX reads the users PIN from the keyboard, echoing to the display an asterisk for each digit accepted. The PIN length can be between 4 and 12 digits. Table 81 DUKPT Packet Z69 Format Characteristic
1H 3AN 819N 1H
Data Element
<STX> Packet Type [account#] <FS> or <US>
Comments
Start of text, value: 02h Value: Z69 Card account number. <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] [amount] <ETX> {LRC}
1H 313N 1H 1H
Credit/debit indicator, value 43h/44h Transaction amount including the decimal point. End of text, value: 03h Error check character
DUKPT Packet Z69 Length
MAX: 24 characters MIN: 45 characters DUKPT Packet Z69 Communication Protocol Transmit Direction IPP
Table 82
Master Device
Z69 Packet
ACK of LRC okay NAK if LRC incorrect EOT after 3 NAKs
Packet 75 with confirmed status

DUKPT Packet Z69 VISA: Example:
<STX>Z6901234567890<FS>C19.99<ETX>{LRC}
ANSI:
<STX>Z6901234567890<US>C19.99<ETX>{LRC}
332
No <FS>
errno
EINVAL
DUKPT Packet 75: DUKPT Accept and Encrypt PIN/Data Authentication Response
Response packet to packet DUKPT Z69 Packet: Accept and Encrypt PIN / Data Authentication Request or Packet 78: DUKPT Accept and Encrypt PIN/Data Authentication Test Request to the controller with confirmation status. Authentication code #1 is the MAC on this message. If the request is approved, the MAC received with the approval response message exactly matches authentication code #2. If the request is declined, the MAC received with the decline response message must exactly match authentication code #3. Table 83 DUKPT Packet 75 Format Characteristic
1H 2AN 8H
Data Element
<STX> Packet Type [Auth. Code #1]
Comments
Start of text, value: 02h Value: 75 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 Key Serial Number Encrypted PIN Block <ETX> {LRC}
1N 1020H
Value is 0, Function Key Indicator feature not implemented Hexadecimal (leading Fs suppressed.); Included only if PIN entered; Length is 0 if no PIN entered The 64 bit encrypted PIN block represented as 16 hexadecimal digits. Length is 0, if no PIN entered. End of text, value: 03h Error check character
16H
1H 1H
333
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 Characteristic
1H 2AN 1N
Data Element
Comments
1 = no key 2 = account error 3 = PIN too long 4 = PIN too short/non-decimal digit in PIN 5 = C|D field error/not DUKPT mode 6 = PIN pad has over 1 million transactions 7 = amount error 8 = ANSI MAC not allowed when using 1DES
DUKPT <ETX> {LRC} 1H 1H End of text, value: 03h Error check
334
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. Table 85 DUKPT Packet 78 Format Characteristic
1H 2AN 819N 1H
Data Element
<STX> Packet Type [account#] <FS> or <US>
Comments
Start of text, value: 02h Value: 78 Card account number <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] [amount] <ETX> {LRC}
1H 3-13N 1H 1H
Credit/Debit indicator, value: 43h/44h Transaction amount, decimal point included. End of text, value: 03h Error check
NOTE
As per the VISA specification: The amount field should be 312 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}
335
IPP MS AND DUKPT C OMMUNICATIONS P ACKETS MAC-Specific Packets
Table 86
Master Device
78 Packet
Packet 75 with PIN = 1234

MAC-Specific Packets
This section describes the master-session MAC generation of received message packets for the IPP. Two packet formats are specified: Z66 and Z67. The detailed module design and interface design are discussed. ANSI (Standard) MAC algorithms are used. The following are the packets in this module:
Z66: Request MAC Z67: Return MAC 72: Cancel MAC Session
MAC Packet Z66: Used by the master device to direct the IPP to generate the MAC of the current Request MAC packet. If it is the first Z66 packet, the IPP begins MAC generation. If it is the last
Z66 packet, the IPP completes the MAC calculation for current packet, and returns the MAC to the master device through the Z67 packet. Otherwise, the IPP calculates the MAC from current packet and stores it in memory. Table 87 MAC Packet Z66 Format Characteristic
1H 3AN 1N
Data Element
<STX> Packet Type [flag]
Comments
Start of text, value: 02h value: Z66 ANSI (Standard) MAC: ASCII Data: Range: 45
4 = the last packet 5 = the first/middle packet
Binary Data; Range: 67

6 = the last packet 7 = the first/middle packet
[sequence] Master Key Pointer <FS> Working Key <FS>
2N 1N 1H 16H 1H
Range: 0099 Optional; Range: 09 Field separator, value: 1Ch Encrypted working key for DES Field separator, value: 1Ch
336
Table 87
MAC Packet Z66 Format (Continued) Characteristic

1N 1H 8*XAN0
Data Element
Second Key <FS> Message for MACa
Comments
Optional; Second master key pointer; Range: 09 Field separator, value: 1Ch ASCII message or ASCII-coded binary data: X= 028 for ASCII data X= 0,2,4,6,...,27,28 for binary data
<ETX> {LRC}
1H 1H
a. ASCII messages for MAC should not include ETX(0x03) or SO(0x0E).
MAC Packet Z66 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. blocks. For example,
2 8*XAN in Message for MAC represents the number of 8-byte (or character)
X = 0: no message data X = 1: 8 bytes of message data X = 2: 16 bytes of message data X = 3: 24 bytes of message data : : X = 27: 216 bytes of message data X = 28: 224 bytes of message data
For ASCII data, all values of X from 028 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.
337
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 156 bits, MAC Algorithm
1112 bits, MAC Algorithm 2112 bits, MAC Algorithm 3112 bits, MAC Algorithm 4112 bits, MAC Algorithm 556 bits, MAC Algorithm 5112 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 Packet Type Keyonly format Binary: X = 0, 2, 4 26, 28 GISKE Key Block Format mode ASCII: X = 0, 1, 2 14, 15 224 120 00 99 Due to size of GISKE key block, the size of message is reduce to 120 bytes. Rules for Request MAC Size of X ASCII: X = 0, 1, 2 27, 28 Maximum Size of Message (bytes) 224 Apply to Message Sequence
0099
Comments
Binary: X =0, 2, 4 12, 14
112
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.
338
Sends the MAC value to the master device. MAC Packet Z67 Format Characteristic
1H 3AN 1N
Table 89
Data Element
<STX> Packet Type Process Code
Comments
Start of text, value: 02h Value: Z67 Range: 09:
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 <ETX> {LRC} 16H 1H 1H Optional; only sent when no errors are detected End of text, value: 03h Error check
MAC Packet Z67 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.
Table 90 MAC Packet Z66 Format Characteristic
1H 3AN 1H 1H
Data Element
<STX> Packet Type <ETX> {LRC}
Comments
Start of text, Value: 02h Value: 72 End of text, value: 03h Error check
Packet 72 Length:
Packet Z72 Example: <STX>712 <ETX>{LRC}
339
Table 91
Master Device
<STX>72<ETX>{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 [pointer]
present absent
MAC for Master and Working Keys [working key]

present present
Selection
Master key selected by [pointer]; working key decrypted by master key. Working key decrypted by current active master key.
After the MAC calculation, there is an optional procedure used to increase protection against exhaustive key determination. This procedure can be turned on/off by the [second key] field of the first Z66 packet. If this second key was provided with the first Z66 packet, this procedure generates the final MAC and uses [second key] as the master key pointer. If no [second key] is provided, no procedure is performed on the current MAC. One thing to note is that [second key] is used on a session-by-session basis. Each [second key] field of the first Z66 packet defines its own optional procedure on/off status during that MAC session. For more detailed information about MAC optional procedure, please refer section 2.4.4.5 of the ANSI X9.19 specification. After the process completes, a 64-bit MAC is generated. This MAC value returns to the master device with packet Z67. If there any errors are detected during the MAC process, packet Z67 returns with [code] set to an error code.
340
INDEX
Numerics
1DES master key 284 real time clock 33 serial port 33 Sound 33 touch panel 33 USB 33 directory structure 198 file organization 198 user space and security 199 user space base structure 199 display 130 dspSetBrightness() 131 downloading 26 IBM ECR 27 NFS 26 TCP/IP 27 USB Memory Device 27 Zontalk 26 downloading files from the ECR 119 DUKPT IPP7 324
A
audio beeper units 135 disabling speakers 134 vlume, bass and treble control 133
C
C compiler and development tools C compiler & tools 13 COM1 98 COM2 99 COM3 service functions 174 svcCom3FlushRxBuf() 185 svcCom3Polled() 188 svcCom3ReqExtStatus() 176 svcCom3ReqFirmVers() 180 svcCom3ReqTallyInfo() 178 svcCom3ResTallyData() 179 svcCom3SetBufFlushInt() 187 svcCom3SetDeviceAddr() 181 svcCom3SetECLevel() 182 svcCom3SetHandshake 183 svcCom3SetMode() 175 svcCom3SetRxRecThresh() 186 COM4 100 COM5 100 config.usrx 18 configuration variables 15
E
ECR Environment Variables 116 Environment Variables P4683 117 environment variables 15 A4683 117 G4683 118 I4683 116 L4683 117 O4683 116 S4683 118 V4683 118 environment/configuration variables getEnvFile 19 putEnvFile 20
D
Delta smartcard interface/cardslot 92 device drivers Delta 33 Display 33 ethernet port 33 IPP 33 magnetic stripe reader 33
F
file authentification 28 file compression 15
341
I NDEX
file format details 15 file systems 15 firmware 13
IPP7 46, 284 DUKPT modes 324
J
JFFS2 15
G
getenv() 15 GISKE key attribute 284 KLK key loads 285 GNU C compiler 13 GNU ZIP 15
K
key 285 key attributes, IPP 284 KLK (GISKE) 285
L
LEDs 136 ledOff 138 ledOn 137
I
IBM ECR tailgate & feature C 100 ecrRead 102 ecrReadReject 103 ecrStatus 104 IBM ECR tailgate & feature CecrClose 110 IBM ECR tailgate & feature CecrDownload 111 IBM ECR tailgate & feature CecrWrite 109 internal PIN pad int ippClose(void) 48 int ippOpen(void) 47 int ippRead(char *buffer, int size) 49 int ippWrite(char *buffer, int size) 50 SetSecurePINDisplayParameters() 51 IPP key attributes 284 key length 284 key version 284 IPP differences 56 IPP ROM version number 56 multiple DUKPT 56 PROM checksum 56 select baud rate 56 set IPP6 key management mode 56 set IPP7 key management mode 56 set master key 56 IPP refenreces 57 GISKE specification 57 PP7 specification 57 ipp_abort() 224 ipp_getpin() 217 ipp_mac() 222 ipp_read() 219
342
M
MAC value 286 magnetic stripe reader 34 msrClose 45 msrDisableLicenseDecode 43 msrEnableLicenseDecode 42 msrMagneticCardPresent 39 msrOpen 35 msrRaw 40 msrRead 36 msrStructured 41 msrVersion() 44 msrWrite 38 Mx800 series COM ports 98 COM3 99
O
operating system 13
P
packet mode 94 endPktMode() 96 Receiving Packet Messages 97 putenv() 15
R
real-time clock 139 void setRTC(void) 140 reference documents LINUX books 12
I NDEX
root file system 197, 215 BusyBox 197 uClibc 197
S
security services APIs 80 AES() 86 authFile() 90 cryptoRead() 82 cryptoWrite() 81 DES() 85 generateRandom() 87 IRSA Computation 83 isAttacked() 88 loadOSFiles() 91 secVersion() 89 SHA1() 84 serial communication control structure 93 packet_parms 94 protocol 93 trailer 94 service functions 143 svcAlarm() 167 svcCrcCalc() 144 svcExpand 172 svcGetInQ() 170 svcGetOutQ() 171 svcGetPortStatus() 168 svcInfoCard() 156 svcInfoDsp() 155 svcInfoKey() 157 svcInfoPlatform() 152 svcInfoType() 154 svcReleaseAlarmCallback() 166 svcReleaseRxCallback() 164 svcRestart() 147 svcSetAlarmCallback() 165 svcSetOpenBlock 162 svcSetRxCallback() 163 SvcZontalkRcv() 159 SIGALRM 114, 115 SIGINT 114 SIGIO 114, 115 Signals 114 signature capture 120
Signature Capture API 123 svcDsp2Hex() 146 svcInfoRFS() 149 System Mode 195
T
touch panel 120
V
Verishield Security Scripts (VSS) 57 VSS APIs 57 iPS_CancelPIN() 73 iPS_CheckMasterKey() 64 iPS_DeleteKeys() 59 iPS_ExecuteScript() 77 iPS_GetPINResponse() 70 iPS_GetScriptStatus() 75 iPS_InstallScript() 74 iPS_LoadMasterClearKey() 62 iPS_LoadSysClearKey() 60 iPS_RequestPINEntry() 69 iPS_SelectPINAlgo() 68 iPS_SetPINParameter() 66 iPS_UninstallScript() 76 pcPS_GetVSSVersion() 79 SetSecurePINDisplayParameters() 65
343
VeriFone, Inc. 2099 Gateway Place, Suite 600 San Jose, CA, 95110 USA Tel: (800) VeriFone (837-4366) www.verifone.com
Mx800 Series
Programmers Guide
Part Number 23753, Revision A

MX800 Programmers Guide

Uploaded by

Copyright:

Available Formats

MX800 Programmers Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MX800 Programmers Guide

Uploaded by

Copyright:

Available Formats

Mx800 Series

Part Number 23753, Revision A

Mx800 Series Programmers Guide 2006 VeriFone, Inc.

MX800 SERIES REFERENCE MANUAL

MX800 SERIES REFERENCE MANUAL

CHAPTER 8 USB - Device / Host USB Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

CHAPTER 9 TCP/IP Ethernet Network Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

C H A P T E R 12 Input Events inputOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

C H A P T E R 13 Visual Payments Visual Payments Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

MX800 SERIES REFERENCE MANUAL

MX800 SERIES REFERENCE MANUAL

Modifications to this document Acronyms, Abbreviations, and Definitions

The Itsy Package Management System

VSS Key Loading Key

I NTRODUCTION Conventions Used in this Document

Acronyms, Abbreviations, and Definitions Definition

Major Hardware Devices

ARM9 Graphic Display

ARM SoC Color (16 bpp) QVGA (320x234)

Conventions Used in this Document

The following table describes the conventions used: Table 3 Convention

Document Conventions Meaning

Recommended Beginning Linux Programming (3rd Edition) LINUX Books

MX800 SERIES PROGRAMMERS GUIDE

MX800 SERIES PROGRAMMERS GUIDE

O VERVIEW OF P RODUCT D ELIVERABLES Operating System and Firmware

MX800 SERIES PROGRAMMERS GUIDE

Environment/ Configuration Variables

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS Environment/Configuration Variables

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS Environment/Configuration Variables

Hash Sign (#)

Forward Slash (/) Left Bracket ([)

Right Bracket (])

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS Environment/Configuration Variables

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS getEnvFile

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS putEnvFile

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS putEnvFile

*BACKLIGHT *VOLUME *MOUNT0 - *MOUNT9

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS putEnvFile

Table 5 Variable Name

xxx.xxx.xxx.xxx or ASCII server DNS name Max length = 96 characters

Default = 21 Default=app.tgz Max length = 96 characters

Default = Terminal S/N Max length = 32 characters

Default = anonymous Max length = 32 characters

Default = 30 Min = 10 Max = 1440 Off = 0

Default = TRUE Default = FALSE

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS putEnvFile

Table 5 Variable Name

*VPAYSERVERADDRESS *VPAYSERVERPORT *VPDOWNPORT

xxx.xxx.xxx.xxx xxxxx xxxxx

MX800 SERIES PROGRAMMERS GUIDE

F ILE S YSTEMS getSysctl()

BACKLIGHT VOLUME MOUNT0 - MOUNT9

VPAYSERVERADDRESS VPAYSERVERPORT *VPDOWNPORT