VeriFone MX800 series Programmer's Manual
  1. Manuals
  2. Brands
  3. VeriFone Manuals
  4. Touch terminals
  5. MX800 Series
  6. Programmer's manual

VeriFone MX800 series Programmer's Manual

Hide thumbs Also See for MX800 series:
Table of Contents

Advertisement

Quick Links

Download this manual See also: Troubleshooting Manual, Installation Manual
x
M
800 Series
Programmers Guide
Part Number 23753, Revision A

Advertisement

Table of Contents
loading

Related Manuals for VeriFone MX800 series

Summary of Contents for VeriFone MX800 series

  • Page 1 800 Series Programmers Guide Part Number 23753, Revision A...
  • Page 2 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.

  • Page 3: Table Of Contents

    ONTENTS H A P T E R Introduction Scope ............11 Modifications to this document .
  • Page 4 ONTENTS int ippWrite(char *buffer, int size) ....... . . 50 SetSecurePINDisplayParameters() .
  • Page 5 ONTENTS COM3 ............99 COM4 - Optional I/O Module .
  • Page 6 ONTENTS svcInfoSerialNum() ......... . . 150 svcInfoPtid() .
  • Page 7 ONTENTS USB Mass Storage and Memory Devices......202 USB Human Interface Device (HID) Support ......204 H A P T E R TCP/IP Ethernet Network Configuration .
  • Page 8 ONTENTS H A P T E R Visual Payments Visual Payments Library Functions ....... . . 255 vpInit() .
  • Page 9 ONTENTS Master Key for PIN Encryption....... . 283 Rules for Loading the Master Key (MS only) .
  • Page 10 ONTENTS Packet 78: DUKPT Accept and Encrypt PIN/Data Authentication Test Request MAC-Specific Packets ......... . . 336 MAC Packet Z66: Request MAC .

  • Page 11: Hapter

    HAPTER Introduction Scope This document describes the programming environment for the M 800 series of terminals. This document lists or references all significant functions unique to the terminal. This document will not describe the Linux application API. There are many good books on this topic.

  • Page 12: Conventions Used In This Document

    NTRODUCTION Conventions Used in this Document Table 1 Acronyms, Abbreviations, and Definitions Abbreviation Definition Cyclic Redundancy Check bits per second Master Session Key Serial Number PIN Encryption Key GISKE Global Interoperable Secure Key Exchange Table 2 Major Hardware Devices ARM9 ARM SoC Graphic Display Color (16 bpp) QVGA (320x234)

  • Page 13: Hapter

    Windows (using Cygwin). The M 800 Series terminal will include gdbserver for use during application debug. VeriFone has created a "plug in" feature for the Eclipse IDE that simplifies application project building and debug. 800 S ERIES...
  • Page 14 VERVIEW OF RODUCT ELIVERABLES Operating System and Firmware 800 S ERIES ROGRAMMERS UIDE...

  • Page 15: Hapter

    HAPTER File Systems The M 800 series terminal file system uses the Journaling Flash File System or JFFS2. JFFS2 is used to store application code and data as well as shared libraries. JFFS2 supports wear leveling and power fail protection. File The M 800 series of terminals will support GNU ZIP (.gz or .tgz or tar.gz)
  • Page 16 YSTEMS Environment/Configuration Variables By default, all configuration files will have two sections, perm and reg. The perm section is special in that entries under perm will not be deleted on a full download. All other section entries will be deleted on a full download. To aid compatibility with previous terminals, all keys that begin with “*”...
  • Page 17 YSTEMS Environment/Configuration Variables Table 4 Character Decimal Usage Form Feed 0x0C This is a reserved character and cannot be used in any field. If used, unexpected and unsupported results may occur. Carriage Return 0x0D This is a reserved character and cannot be used in any field.
  • Page 18 YSTEMS Environment/Configuration Variables There are also command line versions of these 2 functions below called that are mainly used for development purposes. getEnvFile putEnvFile When these command line versions are used, it is necessary to double-quote each part, label, and value fields separately to prevent the Linux shell from interpreting the characters.

  • Page 19: Getenvfile

    YSTEMS getEnvFile getEnvFile Prototype int result = getEnvFile(char *section, char *label, char *value, int vlen); Parameters Points to a null terminated string containing the .ini file section section name. Maximum length of the section name is 32 bytes. If section is a pointer to null, the system will Note: automatically read from with perm or reg.

  • Page 20: Putenvfile

    YSTEMS putEnvFile putEnvFile Prototype int result = putEnvFile(char *section, char *label, char *value, unsigned short vlen, unsigned short options); Parameters Points to a null terminated string containing the .ini file section section name. Maximum length of the section name is 31 bytes. If section is a pointer to null, the system will Note: automatically read from with perm or reg.

  • Page 21: System Configuration Variables

    YSTEMS putEnvFile System The following table of configuration variables are read by the system on power up/ Configuration reboot. These configuration variables must be set within the usr1 account. Variables Table 5 Variable Name Values Definition Executable name The path /home/usr1 is pre-pended to the value set in *GO.
  • Page 22 YSTEMS putEnvFile Table 5 Variable Name Values Definition Enable USB serial device *USB DEVICE mode. You must reboot after setting this variable. Remove variable and reboot to disable. IF *USBHOST exists, USB *USBHOST host (hotplug) will be disabled. xxx.xxx.xxx.xxx or ASCII Either IP address or DNS *FTPHOST server DNS name...
  • Page 23 YSTEMS putEnvFile Table 5 Variable Name Values Definition If * VPAY exist and there is *VPAY no application loaded, the system will attempt to contact the Visual Payments host for an application download. xxx.xxx.xxx.xxx IP address of Visual *VPAYSERVERADDRESS Payments server. xxxxx Connection Port address on *VPAYSERVERPORT...

  • Page 24: Getsysctl()

    YSTEMS getSysctl() getSysctl() Reads the value of the kernel parameters in the /proc/sys directory using the sysctl utility. Prototype int result = getSysctl(char *var, char *value, int vlen); Parameters Points to a null terminated string containing the kernel parameter to reference.

  • Page 25: Putsysctl()

    YSTEMS putSysctl() putSysctl() Dynamically modifies the value of the kernel parameters in the /proc/sys directories using the sysctl utility. The changes are valid until the terminal reboots. Currently, users are limited to change only the /proc/sys/net/ipv4 kernel parameters. Prototype int result = putSysctl(char *var, char *value, int vlen); Parameters Points to a null terminated string containing the kernel parameter and value setting, in the format “variable=value”.

  • Page 26: Syslog Messages

    YSTEMS Syslog Messages Syslog The M 800 series of terminals supports logging messages generated by Messages syslog() method calls. These messages are stored in chronological order in the file system /mnt/sram/. This file system is located in the battery-backed SRAM. There are up to four file messages that are dependent on the number of messages that have been logged.

  • Page 27: Downloaded Notes

    IBM ECR – The M 800 series of terminals supports file download from an IBM ECR. The download file will need to be properly formatted using VeriFone’s PCLANCNV utility. The concatenation / compression facility in PCLANCNV will no longer be supported. Instead, files may be converted to .TAR format (concatenation) and GNU Zipped (compressed) and then passed through PCLANCNV.

  • Page 28: File Authentication And Certificates

    All executable code must be authenticated prior to running. File authentication and Certificates authority is split in to two branches. One branch is owned by VeriFone and encompasses Kernel / OS code. This includes driver modules. The second branch is owned by the customer/VAR and encompasses applications.

  • Page 29: Building Ipkgs

    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 M 870 SDK. The terminal resident ipkg module is used to install and remove packages. All user packages are installed with the user home directory (/home/usr1) as the root.
  • Page 30 Package: openssl Source: ./openssl_0.9.8a_mx870.tar.gz Version: 0.9.8a-mx870 Priority: optional Section: libs Maintainer: John Doe <John_d1@verifone.com> Architecture: arm Description: SSL library The library used for Secure Socket Layer communication. If your package has any configuration files, then create a file \control\conffiles which lists the absolute path of each configuration file.

  • Page 31: Installing Ipkgs

    YSTEMS Package Management Version should have at least one digit and should match "[a-zA-Z0-9.+]*". Version may also contain an optional trailing revision matching "-fam[0- 9]\+". This revision should be incremented each time the package changes but the version does not, (i.e. a packaging tweak). It may be reset, (or simply omitted), each time the version is incremented.
  • Page 32 YSTEMS Package Management 800 S ERIES ROGRAMMERS UIDE...

  • Page 33: Hapter

    VeriFone unique device /dev/ipp Delta VeriFone unique device /dev/delta Touch panel Standard Linux /dev/input/mice Details on the standard Linux drivers are available from the open source community. The succeeding sections will detail the VeriFone specific drivers. 800 S ERIES ROGRAMMERS UIDE...

  • Page 34: Magnetic Stripe Reader

    EVICE RIVERS Magnetic Stripe Reader Magnetic Stripe All M 800 series of terminals include a triple track magnetic stripe reader. Reader Accessing the Magnetic Stripe Reader requires linking with the shared library: libvfimsr.so. The header file msrDevice.h is used by the application to access the library.

  • Page 35: Msropen

    EVICE RIVERS msrOpen msrOpen This interface prepares the firmware to accept and store card reads. If the programmer does not make this call, then the terminal will ignore all card reads. The MSR device allows only one open at a time. Prototype int result = msrOpen(int flags, void *callback);...

  • Page 36: Msrread

    EVICE RIVERS msrRead msrRead Read the decoded and formatted MSR data. If the device is not opened with the O_NONBLOCK flag set, this call will be blocked until data is available. Prototype int bytes_read = msrRead(char *buffer, int size); Parameters Pointer to data area buffer Maximum number of bytes to read.
  • Page 37 EVICE RIVERS msrRead The status byte (s1,s2,s3) can have one of the following values: 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 NOTE tries to decode data in both direction streams.

  • Page 38: Msrwrite

    EVICE RIVERS msrWrite msrWrite This operation transfers data from an application buffer into the device driver's buffer. The data is used for the next read operation. Prototype int bytes_written = msrWrite(char *buffer, int size); Parameters Pointer to data area buffer Maximum number of bytes to read.

  • Page 39: Msrmagneticcardpresent

    EVICE RIVERS msrMagneticCardPresent msrMagneticCardPresent Prototype int result = msrMagneticCardPresent(void) Return Values No data available Data available Magnetic field present 800 S ERIES ROGRAMMERS UIDE...

  • Page 40: Msrraw

    EVICE RIVERS msrRaw msrRaw Allows an application to retrieve the raw magnetic stripe data and perform a custom decode. Prototype int result = msrRaw(MSR_DATA * msr); Parameters The MSR_DATA structure is as follows: typedef struct { unsigned char ucStatus; // status of track unsigned char ucCount;...

  • Page 41: Msrstructured

    EVICE RIVERS msrStructured msrStructured Allows an application to retrieve the decoded magnetic stripe data in a structure. Prototype int result = msrStructured(MSR_DATA * msr); Parameters The MSR_DATA structure is as follows: typedef struct { unsigned char ucStatus; // status of track unsigned char ucCount;...

  • Page 42: Msrenablelicensedecode

    EVICE RIVERS msrEnableLicenseDecode msrEnableLicenseDecode Enables the decoding of California Drivers License and American Association of Motor Vehicle Administrators (AAMVA) Drivers License. NOTE By default, California Drivers Licenses will not be decoded. This is for compatibility with existing terminals and tests. Prototype int msrEnableLicenseDecode(void);...

  • Page 43: Msrdisablelicensedecode

    EVICE RIVERS msrDisableLicenseDecode msrDisableLicenseDecode Disables the decoding of California Drivers License and American Association of Motor Vehicle Administrators (AAMVA) Drivers License. NOTE By default, California Drivers Licenses will not be decoded. This is for compatibility with existing terminals and tests. Prototype int msrDisableLicenseDecode(void);...

  • Page 44: Msrversion()

    EVICE RIVERS msrVersion() msrVersion() Prototype int result = msrVersion(char*version) Parameters Pointer to read in the MSR library version, in the form: version xx.yy.zz Return Values Successful execution < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 45: Msrclose

    EVICE RIVERS msrClose msrClose This function disables the card reader input, preventing the terminal from recognizing card reads. Prototype int result = msrClose(void); Return Values Successful execution < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 46: Internal Pin Pad

    EVICE RIVERS Internal PIN Pad Internal PIN Pad In the Omni 7xxx platform, the IPP7 was implemented in hardware. In the M series of terminals, the IPP chip is emulated in software. The application interface is similar to the one in the Vx family of terminals. Applications access the IPP through a virtual communication port.

  • Page 47: Int Ippopen(Void)

    EVICE RIVERS int ippOpen(void) int ippOpen(void) ippOpen() takes ownership of the IPP and clears the internal IPP FIFO. This function always returns 0. Return Values Successful execution 800 S ERIES ROGRAMMERS UIDE...

  • Page 48: Int Ippclose(Void)

    EVICE RIVERS int ippClose(void) int ippClose(void) ippClose() releases ownership of the IPP. All unread data is lost. This function always returns 0. Return Values Successful execution 800 S ERIES ROGRAMMERS UIDE...

  • Page 49: Int Ippread(Char *Buffer, Int Size)

    EVICE RIVERS int ippRead(char *buffer, int size) int ippRead(char *buffer, int size) ippRead() transfers data from the IPP FIFO to the application data buffer. Parameters Pointer to the data area buffer Maximum number of bytes to read size Return Values >...

  • Page 50: Int Ippwrite(Char *Buffer, Int Size)

    EVICE RIVERS int ippWrite(char *buffer, int size) int ippWrite(char *buffer, int size) ippWrite() transfers a single complete IPP packet or a single character from the buffer into the IPP. Incomplete, incorrectly framed packets, overly large, or multiple packets in a single write are rejected. The valid start-of-packet characters are STX and SI.

  • Page 51: Setsecurepindisplayparameters()

    EVICE RIVERS SetSecurePINDisplayParameters() SetSecurePINDisplayParameters() setSecurePINDisplayParameters() sets the hot spot table and registers the callback function for the upcoming PIN session. This function must be called each time prior to requesting a PIN session either through an IPP packet (Z60, Z63 or Z69) or through a VeriShield Security Script API (iPS_RequestPINEntry()).
  • Page 52 EVICE RIVERS SetSecurePINDisplayParameters() For PIN entry, the following hotspots must be defined. CODE =============================== 0x30 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x0D ENTER Optional keys are: CODE ======================================================= 0x30 BACKSPACE - 0x?2 0x31 CLEAR - 0x?3 0x32 OTHER1 - Defines OTHER key #1 - 0x75 0x33...
  • Page 53 EVICE RIVERS SetSecurePINDisplayParameters() With the callback function, the PIN entry process can control the audio and visual aspects as each key press is detected, and its prototype is: void callback(char value); Table 6 Value Action Lower nibble: A numeric key was pressed. A PIN digit has been added to the 0x?1 internal PIN buffer.

  • Page 54: Int Ipppinentrystatus(Int *Count, Int *Lastnonnumerickey)

    EVICE RIVERS int ippPinEntryStatus(int *count, int *lastNonNumericKey) int ippPinEntryStatus(int *count, int *lastNonNumericKey) ippPinEntryStatus() returns the PIN entry status, the number of PIN digits currently in the internal PIN buffer and the code of the last non-numeric key pressed. Pointer to an integer that will receive the current count of count PIN digits in the internal buffer.

  • Page 55: Ippterminatepinentry()

    EVICE RIVERS ippTerminatePinEntry() ippTerminatePinEntry() Ends the PIN session, for example, for a time-out. Prototype int ippTerminatePinEntry(void) Return Values successful < 0 Error -EBADF The task does not own the IPP 800 S ERIES ROGRAMMERS UIDE...

  • Page 56: Ipp Differences

    EVICE RIVERS IPP Differences IPP Differences <SI>0103 PROM Checksum The value of the checksum does not match IPP7 since it is based on the M series terminal code. <SI>0108 IPP ROM Version Number The return packet is: <SI>14IPP8 EMULvvv mm/ yy<SO>{LRC} where vvv is the version number, mm is the release month, and yy is the release...

  • Page 57: References

    Appendix 15 of the Verix V Programmer’s Guide, VDN 23230 GISKE Specification Global Interoperable Secure Key Exchange Key Block Specification V2.3. ACI Worldwide, HP Atalla, Diebold, Thales e-Security, VeriFone, Inc. Security Module This section describes M 800 series of terminals function calls related to security and cryptography.
  • Page 58 EVICE RIVERS VeriShield Security Scripts APIs Up to eight VeriShield Security Scripts can coexist in the unit at a same time. Each script defines its independent key space and defines whether or not those keys can be loaded using the generic key loading functions (iPS_LoadMasterClearKey() and iPS_LoadMasterEncKey()).

  • Page 59: Ips_Deletekeys()

    EVICE RIVERS iPS_DeleteKeys() iPS_DeleteKeys() This function deletes the specified set of keys. Prototype int iPS_DeleteKeys (unsigned long ulKeyType) Parameters Indicates which set of keys are to be erased. Each bit corresponds ulKeyType to a set of keys, meaning that several sets can be erased in one function call.

  • Page 60: Ips_Loadsysclearkey()

    EVICE RIVERS iPS_LoadSysClearKey() iPS_LoadSysClearKey() This function loads the VSS_KLK (i.e. system keys). The values are presented in the clear. Before writing the new value of the key, all other keys in the terminal are erased. This function should be exclusively used in a secure environment. Prototype int iPS_LoadSysClearKey(unsigned char ucKeyID, unsigned char * pucINKeyValue)

  • Page 61: Ips_Loadsysenckey()

    EVICE RIVERS iPS_LoadSysEncKey() iPS_LoadSysEncKey() This function loads the system keys. The new values must be presented encrypted under the current value of VSS_KLK. Contrary to the clear text loading, this encrypted loading does not erase all other secrets in the unit. An error code will be returned if the VSS_KLK is not present.

  • Page 62: Ips_Loadmasterclearkey()

    EVICE RIVERS iPS_LoadMasterClearKey() iPS_LoadMasterClearKey() This function loads the master key of the security script. The values are sent in the clear, but must be all loaded in a same session. Before loading the first key after a power cycle, all keys previously loaded (including the system keys) are erased. This means that loading additional keys in a different session must be done in encrypted form.

  • Page 63: Ips_Loadmasterenckey()

    EVICE RIVERS iPS_LoadMasterEncKey() iPS_LoadMasterEncKey() This function loads the security script’s master keys without deleting the keys already loaded. The new values must be presented encrypted under the current value of VSS_KLK. This function can be used to load the keys defined by the Security Scripts if the option has not been disabled in the script.

  • Page 64: Ips_Checkmasterkey()

    EVICE RIVERS iPS_CheckMasterKey() iPS_CheckMasterKey() This function indicates whether a key is present in the specified location. The Key Verification Code (KVC) argument is irrelevant in M 800 series of terminals because this function is used only for security script keys. The key may be part of a double or triple length DES key, so for security reasons we cannot return the KVC of a portion of the key.

  • Page 65: Setsecurepindisplayparameters()

    EVICE RIVERS SetSecurePINDisplayParameters() SetSecurePINDisplayParameters() setSecurePINDisplayParameters() sets the hot spot table and registers the callback function for the upcoming PIN session. This function must be called each time prior to requesting a PIN session either through an IPP packet (Z60, Z63 or Z69) or through a VeriShield Security Script API (iPS_RequestPINEntry()).

  • Page 66: Ips_Setpinparameter()

    EVICE RIVERS iPS_SetPINParameter() iPS_SetPINParameter() This function configures several parameters for the upcoming VSS PIN session. This function has not effect on IPP PIN sessions. Prototype int iPS_SetPINParameter( PINPARAMETER * psKeypadSetup) Parameters psKeypadSetup typedef struct { unsigned char ucMin, unsigned char ucMax, unsigned char ucEchoChar, unsigned char ucDefChar, unsigned char ucOption,...
  • Page 67 EVICE RIVERS iPS_SetPINParameter() Return Values Successful execution E_KM_OUT_OF_RANGE At least one of the parameters is out of range E_KM_SYSTEM_ERROR 800 S ERIES ROGRAMMERS UIDE...

  • Page 68: Ips_Selectpinalgo()

    EVICE RIVERS iPS_SelectPINAlgo() iPS_SelectPINAlgo() This function selects the PIN algorithm to be used during the next VSS PIN session. The PIN algorithm cannot be changed during a PIN session In the M 800 series of terminals, the only supported mode is 0Bh for use with VeriShield Security Scripts.

  • Page 69: Ips_Requestpinentry()

    EVICE RIVERS iPS_RequestPINEntry() iPS_RequestPINEntry() This function initiates the PIN collection. Once the PIN entry is completed, the PIN is formatted and encrypted according to the algorithm specified by the previous function iPS_SelectPINAlgo. The encrypted PIN block is then placed in a buffer and made available for the iPS_GetPINResponse function.

  • Page 70: Ips_Getpinresponse()

    EVICE RIVERS iPS_GetPINResponse() iPS_GetPINResponse() This function checks the status of the PIN session. It will typically be used by the application in a loop to poll the system until the PIN session ends. The information returned by this function during the PIN session can be used in conjunction with a timer to implement an inter-character timeout as required in certain countries The functions returns the number of PIN digits entered and the last non-numeric pressed.
  • Page 71 EVICE RIVERS iPS_GetPINResponse() Pointer to an object of the following type: pOUTData typedef struct { unsigned char nbPinDigits; unsigned char encPinBlock[8]; } PINRESULT; This structure will return different information depending on the status of the PIN session. If *piStatus is equal to: Done.
  • Page 72 EVICE RIVERS iPS_GetPINResponse() Aborted by user 0x05: or 0x0A: pOUTData ->nbPinDigits The first byte of the buffer pOUTData contains the value of the last ->encPinBlock non-numeric key pressed. Values can be: 0x00: If the last key pressed • was a numeric key (PIN digit).

  • Page 73: Ips_Cancelpin()

    EVICE RIVERS iPS_CancelPIN() iPS_CancelPIN() This function cancels the PIN processing. Prototype int iPS_CancelPIN(void) Return Values Successful execution E_KM_SYSTEM_ERROR 800 S ERIES ROGRAMMERS UIDE...

  • Page 74: Ips_Installscript()

    EVICE RIVERS iPS_InstallScript() iPS_InstallScript() This function authenticates and installs VeriShield Security Script files in the system. The function attempts to authenticate all .VSO files in the vss/ subdirectory in the current user’s home directory. Files must have been signed with a signer certificate that has security script signing capabilities.

  • Page 75: Ips_Getscriptstatus()

    EVICE RIVERS iPS_GetScriptStatus() iPS_GetScriptStatus() This functions checks if a VeriShield Security Script file is installed in the specified script location and if it is the case, returns the name of the script. Prototype int ippGetScriptStatus(unsigned char ucScriptNumber, unsigned char *pucINName ) Parameters Script number.

  • Page 76: Ips_Uninstallscript()

    EVICE RIVERS iPS_UninstallScript() iPS_UninstallScript() This function uninstalls the specified VeriShield Security Script from the unit. The associated keys are deleted. The script file remains in the file system and can be installed again later on. Prototype int ippGetScriptStatus(unsigned char ucScriptNumber) Parameters Script number.

  • Page 77: Ips_Executescript()

    EVICE RIVERS iPS_ExecuteScript() iPS_ExecuteScript() This function spawns the execution of a given macro from a given loaded VeriShield Security Script. Prototype int iPS_ExecuteScript(unsigned char ucScriptNumber, unsigned char ucMacroID, unsigned short usINDataSize, unsigmed char * pucINData unsigned short usMaximumOUTDataSize, unsigned short *pusOUTDataSize, unsigmed char * pucOUTData) Parameters Script number.
  • Page 78 EVICE RIVERS iPS_ExecuteScript() Return Values Successful execution Value in the range [0...255] Macro execution error - The returned value is the value of the opcode that caused the execution error. Refer to VDN 21883 for the list of opcodes. E_VS_SCRIPT_NOT_LOADED This script is not loaded, not authenticated, or not accessible from the current application group.

  • Page 79: Pcps_Getvssversion()

    EVICE RIVERS pcPS_GetVSSVersion() pcPS_GetVSSVersion() This function returns the version of the VeriShield Security Script interpreter. Prototype char* pcPS_GetVSSVersion (void) Parameters Script number. Range [0..7] ucScriptNumbe Return Values It returns a char pointer to the following NULL terminated string: "PSVSSvX.Y" Major version Minor version 800 S ERIES...

  • Page 80: Security Services Apis

    EVICE RIVERS Security Services APIs Security The security device (/DEV/IPP) need not be opened to use the functions listed Services APIs below. All security services functions listed below are defined in the header file svcsec.h. Applications must link with the libvfisec.so library by using lvfisec.

  • Page 81: Cryptowrite()

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

  • Page 82: Cryptoread()

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

  • Page 83: Rsa_Calc()

    EVICE 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 (2 +1), for instance 2, 3, 65537. Prototype int rsa_calc (unsigned char * msg, unsigned char * mod, int wds count, int exp, unsigned char * result);...

  • Page 84: Sha1()

    EVICE RIVERS SHA1() SHA1() This function performs a SHA-1 computation as described in FIPS PUB 180-2. It returns a 20-byte message digest. Due to the underlying messaging interface, it can process a maximum of 1024 bytes per call. Prototype int SHA1 (unsigned char * int option, unsigned char * input_buffer, unsigned long nb, unsigned char * sha20) Parameters option...

  • Page 85: Des()

    EVICE RIVERS DES() DES() This function performs DES, DESX and Triple-DES computations. The operation type and key length are specified using the parameter ucDeaOption. Prototype int DES (unsigned char ucDeaOption, unsigned char *pucDeaKey8N, unsigned char *pucInputData, unsigned char *pucOutputData) Parameters Algorithm ucDeaOption DEAX encryption with single-length key...

  • Page 86: Aes()

    EVICE RIVERS AES() AES() This function performs AES computations on 128-bit data block. The operation type and key length are specified using the parameter ucAesOption. Prototype int AES (unsigned char ucAesOption, unsigned char *pucAesKey8N, unsigned char *pucInputData, unsigned char *pucOutputData) Parameters Algorithm ucAesOption...

  • Page 87: Generaterandom()

    EVICE RIVERS generateRandom() generateRandom() This function returns an 8-byte random value. Prototype int generateRandom (char*random8) Parameters Pointer to the 8-byte buffer where the random value is random8 transferred. Return Values Successful execution < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 88: Isattacked()

    EVICE RIVERS isAttacked() isAttacked() This function indicates if an attack occurred, causing the loss of the transaction keys and/or encrypted files. It returns 0 if no attack occurred since the last key loading or file encryption, otherwise, a value of 1 is returned. It also returns 1 if the unit has never been loaded with a key and no encrypted file has been written.

  • Page 89: Secversion()

    EVICE RIVERS secVersion() secVersion() This function returns the version number strings for the security module and the security library in the form “xx.yy.zz”. Prototype int secVersion(char *pchModVersion, char *pchLibVersion) Parameters Pointer to the 9-byte buffer receiving the security module pchModVersion version number.

  • Page 90: Authfile()

    EVICE RIVERS authFile() authFile() This function checks if the specified file is authenticated. Internally, the function performs two attempts to authenticate the file. If after the first attempt, the file is not authenticated, the system searches for .CRT files in the crt/ subdirectory in the current user home directory.

  • Page 91: Loadosfiles()

    EVICE RIVERS loadOSFiles() loadOSFiles() This function attempts to authenticate all files in the os/ subdirectory in the current user home directory. Files must have been signed with an OS signer certificate. Internally the function performs two attempts to authenticate each file. If after the first attempt the file is not authenticated, the system searches for .CRT files in the crt/ subdirectory in the current user home directory.

  • Page 92: Delta Smartcard Interface / Cardslot

    EVICE RIVERS Delta Smartcard Interface / CardSlot Delta Smartcard The VeriFone Delta Smartcard module will be used to interface the ARM CPU to Interface / the customer smartcard and SAMs. For more details on Smartcard APIs, refer to CardSlot the M CardSlot Library Programmer’s Guide, VDN 23992.

  • Page 93: Serial Communication Control Structure

    EVICE RIVERS Serial Communication Control Structure Serial The following are the structures defined for configuring serial ports on the M Communication series of terminals. They contain all the necessary elements for defining the ports Control into the different modes that each of them support. Structure typedef struct{ short status;...

  • Page 94: Trailer

    EVICE RIVERS Packet Mode Trailer The value contained in the trailer field depends on the defined protocol. Because the trailer field consists of different types, only one type is valid at any time. If tailgate mode is selected as the protocol, then the ECRtailgate_parms will be the valid field.

  • Page 95: Initialize Packet Mode

    EVICE RIVERS Initialize Packet Mode Initialize Packet Mode Prior to reading or writing messages in packet mode, startPktMode() must be called to configure the packet mode parameters. The packet_parms structure (in struct Opn_Blk) must be correctly completed before calling StartPktMode(). Opening the ECR using ecrOpen() is automatically set. If packet mode is required on a port that is not opened with ecrOpen(), then the application is required to fill in this structure.

  • Page 96: Endpktmode()

    EVICE RIVERS endPktMode() endPktMode() endPktMode() is used to free packet mode buffers once a packet mode session is completed. Prototype void endPktMode(void); 800 S ERIES ROGRAMMERS UIDE...

  • Page 97: Receiving Packet Messages

    EVICE RIVERS Receiving Packet Messages Receiving Packet Messages Calling startPktMode() configures a callback function that will be executed upon receiving a message. Prototype void packetRX(char * rxBuffer, int rxLength); Parameters Pointer to a char buffer with received message rxBuffer Length of received message rxLength 800 S ERIES...

  • Page 98: Com Ports On The M 800 Series Of Terminals

    USB port that acts as a serial port and baud rate settings do not apply. Unlike other VeriFone terminals, the serial port devices can be opened for control by more than one process at a time. To prevent others from using the port at the same time, use the following ioctl() calls to have exclusive access to the opened port.

  • Page 99: Com2

    EVICE RIVERS COM Ports on the M 800 series of Terminals COM2 COM2, or device /dev/ttySAC1, supports the following hardware lines: RTS, CTS, DTR, and DCD. The RTS/CTS flow control is under the device driver control, and the RTS line must be controlled by the application.

  • Page 100: Com4 - Optional I/O Module

    EVICE RIVERS IBM ECR Tailgate & Feature C COM4 - Optional I/O COM4, or device /dev/ttySAC2, is available only to the I/O Module and is Module dedicated for RFID capability. A physical serial port connector maybe available as a future enhancement to this module so that it may be connected to a variety of devices.

  • Page 101: Ecropen

    EVICE RIVERS ecrOpen ecrOpen This function opens the port and initializes it according to the I4683 variable. If the visa_sel is non zero, the port is configured for VISA 2 processing. If port_name is specified, then it overrides the setting in the L4683 environment variable. If port_name is not specified, then a null terminated string (“”) should be passed and the value in the L4683 environment variable will be used.

  • Page 102: Ecrread

    EVICE RIVERS ecrRead ecrRead Prototype short bytes_read = ecrRead(char *buffer, short size); Size is the maximum number of bytes to read, and buffer is a pointer to the data area. Each invocation of ecrRead() will transfer data from the port into the buffer, and return the number of bytes actually read or a negative value if an error occurred.

  • Page 103: Ecrreadreject

    EVICE RIVERS ecrReadReject ecrReadReject Prototype short bytes_read = ecrReadReject(char *buffer, short size); Size is the maximum number of bytes to read, and buffer is a pointer to the data area. Each invocation of ecrReadReject() will transfer the rejected data from ecrWrite() into the buffer, and return the number of bytes actually read or zero if no data is available.

  • Page 104: Ecrstatus

    EVICE RIVERS ecrStatus ecrStatus The information returned from ecrStatus() varies depending on whether the port is in Tailgate or Feature C mode and if VISA is enabled. If in Tailgate mode and VISA is enabled: Prototype struct vficomErrCounts *result = ecrStatus(int *buf); Copy current status information to caller’s 4-integer buffer.
  • Page 105 EVICE RIVERS ecrStatus Prototype struct vficomErrCounts *result = ecrStatus(int*buf); Copy current status information to caller’s 4-byte buffer. The number of bytes pending in the input buffer. The number of bytes available (free) in the output buffer. Indicates if ECR is online. A non-zero value indicates the ECR is online (default is 0x37).
  • Page 106 EVICE RIVERS ecrStatus Copy current status information to caller’s 4-integer buffer. Input messages pending A value of 0 means no pending message. A value of greater than 0 means that a message is pending. The number of bytes available (free) in the output buffer. Current signal information for port: (all bits for corresponding signals are set if hardware supports signal for that port and the signal is detected to be asserted.
  • Page 107 EVICE RIVERS ecrStatus If in Feature C mode and VISA is not enabled: Prototype struct vficomErrCounts *result = ecrStatus(int*buf); Copy current status information to caller’s 4-byte buffer. The number of bytes pending in the input buffer. The number of free bytes available in the output buffer. Current signal information for port: (all bits for corresponding signals are set if hardware supports signal for that port and the signal is detected to be asserted.
  • Page 108 EVICE RIVERS ecrStatus Return Values The result return code is a pointer to vficomErrCounts structure which is defined as: struct vficomErrCounts { int frame_err; int over_err; int parity_err; The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function.

  • Page 109: Ecrwrite

    EVICE RIVERS ecrWrite ecrWrite Prototype short bytes_written = ecrWrite(char *buffer, short size); short bytes_written, size; char *buffer; Size is the number of bytes to write, and buffer is a pointer to the data area. This operation transfers data from an application buffer into the driver's buffer, only if the latter has adequate space, and control is returned to the application immediately.

  • Page 110: Ecrclose

    EVICE RIVERS ecrClose ecrClose This function closes the ECR port. Returns 0 if successful. Returns a negative errno error code if an error occurred. Prototype short result = ecrClose(); The port must be closed in order for it to be returned to a known good state. If the NOTE 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...

  • Page 111: Ecrdownload

    EVICE RIVERS ecrDownload ecrDownload This function downloads the APP/OS (uncompressed or compressed ECR format) from the ECR. short result = ecrDownload(char *version, void (*dspCallback) (char *), void (*ecrDnldEnd) (int)); The ECR download functionality operates as a separate thread as its own process after the ecrDownload() function is called.
  • Page 112 EVICE RIVERS ecrDownload Return Values download started successfully the download process failed to start -EBUSY an ECR download process is already running -EINVAL invalid ECR Download End callback specified Callback Return Values download completed successfully never received an Online packet from the ECR or abort download download type not recognized expansion of archived/expressed file, failed A negative...

  • Page 113: Ecrdnldcancel()

    EVICE RIVERS ecrDnldCancel() ecrDnldCancel() This function allows the application to cancel a current download by calling this function anytime. If a download is not currently running then the function will return a –ESRCH (No such process). Otherwise, it will return 0 upon success. Prototype int ecrDnldCancel(void) 800 S...

  • Page 114: Signals

    EVICE RIVERS Signals Signals Signals are present in practically all Unix/Linux systems and are a mechanism to inform processes of an event that has occurred. Signals have default behavior and documentation on all the signals available and their default actions can be found in practically any Linux/Unix programming book.
  • Page 115 EVICE RIVERS Signals The SIGIO signal is issued by the OS whenever any hardware device detects data I/O has occurred. For example, an application may like to know when data is available on a serial port. The application could create a signal handler for the SIGIO signal associated with the file descriptor (handle) of the open port.

  • Page 116: Ecr Environment Variables

    EVICE RIVERS ECR Environment Variables The M 800 series of terminals OS has provided a function that conveniently does this for the application called svcAlarm(). This function must be used in conjunction with the svcSetAlarmCallback() function. When the application no longer needs to be notified of an Alarm signal, it must unregister its callback function with using svcReleaseAlarmCallback().

  • Page 117: A4683

    EVICE RIVERS ECR Environment Variables A4683 Indicates the application id number. This is copied from the application id field of O4683 after a successful download. P4683 Indicates the parameter id number. This is copied from the parameter id field of O4683 after a successful parameter download.

  • Page 118: S4683

    EVICE RIVERS ECR Environment Variables COM4 can also be available if the M 800 series terminal custom optional module is present with a physical serial connector. This module may be available as a future enhancement. Whenever flow control is enabled via the svcSetOpenBlock() function, then RTS is also asserted and held, regardless if “R”...

  • Page 119: Downloading Files From The Ecr

    EVICE 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: Program File named EFTLxxxx , xxxx represents the program version number. Parameter File named EFTPyyyy, yyyy represents the parameter version number.

  • Page 120: Touch Panel / Signature Capture/Tiff

    The touch panel is calibrated (also called compensated) at the factory. The factory Signature calibration is used by the system until it is periodically updated. VeriFone strongly Capture/TIFF recommends that the touch panel be calibrated daily during a period of inactivity.

  • Page 121: Touchcmd()

    EVICE RIVERS touchCmd() touchCmd() touchCmd() is used to set and get touch panel functionality per the following table: Table 7 value return Notes Bit values Returns the status of the stylus. Bits 1 or 2 = 1 if a stylus is attached All other bits reserved.

  • Page 122: Touchcompnsave()

    The terminal must not be touched between the time this function is called and the time it returns. VeriFone recommends that touchCompNSave() be called once per day. VeriFone also recommends that the backlight be turned off during touch panel calibration. Prototype...

  • Page 123: Signature Capture

    EVICE RIVERS Signature Capture Signature Signature Capture is implemented as a widget at the FancyPants GUI level. The Capture widget supports the definition of a signing region as well as the ability to track stylus movement. Note that the strokes returned by the Signature Capture widget are scaled to 320x234 (72dpi).

  • Page 124: Sigcapcount()

    EVICE RIVERS SigCapCount() SigCapCount() Returns the number of signature points that are currently available. Prototype int SigCapCount(void) 800 S ERIES ROGRAMMERS UIDE...

  • Page 125: Sigcapget()

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

  • Page 126: Sigcapboxapply()

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

  • Page 127: Tiff Api

    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.

  • Page 128: Int Sigcap2Tiff()

    EVICE 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 is a pointer to the user’s signature data buffer consisting of points of type xyz_t.
  • Page 129 EVICE RIVERS int SigCap2Tiff() Return Values Success < 0 Error NOTE The setTiffUserTags function can override the default date/time tag that is automatically inserted into the file. This is an optional user-supplied function that can over-ride standard tags (but be careful or the TIFF image may be affected or unusable) and can also define and specify new user tags in the range MIN_TIFFTAG_USER to MAX_TIFFTAG_USER (both defined in sigtiff.h.)

  • Page 130: Display

    EVICE RIVERS Display Display The user interface is managed by the FST FancyPants GUI. 800 S ERIES ROGRAMMERS UIDE...

  • Page 131: Dspsetbrightness()

    EVICE RIVERS dspSetBrightness() dspSetBrightness() Allows the display brightness to be adjusted. If direction is 1, the brightness will be increased. If direction is 0 the brightness will be decreased. There are 32 discrete brightness settings. The brightness can be adjusted significantly by repeated calls to dspSetBrightness.

  • Page 132: Audio / Beeper

    EVICE RIVERS Audio / Beeper Audio / Beeper At the lower level, the M 800 series terminal kernel will implement a sound device using the Open Sound System (OSS) specification. See: http:// www.opensound.com/ Applications written to the OSS specification should run on the M 800 series of terminals.

  • Page 133: Soundctrl()

    EVICE RIVERS soundCtrl() soundCtrl() The VeriFone supplied library (libvfisvc.so) contains support for controlling the audio volume, bass, and treble via the following API: Prototype int soundCtrl(int volume, int bass, int treble) Parameters Accepted values: 0-100 volume Sound off Maximum volume...

  • Page 134: Speaker()

    RIVERS speaker() speaker() The VeriFone supplied library (libvfisvc.so) contains support for enabling / disabling the built in speakers. Disabling the built in speakers may be desirable if external speakers are connected to the Audio lineout connector on the multi-port cable.

  • Page 135: Normaltone() / Errortone()

    EVICE RIVERS normalTone() / errorTone() normalTone() / errorTone() Prototype normalTone() errorTone() NOTE Some M 800 series terminals may lack sound capability and will only support a traditional beeper. In this case, the legacy API will be supported. 800 S ERIES ROGRAMMERS UIDE...

  • Page 136: Leds

    EVICE RIVERS LEDs LEDs One of the features of the M 800 series of terminals are the three blue LEDs located in Magnetic Stripe Reader. The purpose of these LEDs is to inform the user that they can swipe their card. More complex use of the LEDs will require a thread or timer for synchronization.

  • Page 137: Ledon

    EVICE RIVERS ledOn ledOn ledOn() is used to turn 1 or more of the LEDs on. A bit mask is used to select the LED(s) to turn on. Prototype void ledOn(int parm) Parameters parm Top LED LED1 Middle LED LED2 Bottom LED LED3 To turn on all three LEDs,...

  • Page 138: Ledoff

    EVICE RIVERS ledOff ledOff ledOff() is used to turn 1 or more of the LEDs off. A bit mask is used to select the LED(s) to turn off. Prototype void ledOff(int parm) Parameters parm Top LED LED1 Middle LED LED2 Bottom LED LED3 To turn off all three LEDs,...

  • Page 139: Real-Time Clock (Rtc)

    (RTC) or modifying that API. The M 800 series of terminals include VeriFone specific RTC hardware required to keep the time accurate when the unit is turned off. On power up, the operating system will automatically set the Linux (soft) RTC from the M 800 series terminal RTC hardware.

  • Page 140: Setrtc()

    EVICE RIVERS setRTC() setRTC() Used to set the RTC hardware to the Linux RTC time/date. This function must be called immediately after any function that sets the Linux RTC time/date. There are no parameters or return codes from setRTC(). Prototype void setRTC(void) 800 S ERIES...

  • Page 141: Setdatetime()

    EVICE RIVERS setDateTime() setDateTime() As user processes are not allowed to set the Linux RTC, applications must call setDateTime() passing the date and time in the same format used in the shell command date. Format: MMDDhhmmYYYY.ss • MM = Month •...
  • Page 142 EVICE RIVERS setDateTime() 800 S ERIES ROGRAMMERS UIDE...

  • Page 143: Service Functions

    HAPTER Service Functions Service This chapter lists the service function APIs used in the M 800 series of terminals. Functions for the M 800 series of Terminals 800 S ERIES ROGRAMMERS UIDE...

  • Page 144: Svccrccalc()

    ERVICE UNCTIONS svcCrcCalc() svcCrcCalc() Prototype checksum = svcCrcCalc(type, buffer, size) int checksum, type, size; char*buffer; Parameters This routine returns the cyclic redundancy check for a string contained in buffer of a length specified by size. Each type is now specified by referring to a standard CRC description model which can be found by searching the Internet for “A Painless Guide to CRC Error Detection Algorithms”...
  • Page 145 ERVICE UNCTIONS svcCrcCalc() CRC32, lsb-first, reflected input and output Model: width=32,poly=0x04C11DB7,init=0,refin=1,refot=1,xorot=0, check=0x2DFD2D88 CRC32, lsb-first, reflected input & output, inverted result Model: width=32,poly=0x04C11DB7,init=-1,refin=1,refot=1,xorot=-1, check=0xCBF43926 CRC16, msb-first, reflected input and output Model: width=16,poly=0x8005,init=0,refin=1,refot=1,xorot=0,check=0xBB3D CCITT16, msb-first, reflected input and output Model: width=16,poly=0x1021,init=0,refin=1,refot=1,xorot=0,check=0x6F91 For both CRC16 computations, the initial value used for the checksum will be NOTE reset to all zeros (0x0000).

  • Page 146: Svcdsp2Hex()

    ERVICE UNCTIONS svcDsp2Hex() svcDsp2Hex() This command causes the data at dsp to be converted and stored at location hex. The presumption is that the input (at dsp) consists of count pairs of bytes, with each byte in the range of 30h-90h (ASCII 0-9) or 42h-46h (ASCII A-F). Each byte will then be converted to the corresponding hexadecimal nibble (hex 0-9, A- This function will convert up to a long hex value for the corresponding ASCII array.

  • Page 147: Svcrestart()

    ERVICE UNCTIONS svcRestart() svcRestart() This routine will reboot the terminal. The terminal will shut down and then start up as if it has just been started initially at power on. NOTE Set the configuration variable *GO if you wish to restart and begin execution of a specific application.

  • Page 148: Svcinfokernel() / Svcinfoeprom()

    ERVICE UNCTIONS svcInfoKernel() / svcInfoEprom() svcInfoKernel() / svcInfoEprom() This function fills buffer with the current firmware ID in null-terminated string format. Prototype svcInfoKernel(buffer); svcInfoEprom(buffer); char *buffer; The M 800 series of terminals has been assigned the identifier, Mx. Released OS versions will be MxXxYyAa.

  • Page 149: Svcinforfs()

    ERVICE UNCTIONS svcInfoRFS() svcInfoRFS() This function fills buffer with the current version of the root file system. The eight character string is null-terminated. Prototype SvcInfoRFS(buffer); char*buffer; 800 S ERIES ROGRAMMERS UIDE...

  • Page 150: Svcinfoserialnum()

    ERVICE UNCTIONS svcInfoSerialNum() svcInfoSerialNum() This function fills buffer with the unit’s serial number in the form: xxx-xxx-xxx. The 11-character string is null terminated. The serial number returned will match the serial number sticker on the bottom of the unit. Prototype SvcInfoSerialNum(buffer);...

  • Page 151: Svcinfoptid()

    ERVICE UNCTIONS svcInfoPtid() svcInfoPtid() This function fills buffer with the UNIT ID in null-terminated string format. Prototype svcInfoPtid(buffer); char*buffer; Default value 12000000 800 S ERIES ROGRAMMERS UIDE...

  • Page 152: Svcinfoplatform()

    ERVICE UNCTIONS svcInfoPlatform() svcInfoPlatform() This function provides information about the terminal running the application. feature can be one of the following values: Table 8 Feature Definition 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...
  • Page 153 ERVICE UNCTIONS svcInfoPlatform() If feature = 3, then the value in result will be the amount of static RAM currently installed in kilobytes. If feature = 4, then the following bit values are returned, for multi-port cable status: Table 10 Bits Definition Value...

  • Page 154: Svcinfotype()

    ERVICE UNCTIONS svcInfoType() svcInfoType() This function provides more information about the terminal running the application. feature can be one of the following values: Processor type: 6 = S3C2410 Platform: 1000 = M 800 series of terminals Prototype result = svcInfoType(feature); int result, feature;...

  • Page 155: Svcinfodsp()

    ERVICE UNCTIONS svcInfoDsp() svcInfoDsp() This function provides information about the physical characteristics of the display on the terminal running the application. feature can be one of the following values: 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)

  • Page 156: Svcinfocard()

    ERVICE UNCTIONS svcInfoCard() svcInfoCard() This function provides information about the type of card reader supported by the terminal on which the application is running. feature must be a value of 0. feature = 0 Bit map of supported track options 0x01 Dual track 0x02...

  • Page 157: Svcinfokey()

    ERVICE UNCTIONS svcInfoKey() svcInfoKey() This function provides information about the type of keyboard supported by the terminal on which the application is running. feature can be one of the following values: number of standard keys: returns 0 number of non-screen-addressable function keys: returns 0 number of screen-addressable function keys: returns 0 keypad layout (0=telco, 1=calculator, 2=Touch): returns 2 If return value is >0 then a touch panel is installed: returns 1...

  • Page 158: Svcinfoserialnum

    ERVICE UNCTIONS svcInfoSerialNum svcInfoSerialNum Returns the serial number of the unit. This is the same serial number that is on the unit’s label. The returned string is null-terminated. Format of buf: xxx-xxx-xxx xxx-xxx-xxx is an ASCII 11-digit string. (e.g. 000-012-030) Return Values result = svcInfoSerialNum(char *buf);...

  • Page 159: Svczontalkrcv()

    ERVICE UNCTIONS svcZontalkRcv() svcZontalkRcv() svcZontalkRcv() allows an application to perform a LOCAL DL/Zontalk/ VeriTalk download. The application must open and configure the port prior to calling this function. NOTE svcZontalkRcv()is a threaded function and will return immediately. The return code will be < 0 if the download could not be initialized. The application will receive a callback when the download has completed (on success of failure).
  • Page 160 ERVICE UNCTIONS svcZontalkRcv() If the server application supports embedding environment variables in the download stream, then svcZontalkRcv() will set these environment variables in the users configuration file. If any of the above two environment variables are already set prior to initiating a download, then their values will be used as described above.

  • Page 161: Zontalkcancel

    ERVICE UNCTIONS zontalkCancel zontalkCancel Cancels a Zontalk/DL download (initiated by svcZontalkRcv). In System Mode, the user can cancel the download by touching the System Mode screen before the download is completed. The message, DOWNLOAD CANCELLED will then be displayed on the screen. Prototype result = zontalkCancel();...

  • Page 162: Svcsetopenblock()

    ERVICE UNCTIONS svcSetOpenBlock() svcSetOpenBlock() The svcSetOpenBlock() function accepts a pointer to an Open Block structure that has been populated by the application to the desired port settings. This function then takes the open block settings and properly maps them to Linux serial port settings and sets the port to these values.

  • Page 163: Svcsetrxcallback()

    ERVICE UNCTIONS svcSetRxCallback() svcSetRxCallback() The svcSetRxCallback() function is used to specify a function that an application wants to be called whenever data is received on a particular device designated by the file descriptor parameter. When the svcSetRxCallback() function is called it checks to determine if the ECR has been opened. If Visa mode is enabled then the callback function will be called when a complete Visa packet is available.

  • Page 164: Svcreleaserxcallback()

    ERVICE UNCTIONS svcReleaseRxCallback() svcReleaseRxCallback() The svcReleaseRxCallback() function must be used when the application no longer needs to know if data I/O has occurred on a particular device associated with the file descriptor (handle) given. The file descriptor (fd) passed to this function should be the same one that was used to register a callback function for the device with svcSetRxCallback().

  • Page 165: Svcsetalarmcallback()

    ERVICE UNCTIONS svcSetAlarmCallback() svcSetAlarmCallback() The svcSetAlarmCallback() function is used to specify a function that an application wants to be called whenever the SIGALRM signal is issued by that process. The application should call this function whenever it wants to register a callback function to be called when the SIGALRM signal is issued and it should provide the process ID of the process that will issue the signal.

  • Page 166: Svcreleasealarmcallback()

    ERVICE UNCTIONS svcReleaseAlarmCallback() svcReleaseAlarmCallback() The svcReleaseAlarmCallback() function must be used when the application no longer needs to know if the SIGALRM signal has been issued for a particular process. The process ID (pid) passed to this function should be the same one that was used to register a callback function for the device with svcSetAlarmCallback().

  • Page 167: Svcalarm()

    ERVICE UNCTIONS svcAlarm() svcAlarm() The svcAlarm() function can conveniently be used to set the number of seconds to wait before a SIGALRM signal is issued to the current process. This function can only be used if the SIGALRM signal is to be issued to the current process.

  • Page 168: Svcgetportstatus()

    ERVICE UNCTIONS svcGetPortStatus() svcGetPortStatus() The svcGetPortStatus() function returns the following information regarding the port: NOTE The M 800 series terminal does not support the detection of parity errors on the COM ports due to the limitations of the ARM processor. Prototype struct vficomErrCounts *svcGetPortStatus(int inFd, int *buf) Parameters...
  • Page 169 ERVICE UNCTIONS svcGetPortStatus() The return value of svcGetPortStatus() is a pointer to vficomErrCounts structure which is defined in vficom.h as the following: struct vficomErrCounts { int frame_err; int over_err; int parity_err; The pointer to this structure will contain the error counts for the port described by the file descriptor passed into the function.

  • Page 170: Svcgetinq()

    ERVICE UNCTIONS svcGetInQ() svcGetInQ() The svcGetInQ() function returns the number of bytes pending in the port’s input queue. Prototype int svcGetInQ(int inFd) Parameters The file descriptor associated with the open port device. inFd 800 S ERIES ROGRAMMERS UIDE...

  • Page 171: Svcgetoutq()

    ERVICE UNCTIONS svcGetOutQ() svcGetOutQ() The svcGetOutQ() function returns the number of bytes pending in the port’s output queue. Prototype int svcGetOutQ(int inFd) Parameters The file descriptor associated with the open port device. inFd 800 S ERIES ROGRAMMERS UIDE...

  • Page 172: Svcexpand()

    ERVICE UNCTIONS svcExpand() svcExpand() Prototype int svcExpand(char *inFile, int keepinFile, char *uowner) Parameters inFile Pointer to a string containing the name of the file to expand. This file should be in a tar format with or without either GNU zipped or binary zipped compression.

  • Page 173: Svcusbstorpresent()

    ERVICE UNCTIONS svcUsbStorPresent() svcUsbStorPresent() The svcUsbStorPresent() function determines how many USB storage/ memory devices are currently plugged into the USB host port, mounted properly and ready for access. If so, then it sets a value of 1 in each byte of the array pointed to by usbStorDevPresent.

  • Page 174: Com3 Service Functions

    ERVICE UNCTIONS COM3 Service Functions COM3 Service The COM3 service functions are for tuning and configuring the communication Functions processor used on the COM3 port. These functions were brought up to the API level in case there is a need to use them directly in an application for a special architecture/configuration.

  • Page 175: Svccom3Setmode()

    ERVICE UNCTIONS svcCom3SetMode() svcCom3SetMode() The svcCom3SetMode() function allows the application to manually set the mode for the COM3 port according to what kind of port COM3 should function as. If ecrOpen() is used, this is done automatically according to the ECR environment variables.

  • Page 176: Svccom3Reqextstatus()

    ERVICE 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 2- byte value that indicates the configuration and handshake settings for the port. This function returns 0 upon success and a negative value if unsuccessful.
  • Page 177 ERVICE UNCTIONS svcCom3ReqExtStatus() Where: DevStat2 = Handshake Status Where: Table 15 Mnemonic Description RE Receive enable Receive disabled Receive enabled FHW Trransmit wait status Transmit wait on handshake disabled Transmit wait on handshake enabled FAO Auxiliary Out state Aux Out is in idle state Aux Out is in Asserted state FCO Control Out state Control Out is in Idle state...

  • Page 178: Svccom3Reqtallyinfo()

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

  • Page 179: Svccom3Restallydata()

    ERVICE UNCTIONS svcCom3ResTallyData() svcCom3ResTallyData() The svcCom3ResTallyData() function resets all the tally counters to zero. Prototype short svcCom3ResTallyData(int fd) Parameters 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. 800 S ERIES ROGRAMMERS...

  • Page 180: Svccom3Reqfirmvers()

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

  • Page 181: Svccom3Setdeviceaddr()

    ERVICE 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 M 800 series terminal will respond to a poll from the ECR.

  • Page 182: Svccom3Seteclevel()

    ERVICE UNCTIONS svcCom3SetECLevel() svcCom3SetECLevel() The function svcCom3SetECLevel() function sets the ECR engineering change level that is reported to the ECR in response to the Request EC command. This value is logged by the ECR and may be used to invoke version specific drivers. The legal values are 00-FF and the default is FF corresponding to an OEM device.

  • Page 183: Svccom3Sethandshake()

    ERVICE UNCTIONS svcCom3SetHandshake() svcCom3SetHandshake() The svcCom3SetHandshake() function sets the handshake byte to the value indicated. Return Values This function returns 0 upon success and a negative value if unsuccessful. The value of the handshake control byte can be read using the svcCom3ReqExtStatus() function.
  • Page 184 ERVICE UNCTIONS svcCom3SetHandshake() Prototype short svcCom3SetHandshake(int fd, char hs) Parameters File descriptor returned when opening a serial port with either open() or ecrOpen(). A 1 byte value that indicates the handshake control. 800 S ERIES ROGRAMMERS UIDE...

  • Page 185: Svccom3Flushrxbuf()

    ERVICE UNCTIONS svcCom3FlushRxBuf() svcCom3FlushRxBuf() The svcCom3FlushRxBuf() function allows the application to manually flush the receive buffer internal to the communication processor. This command is meaningful only in RS232 mode: MODE_R232_INT. Prototype short svcCom3FlushRxBuf(int fd) Parameters File descriptor returned when opening a serial port with either open() or ecrOpen().

  • Page 186: Svccom3Setrxrecthresh()

    ERVICE UNCTIONS svcCom3SetRxRecThresh() svcCom3SetRxRecThresh() The svcCom3SetRxRecThresh() function allows the application to set the receive record threshold (RRT). This threshold is used to set the minimum size of receive records returned to the host from the communication processor. This command is not valid in COM3 tailgate mode: MODE_SIO_INT and has no effect if used in this mode.

  • Page 187: Svccom3Setbufflushint()

    ERVICE UNCTIONS svcCom3SetBufFlushInt() svcCom3SetBufFlushInt() The svcCom3SetBufFlushInt() function allows the application to manually set the buffer flush interval. This value indicates when a record that is less in size than the Receive Record Threshold is to be released to the host. It sets the maximum latency, in milliseconds, for receive characters to reside in the communication processor receive buffer before a record is released.

  • Page 188: Svccom3Polled()

    ERVICE UNCTIONS svcCom3Polled() svcCom3Polled() The svcCom3Polled() function allows the application to check if the ECR address the M 800 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.

  • Page 189: Svcgetsysmillisec(), Svcgetsysmicrosec()

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

  • Page 190: Enableprocessmonitor()

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

  • Page 191: Disableprocessmonitor()

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

  • Page 192: Enablebuttonsig()

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

  • Page 193: Disablebuttonsig()

    ERVICE 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. 800 S ERIES ROGRAMMERS UIDE...
  • Page 194 ERVICE UNCTIONS disableButtonSig() 800 S ERIES ROGRAMMERS UIDE...

  • Page 195: System Mode

    HAPTER System Mode System Mode for The M 800 series of terminals’ System Mode will be a departure from previous the M 800 series products in that a graphical user interface will be used for presentation. The of Terminals System Mode idle display will have pertinent terminal configuration and status information on the top and bottom border of the display and task driven icons in the center.
  • Page 196 YSTEM System Mode for the M 800 series of Terminals File Transfer Direct load, ECR download, FTP. File Manager Supports launching the application associated with *GO and rebooting the system. Security VeriShield Security, displays the certificate IDs and serial numbers. Key Status –...

  • Page 197: Root File System

    HAPTER Root File System The Embedded Linux OS is much more than a kernel. A number of significant applications and modules are required to complete the system. These applications, libraries and driver modules reside in the root file system. BusyBox - Combines tiny versions of many common UNIX utilities into a single small executable.

  • Page 198: Directory Structure

    YSTEM Directory Structure Directory Linux / Unix has a long history with respect to the root file system directory Structure structure. This document will not attempt to explain this history. If you are interested, see: http://www.pathname.com/fhs/. boot dev home lib mnt proc root sbin initrd...

  • Page 199: User Space Base Directory Structure

    YSTEM Directory Structure User Space Base User space directories will be placed under /home. Directory Structure /home ---- usr1 ---- usr2 ---- usr x The following base directory tree will be defined under each /user: /home ---- usr1 ---- crt ---- vss ---- os NOTE...
  • Page 200 YSTEM Directory Structure 800 S ERIES ROGRAMMERS UIDE...

  • Page 201: Usb - Device / Host

    HAPTER USB - Device / Host The M 800 series supports two USB ports. One port (on the multi-port cable) supports either the host or device function. The multi-port cable determines the type of USB port. The second USB port is always the host and is available on the I/O module interface.

  • Page 202: Usb Host

    USB - D EVICE USB Host USB Host The M 800 series of terminals supports USB host functionality and can run specific drivers for a multitude of different devices that can be plugged into the 800 series terminal. Currently, the M 800 series of terminals has been tested with the following devices: •...
  • Page 203 USB - D EVICE USB Host Each directory will be used in order as the devices are plugged into the unit. If a device is removed, it is automatically unmounted from the directory mount point and the data on it is no longer accessible. While the device is plugged in, the data can be accessed by an application.

  • Page 204: Usb Human Interface Device (Hid) Support

    USB - D EVICE USB Human Interface Device (HID) Support USB Human The M 800 series terminal also has built in USB HID support for some devices Interface Device through the Linux kernel Input Event module. When a HID is plugged into the USB (HID) Support Host port, it is automatically detected and the appropriate USB HID and event drivers are loaded.

  • Page 205: Network Configuration

    HAPTER TCP/IP Ethernet The M 800 series terminal supports TCP/IP networking on the Ethernet port. The network configuration and program APIs are contained in this chapter. The M series fully support the Linux sockets interface for client and server network programming.

  • Page 206: Netup()

    TCP/IP E THERNET netUP() netUP() Activates the Ethernet network interface eth0 for sending and receiving. This function uses the Network Configuration environment variables and either NOTE the *DHCP or *IFCONFIG variable must exist. *DHCP takes precedence if both variables exist Prototype int result= netUp(void) Return Values...

  • Page 207: Netdown()

    TCP/IP E THERNET netDown() netDown() Deactivates the Ethernet network interface eth0. This also deletes the routing entries for this interface. Prototype int result= netDown(void) Return Values Success < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 208: Netgetconfig()

    TCP/IP E THERNET netGetConfig() netGetConfig() Returns the network configuration parameters of the eth0 network interface. The network interface must be up. Prototype int result = netGetConfig(net_conf_t *net) Parameters Pointer to the network configuration structure to be filled: typedef struct { net_conf_t members Description int dhcp;...

  • Page 209: Netlinkstatus()

    TCP/IP E THERNET netLinkStatus() netLinkStatus() Returns the link status of the specified network interface. Prototype int result = netLinkStatus(void) Return Values Link is up. Interface down or Ethernet cable is unplugged. < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 210: Getsysctl()

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

  • Page 211: Supported Network Programs

    TCP/IP E THERNET Supported Network Programs Supported The M 800 series of terminals API includes support for common networking Network programs such as ping and FTP file transfers. Programs For FTP file transfers, the FTP server must support passive mode for the data socket connection and the file transfers are always in binary mode.

  • Page 212: Netping()

    TCP/IP E THERNET netPing() netPing() Tests whether the remote host is reachable. NOTE This program sends an ICMP message to the remote host asking for acknowledgement. Prototype int result = netPing(char *host) Parameters Pointer to remote host either in the “xxx.xxx.xxx.xxx” IP address host format or fully qualified domain name.

  • Page 213: Ftpget()

    TCP/IP E THERNET ftpGet() ftpGet() Transfers the file from the FTP server to the terminal. NOTE This function logs in to the FTP server, retrieves the file, and logs off. Prototype int result = netGetConfig(net_conf_t *net) Parameters Pointer to the FTP parameter structure. typedef struct{ ftpHost In the “xxx.xxx.xxx.xxx”...

  • Page 214: Ftpput()

    TCP/IP E THERNET ftpPut() ftpPut() Transfers a file from the terminal to the FTP server. NOTE This function logs in to the FTP server, sends the file to the server, and logs off. Prototype int result = ftpPut(FTP_parm_t *ftp) Parameters Pointer to FTP parameter structure (see ftpGet()).

  • Page 215: Ipp Legacy Library

    HAPTER IPP Legacy Library IPP Support for This chapter describes the IPP support functions ported from the TXO platforms the M 800 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...
  • Page 216 IPP L EGACY IBRARY IPP Support for the M 800 series of Terminals • There is no IPP trap mechanism on the M 800 series of terminals. • The Interac mode support functions are not implemented on the M 800 series of terminals.

  • Page 217: Ipp_Getpin()

    IPP L EGACY IBRARY ipp_getpin() ipp_getpin() This command passes the appropriate parameters to define PIN entry. Prototype result = ipp_getpin(key_type, disp_line, min_pin_len, max_pin_len, zero_pin_ok, max_time, pan, working_key, master_key); int result, key_type, max_time, master_key; char dsp_line, min_pin_len, max_pin_len, zero_pin_ok, *working_key, *pan); Parameters 0 for Master Key Management, 1 for DUKPT key_type...
  • Page 218 IPP L EGACY IBRARY ipp_getpin() Return Values Successful PIN Entry Occurring Too many PIN entry requests in a short period - Retry later. Invalid parameter or IPP communication error. Prior to issuing this command, the setSecurePINDisplayParameters() function must be used to register the “PIN feedback” callback function and to load the hotspot table.

  • Page 219: Ipp_Read()

    IPP L EGACY IBRARY ipp_read() ipp_read() This function returns the encrypted PIN block generated by ipp_getpin(). Prototype result = ipp_read(buffer, size); intresult; unsigned int size; char *buffer; Parameters User defined buffer in the application space where the information is to buffer be stored.
  • Page 220 IPP L EGACY IBRARY ipp_read() For Master Session Key Management, the buffer contains the following packet: Start of text, value 02h value ‘71' packet type value '.' delimiter value 0 if function key feature not implemented Function key value 00 or 04 -12 PIN length value 01 - format prior to encryption PIN Block Format...
  • Page 221 IPP L EGACY IBRARY ipp_read() In case of an input error, the packet looks like: Start of text, value 02h value ‘73' packet type "1" = No key error code "2" = key serial number error "3” = PIN length over Max "4”...

  • Page 222: Ipp_Mac()

    IPP L EGACY IBRARY ipp_mac() ipp_mac() This function performs a MAC calculation on the user data and returns the resultant value. Prototype return = ipp_mac(master_key, working_key, second_key, message, message_length, result); int return; unsigned int message_length; char master_key, second_key, *working_key, *message, *result; Parameters ASCII "0...9"...
  • Page 223 IPP L EGACY IBRARY ipp_mac() The resultant MAC value is placed in the users result buffer and is formatted as follows: Process code field One character, indicates status "0" = no error and MAC follows MAC field 16 character MAC value The message parameter is blocked into 32-byte blocks and a running calculation is performed on each block.

  • Page 224: Ipp_Abort()

    IPP L EGACY IBRARY ipp_abort() ipp_abort() This function aborts PIN collection. Prototype return = ipp_abort(void); int return; Return Values Successfully aborted Failure to abort On successful return, the Application gets control of the keyboard and display. NOTE If PIN collection is not running when this function is called, then a 0 is returned. 800 S ERIES ROGRAMMERS...

  • Page 225: Ipp_Diag()

    IPP L EGACY IBRARY ipp_diag() ipp_diag() This function executes various IPP diagnostics. The application can use this function to check information on the IPP firmware as well as perform 1DES test encryptions. Prototype return = ipp_diag(test_type, result, master_key); return, test_type, master_key; char *result;...
  • Page 226 IPP L EGACY IBRARY ipp_diag() All strings are null terminated. For DUKPT and Master/Session Encryption tests, the usual prompts for necessary information have been hard coded for the purpose of this diagnostic. The values for this information are: M/S working_key 1234567890123456 DUKPT working_key DUKPT ENCRYPTION...

  • Page 227: Select_Key_Mgmnt()

    IPP L EGACY IBRARY select_key_mgmnt() select_key_mgmnt() This function selects the Key Management method. It allows selection of Master/ Session and DUKPT methods, either Single DES (1DES) or Triple DES (3DES) as well as Secure Messaging and Zero Key support. Prototype return = select_key_mgmnt(kmm, demf);...
  • Page 228 IPP L EGACY IBRARY select_key_mgmnt() 1 char binary encoded 7 6 5 4 3 2 1 0 demf DUKPT Engine "1" - - - - - - - 0 1DES DUKPT (default) - - - - - - - 1 3DES DUKPT DUKPT Engine "2"...

  • Page 229: Get_Key_Mgmnt()

    IPP L EGACY IBRARY get_key_mgmnt() get_key_mgmnt() This function is used to check the current Key Management settings. Prototype return = get_key_mgmnt(kmm, demf); int return; char *kmm, *demf; Parameters 1 char binary encoded 7 6 5 4 3 2 1 0 --------------- - - - - - 0 0 0 1DES Master/Session (default)
  • Page 230 IPP L EGACY IBRARY get_key_mgmnt() 1 char binary encoded 7 6 5 4 3 2 1 0 demf DUKPT Engine "1" - - - - - - - 0 1DES DUKPT (default) - - - - - - - 1 3DES DUKPT DUKPT Engine "2"...

  • Page 231: Contactless Rf Card Reader Module

    HAPTER Contactless RF Card Reader Module The M 800 series of terminals supports the Contactless RF Card Reader Module. The module communicates over the COM4 serial port (/dev/ttySAC2) at 19200bps 8N1 using a simple command and response protocol. The user space shared library libvfirfcr and the RFCRapi.h header file helps to interface common features of the module and are detailed in this chapter.

  • Page 232: Rfcrlibversion()

    RF C ONTACTLESS EADER ODULE RFCRlibVersion() RFCRlibVersion() Prototype int RFCRlibVersion(char *libVersion) Parameters Pointer to read in the RFCR library version, in the form: libVersion “xx.yy.zz” Return Values > = 0 Success < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 233: Rfcrinit()

    RF C ONTACTLESS EADER ODULE RFCRInit() RFCRInit() RFCRInit() performs device initialization, opens, and configures the serial port. The device handle that is returned on success can be used by the applications. Prototype int RFCRInit(void); Return Values > 0 Success, and the device handle is returned. <...

  • Page 234: Rfcrgetversion()

    RF C ONTACTLESS EADER ODULE RFCRGetVersion() RFCRGetVersion() Prototype int RFCRGetVersion(char *fwVersion); Parameters Pointer to read in the RFCR firmware version fwVersion Return Values Success < 0 Error -EBADF if not initialized > 0 NAK error 800 S ERIES ROGRAMMERS UIDE...

  • Page 235: Rfcrping()

    RF C ONTACTLESS EADER ODULE RFCRPing() RFCRPing() Tests if the RFCR module is alive and responding Prototype int RFCRPing(void); Return Values Success < 0 Error -EBADF if not initialized 800 S ERIES ROGRAMMERS UIDE...

  • Page 236: Rfcrreset()

    RF C ONTACTLESS EADER ODULE RFCRReset() RFCRReset() Configures the RESET line of the RFCR module. Prototype int RFCRReset(int onOffPulse); Parameters 0 = OFF onOffPulse 1 = ON 2 = PULSE (OFF then ON) Return Values Success, for OFF > 0 Success, for ON or PULSE.

  • Page 237: Rfcrsetantenna()

    RF C ONTACTLESS EADER ODULE RFCRSetAntenna() RFCRSetAntenna() Configures the Antenna control of the RFCR module. Prototype int RFCRSetAntenna(short onOff); Parameters 0 = Disable the RF Antenna onOff 1 = Enable the RF Antenna Return Values Success, for OFF < 0 Error -EBADF if not initialized >...

  • Page 238: Rfcrsetindicator()

    RF C ONTACTLESS EADER ODULE RFCRSetIndicator() RFCRSetIndicator() Configures the optional indicator controls of the RFCR module. The controllable optional LED is located on the right side of the reader face. The LED on the top left side of the reader face is not controllable. NOTE The current RFCR hardware does not support the optional buzzer control.

  • Page 239: Rfcrgetcardpayload()

    RF C ONTACTLESS EADER ODULE RFCRGetCardPayload() RFCRGetCardPayload() Prototype int RFCRGetCardPayload(char* buff, int maxlen); Parameters Pointer to store the Card Payload Packet buff Maximum size of buff maxlen Return Values > 0 Success, with the length of the Card Payload Packet data read. <...

  • Page 240: Rfcrparsecardpayload()

    RF C ONTACTLESS EADER ODULE RFCRParseCardPayload() RFCRParseCardPayload() Parses the Card Payload Data to the CardPayload structure. Prototype int RFCRParseCardPayload(CardPayload* payLoad, char* buff, int len); Parameters payload Pointer to CardPayload structure to store the data buff Pointer to Card Payload Packet data Size of the Card Payload Packet data in buff Return Values Success...

  • Page 241: Rfcrupdatefw()

    RF C ONTACTLESS EADER ODULE RFCRUpdateFW() RFCRUpdateFW() Upgrades the RFCR Module firmware. Prototype int RFCRUpdateFW(char* fileName, int removeFile, FWUpdateCallback *displayProgress); Parameters Pointer to name of the update hex file. The filename shall not fileName have any path prefix, and the file is assumed to be in the “/lib/ modules”...

  • Page 242: Rfcrpurge()

    RF C ONTACTLESS EADER ODULE RFCRPurge() RFCRPurge() Purges any pending input from the reader. Parameters void RFCRPurge(void); 800 S ERIES ROGRAMMERS UIDE...

  • Page 243: Rfcrinputpending()

    RF C ONTACTLESS EADER ODULE RFCRInputPending() RFCRInputPending() Returns the number of bytes available for reading. Prototype int RFCRInputPending(void); Return Values No data available > 0 Number of bytes available for reading < 0 Error 800 S ERIES ROGRAMMERS UIDE...

  • Page 244: Rfcrrawwrite()

    RF C ONTACTLESS EADER ODULE RFCRRawWrite() RFCRRawWrite() Sends raw data to the RFCR module. Prototype int RFCRRawWrite(unsigned char *buff, int len); Parameters Pointer containing the data to send to the RFCR module buff Number of bytes to send Return Values >...

  • Page 245: Rfcrrawread()

    RF C ONTACTLESS EADER ODULE RFCRRawRead() RFCRRawRead() Reads raw data from the RFCR module. Prototype int RFCRRawRead(unsigned char *buff, int maxlen, int msecs); Parameters Pointer to store the data read from the RFCR module buff Maximum size of the buffer maxlen Maximum wait time for data to arrive msecs...

  • Page 246: Rfcraddcrc()

    RF C ONTACTLESS EADER ODULE RFCRAddCRC() RFCRAddCRC() Calculates the CRC of the data contained in buff and insert it at the offset position of the buffer. Prototype void RFCRAddCRC(char* buff, int offset); Parameters Buffer containing the Command Frame to calculate the CRC. buff The position in the buffer to insert the CRC (and the size of the data to size...

  • Page 247: Rfcrcheckcrc()

    RF C ONTACTLESS EADER ODULE RFCRCheckCRC() RFCRCheckCRC() Prototype int RFCRCheckCRC (char* buff, short len, unsigned short* calcCRC); Parameters Buffer containing the data and CRC, with the CRC being the last 2 buff bytes of the buffer data. Length of the data including the CRC Pointer to store the calculated CRC calcCRC Return Values...

  • Page 248: Rfcrreceiveackframe()

    RF C ONTACTLESS EADER ODULE RFCRReceiveACKFrame() RFCRReceiveACKFrame() Receives an ACK frame from the RFCR module. The contents of the ACK frame specify whether the reader accepted the command. Depending upon the command, the ACK frame may provide additional information. Prototype int RFCRReceiveACKFrame (char* buff);...

  • Page 249: Rfcrreceivedataframe()

    RF C ONTACTLESS EADER ODULE RFCRReceiveDataFrame() RFCRReceiveDataFrame() Receives a data frame from the RFCR device. The Size of the data frame may vary. Prototype int RFCRReceiveDataFrame (char* buff, int maxlen); Parameters Pointer to store the ACK frame. The number of bytes returned may buff vary, but the buff should be able to accept the maximum possible size of the data frame.

  • Page 250: Rfcr Return Values

    RF C ONTACTLESS EADER ODULE RFCR Return Values RFCR Return Along with the generic error returns in errno.h, the RFCR specific error returns Values are as follows (most are from the RFCRUpdateFW() routine): Table 21 RFCR Return Values Error Value No File -401 Bad File...

  • Page 251: Input Events

    HAPTER Input Events The M 800 series terminal supports input events as captured through the Linux kernel Input Event module. Currently, the Input Events module supports the following event devices: • Touch panel – this enables an event interface that an application can use to capture events from the touch panel.

  • Page 252: Inputopen

    NPUT VENTS inputOpen inputOpen Prototype int inputOpen(int vfi_device) Parameters The device desired to open as defined in vfiInputAPI.h header file vfi_device as follows: • VFI_TOUCHPAD • VFI_USB_KBD • VFI_USB_SCANNER • VFI_USB_MOUSE Return Values This function will return a value greater than 0 upon successful execution, corresponding to the handle of the opened device, otherwise, it will return a negative value.

  • Page 253: Inputread()

    NPUT VENTS inputRead() inputRead() Prototype int inputRead(int inHdl) Parameters The device handle obtained from opening the device with inHdl inputOpen(). Return Values The function will return a value of int size from the device. Currently, touchpad and mouse events are not captured. Only keyboard and scanner data can be read. The function will return the ASCII value or the raw scancode of the key pressed or data scanned.

  • Page 254: Inputclose()

    NPUT VENTS inputClose() inputClose() Prototype int inputClose(int inHdl) Parameters The device handle obtained from opening the device with inHdl inputOpen(). Return Values The function will return a 0 upon success or a negative value if an error occurred while trying to close the device. When the device is closed, any illuminated LEDs are turned off.

  • Page 255: Visual Payments Library Functions

    HAPTER Visual Payments The SMF group shall be responsible for the code needed to connect to the Visual Payments (VP) server with no applications loaded. Thus, the output will be a VP shared library and the code that initiates it in System Mode. The VP shared library shall also be available for the application.

  • Page 256: Vpinit()

    ISUAL 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: •...

  • Page 257: Vpparsefields()

    ISUAL AYMENTS vpParseFields() vpParseFields() Parses the input buffer into the field arrays. The STX should not be in the input buffer. Prototype int vpParseFields(char *pchInBuf, vp_field_t *pszField, char *pszSep); typedef struct { key[]; value[]; } vp_field_t; Parameters Input Data Stream to parse pchInBuf Pointer to array of vp_field_t to store parsed strings pszField...

  • Page 258: Vpsendpacket()

    ISUAL AYMENTS vpSendPacket() vpSendPacket() Sends the packet to VP server after adding the wrappers. This is used for both Up and Down Channel messages. Prototype int vpSendPacket(int iFd, int iOptions, unsigned short ushMsgNum, char *pchOutBuf, unsigned short ushLength); Parameters Socket fd Bit defined options: iOptions 0x0002 Wait for ACK...

  • Page 259: Vpexit()

    ISUAL AYMENTS vpExit() vpExit() Closes the VP connections, frees the memory, and then exits the application. Prototype int vpExit(int iFd); 800 S ERIES ROGRAMMERS UIDE...

  • Page 260: Vpversion()

    ISUAL AYMENTS vpVersion() vpVersion() Returns the VP library version string in the form “xx.xx.xx”. Prototype void vpVersion(char *pchVersion); 800 S ERIES ROGRAMMERS UIDE...

  • Page 261: Visual Payments Callback Functions

    ISUAL AYMENTS Visual Payments Callback Functions Visual Payments • fnDownReq() Callback • fnDownFileStatus() Functions • fnUpData() • fnUpDisconnect() • fnTimedOut() 800 S ERIES ROGRAMMERS UIDE...

  • Page 262: Fndownreq()

    ISUAL AYMENTS fnDownReq() fnDownReq() Called after a REQ packet is received on the Down Channel. The application can: • allow or disallow this command to proceed • perform the request and detail the result. If this callback function is not provided, all REQ commands will be allowed to run. VP library will send the ACK prior to issuing this callback.

  • Page 263: Fndownfilestatus()

    ISUAL AYMENTS fnDownFileStatus() fnDownFileStatus() Called after a file that is successfully received from the XFTPGET command on the Down Channel is to be acted on. Prototype void fnDownFileStatus(int iStatus, int iFieldCount, vp_field_t *pszFields); Parameters Status of FTP operation: iStatus < 0 Error = 0 Done >...

  • Page 264: Fnupdata()

    ISUAL AYMENTS fnUpData() fnUpData() Called when response data is received on the Up Channel. VP library will send the ACK prior to issuing this callback. Prototype int fnUpData(unsigned short ushDataSize, unsigned short ushMsgNum, char *pchData); Parameters Contains the size of data in pchData. ushDataSize Contains the Message Number.

  • Page 265: Fnupdisconnect()

    ISUAL AYMENTS fnUpDisconnect() fnUpDisconnect() Called when the Up Channel is disconnected. Application should call vpExit() to clean up. Prototype void fnUpDisconnect(void); 800 S ERIES ROGRAMMERS UIDE...

  • Page 266: Fntimedout()

    ISUAL AYMENTS fnTimedOut() fnTimedOut() Called when ACKs are not received within the timeout period for the Down Channel Response message. NOTE For the Up Channel, the application is responsible for the protocol timeouts. Prototype void fnTimedOut(void); 800 S ERIES ROGRAMMERS UIDE...

  • Page 267: Network/Ethernet Library Functions Required By Visual Payments

    ISUAL AYMENTS Network/Ethernet Library Functions Required by Visual Payments Network/ • ftpPut() Ethernet Library • ftpGet() Functions • netLinkStatus() Required by Visual Payments • netDown() • netUp() • netPing() 800 S ERIES ROGRAMMERS UIDE...

  • Page 268: Ftpput()

    ISUAL AYMENTS ftpPut() ftpPut() Gets a file from the VP Server. FTPHost in form of IP address “xxx.xxx.xxx.xxx” or fully qualified domain name “ftp.site.com”. Translation of directory path ‘/’ to ‘\’ to be done by the VP server. VP server must support the following FTP commands: •...

  • Page 269: Ftpget()

    ISUAL AYMENTS ftpGet() ftpGet() Sends a file to the VP Server. Prototype int ftpGet(FTP_parm_t *pstFTP); 800 S ERIES ROGRAMMERS UIDE...

  • Page 270: Netlinkstatus()

    ISUAL AYMENTS netLinkStatus() netLinkStatus() Returns the link status of the eth0 network interface. Prototype int netLinkStatus(); 800 S ERIES ROGRAMMERS UIDE...

  • Page 271: Netdown()

    ISUAL AYMENTS netDown() netDown() Deactivates the network interface. Prototype int netDown(); 800 S ERIES ROGRAMMERS UIDE...

  • Page 272: Netup()

    ISUAL AYMENTS netUp() netUp() Activates the network interface. Prototype int netUp(); 800 S ERIES ROGRAMMERS UIDE...

  • Page 273: Netping()

    ISUAL AYMENTS netPing() netPing() Pings the remote host. Prototype int netPing(char *host); 800 S ERIES ROGRAMMERS UIDE...

  • Page 274: Xftp Commands

    ISUAL AYMENTS XFTP Commands XFTP The succeeding sections lists all XFTP commands. Commands XFTPGET • Required fields are: FTPHOST, FTPPORT, FTPUSER, FTPPWD, FILENAME, FILETYPE. • System Mode will act only on FILETYPE OS and APP. • The FILENAME is in reference to the VP server, and may contain a directory path.

  • Page 275: Ipp Ms And Dukpt Communications Packets

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

  • Page 276: Si>15Spain Set Ipp6 Key Management Mode

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packets <SI>15SPAIN<SO> Set IPP6 Key Management Mode Spain mode is not supported and switching to Spain mode erases keys. This is done because some programs depend on this feature to erase keys. <SI>17xyz<SO> Set IPP7 Key Management Mode SM mode is not supported but switching to SM mode erases keys.
  • Page 277 IPP MS DUKPT C OMMUNICATIONS ACKETS Packets Table 23 Common Packets (Continued) Packet 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...

  • Page 278: Packet Acknowledgement And Timing

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packets Packet The IPP only responds to commands that have the proper packet format. The Acknowledgement packet can be in the form of <STX>msg<ETX>[LRC]or <SI>msg<SO>[LRC] and Timing according to the specific command. The IPP returns <ACK> within 20ms to the terminal when it receives a properly framed packet with a valid LRC.

  • Page 279: Dukpt Method

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packets The following illustrates an MS encryption session. Master Device Forwards the encrypted working key, account number, and PIN to the IPP. Decrypt the working key using the master key. Encrypts the PIN block with the decrypted working key.

  • Page 280: Constraints

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packets The following illustrates the DUKPT method of encryption. Master Device Forwards the account number and PIN to the IPP. Creates the PIN block. Encrypts PIN block with the generated PEK. Sends the PIN block and current KSN (key serial number) to the master device.

  • Page 281: Dukpt Initial Pin Encryption Key Insertion

    IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 The terminal or master device uses Packet 02: Transfer Master Key to transfer the master keys into the IPP for MS. DUKPT Initial PIN Encryption Key Insertion The terminal or master device uses DUKPT Packet 90: Load Initial Key Request to load the initial PIN encryption key into the IPP for DUKPT.
  • Page 282 IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 Table 26 Key Management Switching Rules Rules To 1DES (VISA) To Mixed Mode To 3DES To 1DES (SPAIN) To SM 2/3K From 1DES (VISA) From 1DES (SPAIN) 2/3K From Mixed mode From 3DES From SM Key Mode 1DES and 3DES Key Usage Rules...

  • Page 283: Using A Session Key

    IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 Using a Session Key Loading the Session Key 3DES session keys are only loaded in GISKE cipher text under the protection of the indexed master key, as long as that key has its attribute set to ‘KEK’ (key usage attributes = “K0”).

  • Page 284: Rules For Loading The Master Key

    IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 Rules for Loading This section provides details on IPP7 key attributes, key version, and key length. the Master Key On erasure, the master key usage attribute is set to 0, the version is set to 0, and (MS only) the length is set to 1DES.

  • Page 285: Klk

    IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 • when the version is less than the current key version, an error returns and the IPP rejects the new key NOTE The key version comparison is only compared to the key it is replacing, not to any other keys.

  • Page 286: 3Des

    IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 • KLK is present and cipher text is being loaded that is encrypted with the previous KLK, has the correct key version and the key attribute is not equal to “KEK”, the IPP returns an error. •...

  • Page 287: 1Des

    Addressing length DES keys. Omni 33XX IPP7 can hold at most three triple-length keys. Clear Text GISKE The following are VeriFone-proprietary rules for GISKE key block loading, and are Key Block Loading not part of the ANSI GISKE specification. Rule •...
  • Page 288 IPP MS DUKPT C OMMUNICATIONS ACKETS IPP7 Padded clear text 8 HB + 48 HB + 48 KB + 16 MAC GISKE key block (MAC is all zeros): 800 S ERIES ROGRAMMERS UIDE...

  • Page 289: Common Packets

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Common This section presents the packets common to all protocols. Packets Packet 01: Packet 01 has the IPP run a specified self-diagnostic test. Information on the test Interactive in progress is provided using response packets 9 and 14, depending on the Diagnostic Routine selected test.

  • Page 290: Packet 06: Request Pin Pad Serial Number

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 31 Packet 05 Communication Protocol Transmit Master Device Direction <SI>05[vvv][dddddd][p][bb][nnnn] <SO>{LRC} ACK if LRC • NAK if LRC incorrect • EOT after 3 NAKs • <SI>05[vvv][dddddd][p][bb][nnnn] <SO>{LRC} ACK if LRC • NAK if LRC incorrect;...

  • Page 291: Packets 09 And 14: Response Packet To Packet 01

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets • Packet 06 Length: MAX: 21 characters • MIN: 21 characters Response Sample <SI>06246880401A001234SO>{LRC} Packet Table 34 Packet 06 Communication Protocol Transmit Master Device Direction <SI>06<SO>{LRC} ACK if LRC • NAK if LRC incorrect •...
  • Page 292 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 35 Packets 09 and 14 Communication Protocol Transmit Master Device Direction 00 Current Baud Rate <SI>0100<SO>{LRC} ACK/NAK/EOT <SI>14yyyyy<SO>{LRC} where, yyyyy indicates the current baud rate: 1200 • 2400 • 4800 • 9600, or •...
  • Page 293 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 35 Packets 09 and 14 Communication Protocol (Continued) Transmit Master Device Direction 02 RAM Test/Continuous IPP7 <SI>0102<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. 03 PROM Checksum Test IPP7 <SI>0103<SO>{LRC}...
  • Page 294 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 35 Packets 09 and 14 Communication Protocol (Continued) Transmit Master Device Direction 06 Serial Number Check IPP6 and earlier <SI>0106<SO>{LRC} ACK/NAK/EOT <SI>14xxxxxxxxxxxxxxxx<SO>{LRC} where, xxxxxxxxxxxxxxxx indicates the serial number of the IPP. Length is 16 digits, for example, 1234567890123456.
  • Page 295 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 35 Packets 09 and 14 Communication Protocol (Continued) Transmit Master Device Direction 08 IPP PROM Version Number IPP7 <SI>0108<SO>{LRC} ACK/NAK/EOT <SI>14IPPx vvvvxxx MM/YY<SO>{LRC} where: vvvv: 4-digit software ID number. For • IPP5, 0PGP.

  • Page 296: Packet 11: Pin Pad Connection Test

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 35 Packets 09 and 14 Communication Protocol (Continued) Transmit Master Device Direction 10 Clear IPP IPP7 <SI>0110<SO>{LRC} ACK/NAK/EOT <SI>14CLR COMPLETE<SO>{LRC} ACK/NAK/EOT EOT to terminate process. Packet 11: PIN Pad The master device uses this packet to check the connection with the IPP. If the Connection Test connection is good, the master device receives an ‘ACK’...

  • Page 297: Packet 13: Select Baud Rate

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Packet 13: Select Omni 33XX supports this packet but it has no effect. Verix-based Omni series Baud Rate terminals do not use an RS-232 interface so do not need this setting. However, it is supported for compatibility with other IPPs.

  • Page 298: Packet 15: Set Ipp Key Management Mode

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 39 Packet 13 Communication Protocol Transmit Master Device Direction <SI>13x<SO>{LRC} ACK if LRC okay; NAK if LRC incorrect. <SI>14yyyyy<SO>{LRC} where, x = baud rate code yyyyy = string for selected baud rate 1200 (default) •...
  • Page 299 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 40 IPP Request Packet 15 Format Data Element Field Length Comments [Key Code] Packet 4 or 5 The key management operation parameters mode for the IPP “SPAIN” – Spain SEMP/4B • mode “VISA”...

  • Page 300: Packet 17: Set Ipp7 Key Management Mode

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 42 Packet 15 Format Data Element Characteristic Comments <SI> Shift In, Value: 0Fh Packet Type Value: 15 Packet Data Value: 'IPP2', fixed as password <SO> Shift Out, Value: 0Eh Error Check {LRC} •...
  • Page 301 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 44 Packet 17 Format Data Elements Characteristics Comments <SI> Shift In, value: 0Fh Packet Type Value: 17 Key Management The two ASCII hex digits are Mode concatenated big-endian, to produce a single control byte.
  • Page 302 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 44 Packet 17 Format (Continued) Data Elements Characteristics Comments Bit 7 Description MAC empty working key support off (default) MAC empty working key support on DUKPT Engine 1/2 The one ASCII-Hex digit is used Mode Flag [DEMF] produce half of a control byte.
  • Page 303 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Packet 17 Set IPP Key Management Mode Transmit Master Device Direction <SI>17[KMM][PINER]<SO>{LRC} ACK if LRC • NAK if LRC incorrect • EOT after 3 NAKs • <SI>17[KMM][PINER]<SO>{LR ACK if LRC and key management echo •...
  • Page 304 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Packet 17 Examples: The following examples only illustrate the command packet sent from the master device. Some valid IPP KMM are shown below. 1DES MS mode, zero key support off, zero GISKE session key support off, and 1DES DUKPT mode: <SI>17000<SO>{LRC} Mixed MS mode, zero key support off, zero GISKE session key support off,...

  • Page 305: Packet 18: Check Ipp7 Key Management Mode

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets The combinations of KMM setting are limited, which means that the mixtures of MS mode, zero key support, zero GISKE session key support, DUKPT mode, and SM mode are not applicable in some cases. If there is a conflict in the KMM setting, the following priority rules apply: Priority KMM setting...
  • Page 306 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 45 Packet 18 Format Data Elements Characteristics Comments Key Management Mode The two digits are concatenated big- endian, to produce a single control [KMM] byte. The key management mode register (8 bits) in IPP7 is as follows: Description Old single DE Mixed mode (1DES...
  • Page 307 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 45 Packet 18 Format Data Elements Characteristics Comments DUKPT Engine 1/2 The one ASCII-Hex digit is used Mode Flag [DEMF] produce half of a control byte. This field was Note: added for IPP8 Bit 0 ( DUKPT Engine "1") emulation.
  • Page 308 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 46 Packet 18 Check IPP7 Key Management Mode Transmit Master Device Direction ACK/NAK • EOT to terminate process. Packet 18 Examples: The following examples show the response packet, <SI>18[KMM][PINER]<SO>{LRC} from the IPP. 1DES MS mode, zero key support off, zero GISKE session key support off, and 1DES DUKPT mode: <SI>18000<SO>{LRC}...

  • Page 309: Packet Z60: Accept And Encrypt Pin (Visa Mode)

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets <SI>18180<SO>{LRC} Mixed MS mode, zero key support off, zero GISKE session key support on, and 3DES DUKPT mode: <SI>18390<SO>{LRC} 3DES MS mode, zero key support off, zero GISKE session key support on, and 3DES DUKPT mode: <SI>182A0<SO>{LRC} 1DES MS mode, zero key support on, zero GISKE session key support off,...
  • Page 310 IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Packet Z60 Format <STX>Z60.[aaa…aaa]<FS>[DUKPT ENCRYPTION]<ETX>{LRC} DUKPT Table 47 Packet Z60 Format Data Elements Characteristics Comments <STX> Start of Text, Value: 02h Packet Type Value: Z60 Packet Delimiter Value: (.), 2Eh [aaa...aa] 8-19N Card account number <FS>...

  • Page 311: Errors Returned By Write()

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Errors returned by write() Some packet format errors are caught when the packet is written to the IPP. In this case, write() returns –1 and errno set. The packet is not ACKed or NAKed, and no response packet returns.

  • Page 312: Errors Returned By Write()

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Table 48 Packet Z63 Format (Continued) Data Elements Characteristics Comments <FS> Field Separator; Value: 1Ch [www...www] 16AH or 120AH Encrypted working key or (encrypted session key) DUKPT. DUKPT ENCRYPTION means DUKPT is ENCRYPTION selected.

  • Page 313: Packet M04: Read Permanent Unit Serial Number

    IPP MS DUKPT C OMMUNICATIONS ACKETS Common Packets Packet M04: Read This command is used to check the permanent unit serial number. Permanent Unit Serial Number NOTE This packet is added for IPP8 emulation. Request Packet <SI>M04<SO>{LRC} Format Table 49 Packet M04 Format Data Element Characteristic...

  • Page 314: Ms-Specific Packets

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 51 Packet M04 Communication Protocol (Continued) Transmit Master Device Direction ACK if LRC okay • NAK if LRC • incorrect (EOT after 3 NAKs). EOT terminates session. MS-Specific The following packets are specific to MS 1DES and 3DES operations. The default Packets mode for the IPP at power up is MS 1DES.

  • Page 315: Key-Only Format

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Key-only Format The key attribute information is not available when the key is loaded using the key-only format (as compared to the GISKE communication protocol). The IPP sets the default attributes to the key, as shown in Table Table 53 Default Key Attributes...

  • Page 316: Giske Key Block Format

    IPP MS DUKPT C OMMUNICATIONS 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:...

  • Page 317: Packet 04: Check Master Key

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 56 Packet 02 GISKE Key Block Format Communication Protocol Transmit Master Device Direction <SI>02[r][hhh.hhh]<SO>{LRC} ACK if LRC • NAK if LRC incorrect • EOT after 3 NAKs • <SI>02[n]<SO>{LRC} ACK if LRC, no errors, and key •...

  • Page 318: Packet 04 Communication Protocol

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Packet 04 Communication Protocol Packet 04 has two types of communication format: key-only and GISKE key block format. The communication format depends on the IPP key management setting and the length of the key at address [a]. The use of the communication protocol is as follows: IPP Key Management Setting Key Length at...

  • Page 319: Packet 04 Giske Key Block Format

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 59 Response Packet 04 Key-only Format Communication Protocol Transmit Master Device Direction <SI>040<SO>{LRC} ACK if LRC okay • NAK if LRC incorrect • EOT after 3 NAKs • PIN pad checks requested address [a]. •...
  • Page 320 IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 60 Response Packet 04 GISKE Key Block Format (Continued) Data Characteristic Comments Element Key Usage Only when master key is present at address [a]: Attribute (KUA) AN: ANY: The key is available in the IPP, but •...
  • Page 321 IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 60 Response Packet 04 GISKE Key Block Format (Continued) Data Characteristic Comments Element Mode of Use (optional) Only if the master key present at Attribute address [a]. The value is stored in the key (MOUA) attributes register.

  • Page 322: Ms Packet 08: Select A Master Key

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 61 Response Packet 04 GISKE Block Format Communication Protocol Transmit Master Device Direction <SI>04[a]<SO>{LRC} ACK if LRC okay • NAK if LRC incorrect • EOT after 3 NAKs • PIN pad checks requested address [a]. •...

  • Page 323: Ms Packet 71: Transfer Pin Block

    IPP MS DUKPT C OMMUNICATIONS ACKETS MS-Specific Packets Table 63 MS Packet 08 Communication Protocol Transmit Master Device Direction <SI>08[a]<SO>{LRC} ACK if LRC • NAK if LRC incorrect • EOT after 3 NAKs • PIN pad makes master key [a] active. •...

  • Page 324: Packet 07: Dummy Packet

    IPP MS DUKPT C OMMUNICATIONS ACKETS DUKPT-Specific Packets MS Packet 71 <STX>71.000010123456789123456<ETX>{LRC} Example: This packet 71 is the response packet to PIN request Z60 and Z63 when no errors are detected in the Z60 or Z63 packet. If errors are detected in the Z60 or Z63 packet, the response packet is in the following format: Table 65 MS Response Packet 71 Format: Errors in Z60 or Z63 Packets...
  • Page 325 IPP MS DUKPT C OMMUNICATIONS ACKETS DUKPT-Specific Packets Table 66 DUKPT Packet 19 Format Data Element Characteristic Comments <SI> Shift In, Value: 0Fh Packet Type Value: 19 DUKPT Engine: "0", "1",or "2" <SO> Shift Out, Value: 0Eh {LRC} Error Check DUKPT Packet 19 Length: Maximum: 6 characters Minimum: 6 characters...

  • Page 326: Packet 25: Check The Dukpt Engine

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Packet 25: Check The application sends this packet to the IPP to check the current active DUKPT the DUKPT Engine engines ("0", "1", or "2"). NOTE This packet is added for IPP8 emulation. Request Packet <SI>25<SO>{LRC} Format...

  • Page 327: Dukpt Packet 73: Transfer Pin Block (For Packets Z60 Or Z63)

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Table 70 Packet 25 Communication Protocol Transmit Master Device Direction <SI>25<SO>{LRC} ACK if LRC okay. • NAK if LRC incorrect (EOT after 3 • NAKs). Response current active DUKPT engine.

  • Page 328: Dukpt Packet 90: Load Initial Key Request

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Table 72 MS Response Packet 73 Format: Errors in Z60 or Z63 Packet Data Element Characteristic Comments <STX> Start of text, value: 02h Packet Type Value: 73 Error Code 1 = no key •...

  • Page 329: Dukpt Packet 91: Load Initial Key Response

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Table 74 DUKPT Packet 90 Communication Protocol Transmit Master Device Direction 90 Packet ACK if LRC • NAK if LRC incorrect • EOT after 3 NAKs • Initialization of 21 Future Keys •...

  • Page 330: Dukpt Packet 76: Pin Entry Test Request

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Table 76 DUKPT Packet 91 Communication Protocol Transmit Master Device Direction Packet 91 ACK if LRC • NAK if LRC incorrect • EOT after 3 NAKs • DUKPT Packet 76: Directly presets the PIN code '1234' to do encryption and send response PIN Entry Test packet 71.

  • Page 331: Dukpt Packet 71: Transfer Pin Block - (For Packet 76)

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine DUKPT Packet 71: Response packet to packet 76, request for PIN. The IPP encrypts the formatted Transfer PIN Block - clear-text PIN block and sends the cipher-text PIN block to the master device. (for Packet 76) (refer to the VISA PIN Processing and Data Authentication specification, International version 1.0)

  • Page 332: Dukpt Packets 92 And 93

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine DUKPT Packet 71 <STX>711<ETX>{LRC} Example: DUKPT Packets 92 The DUKPT reinitialization request and reinitialization response packets are not and 93 supported in Omni 33XX. DUKPT Z69 Packet: On receipt of the Z69 packet, Omni 33XX reads the user’s PIN from the keyboard, Accept and Encrypt echoing to the display an asterisk for each digit accepted.

  • Page 333: Errors Returned By Write()

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Errors returned by write() Some packet format errors are caught when the packet is written to the IPP. In this case, write() returns –1 and errno set. The packet is not ACKed or NAKed, and no response packet returns.
  • Page 334 IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine DUKPT Packet 75 VISA: Example: PC ---> PINPAD : <STX>7801234567890<FS>C19.99<ETX>{LRC} PC <--- PINPAD : <ACK> PC <--- PINPAD : <STX>75FCD3CA45D04396624CF6892B04A000002468000048D5D7AF0333800FD<ETX>{LRC} PC ---> PINPAD : <ACK> ANSI: PC ---> PINPAD : <STX>7801234567890<US>C19.99<ETX>{LRC} PC <--- PINPAD : <ACK>...

  • Page 335: Packet 78: Dukpt Accept And Encrypt Pin/Data Authentication Test Request

    IPP MS DUKPT C OMMUNICATIONS ACKETS Packet 25: Check the DUKPT Engine Packet 78: DUKPT Packet 78 requests PIN encryption and MAC processing using a fixed PIN of Accept and Encrypt '1234'. The response packet is packet 75. PIN/Data Authentication Test Request Packet 78 is similar to packet Z69, but the PIN code is preset to “1234.”...

  • Page 336: Mac-Specific Packets

    IPP MS DUKPT C OMMUNICATIONS ACKETS MAC-Specific Packets Table 86 DUKPT Packet 78 Communication Protocol Transmit Master Device Direction 78 Packet ACK if LRC • NAK if LRC incorrect • Packet 75 with PIN = 1234 ACK if LRC • NAK if LRC incorrect •...
  • Page 337 IPP MS DUKPT C OMMUNICATIONS ACKETS MAC-Specific Packets Table 87 MAC Packet Z66 Format (Continued) Data Element Characteristic Comments Second Key Optional; Second master key pointer; Range: 0–9 <FS> Field separator, value: 1Ch Message for 8*XAN0 ASCII message or ASCII-coded binary data: X= 0–28 for ASCII data X= 0,2,4,6,...,27,28 for binary data <ETX>...

  • Page 338: Rules Of Request Mac

    IPP MS DUKPT C OMMUNICATIONS ACKETS MAC-Specific Packets If the working key is loaded in 1DES key-only format, either ANSI (standard) or MAC is used (depending on the status of the flag in the packet Z66). If the working key is loaded in the GISKE format, the IPP uses the MAC algorithm specified in the Key Usage Attributes of the GISKE key block.

  • Page 339: Packet 72: Cancel Mac Session

    IPP MS DUKPT C OMMUNICATIONS ACKETS MAC-Specific Packets • Sends the MAC value to the master device. Table 89 MAC Packet Z67 Format Data Element Characteristic Comments <STX> Start of text, value: 02h Packet Type Value: Z67 Process Code Range: 0–9: 0 = no error and MAC follows •...

  • Page 340: Mac Module Design

    IPP MS DUKPT C OMMUNICATIONS ACKETS MAC-Specific Packets Table 91 Packet 72 Communication Protocol Transmit Master Device Direction <STX>72<ETX>{LRC} ACK if LRC • NAK if LRC incorrect • MAC Module Design ANSI (Standard) MAC Algorithms The algorithm to calculate the MAC is fully compatible with the ANSI X9.19 1986, Financial Institution Retail Message Authentication specification.
  • Page 341 NDEX Numerics real time clock serial port 1DES master key Sound touch panel audio directory structure beeper units file organization disabling speakers user space and security vlume, bass and treble control user space base structure display C compiler and development tools dspSetBrightness() C compiler &...
  • Page 342 NDEX file format details IPP7 DUKPT modes file systems firmware JFFS2 getenv() GISKE key attribute key attributes, IPP KLK key loads KLK (GISKE) GNU C compiler GNU ZIP LEDs ledOff IBM ECR tailgate & feature C ledOn ecrRead ecrReadReject ecrStatus MAC value IBM ECR tailgate &...
  • Page 343 NDEX root file system Signature Capture API BusyBox svcDsp2Hex() uClibc svcInfoRFS() System Mode security services APIs AES() touch panel authFile() cryptoRead() cryptoWrite() Verishield Security Scripts (VSS) DES() VSS APIs generateRandom() iPS_CancelPIN() IRSA Computation iPS_CheckMasterKey() isAttacked() iPS_DeleteKeys() loadOSFiles() iPS_ExecuteScript() secVersion() iPS_GetPINResponse() SHA1() iPS_GetScriptStatus() serial communication control structure...
  • Page 344 VeriFone, Inc. 2099 Gateway Place, Suite 600 San Jose, CA, 95110 USA Tel: (800) VeriFone (837-4366) www.verifone.com 800 Series Programmers Guide Part Number 23753, Revision A...

Table of Contents