MX800 Programmers Guide

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