# new\_XPI\_Generic\_Keyloader\_UserGuide\_Vers1.0e ## Introduction The purpose of this document is to describe the implementation of the Key Loader application. The Key Loader application is a generic application which supports all the commands supported by previous key loaders for Moneris, Chase, GPC/Scotia bank, ACCEO and FDMS. The information in this document covers instructions specific to the Engage Terminals. This document is intended for users who want to perform key loading using the XPI Generic Key Loader application. ### Definition of Terms This table lists the terms and abbreviations that are used throughout this document: | Term | Description | | -------- | -------------------------------------------------------------------------------------------------- | | CAM | Commerce Acceptance Module | | COM | Communications Port | | MAC | Message Authentication Code — A short piece of information that is used to authenticate a message. | | SAC | Command Module (Surrogate Application) | | Terminal | Terminal is a term used interchangeably with host device and master device in this document. | ### Related Documents * EPP Interface Specification * XPI Generic Keyloader Release Notes * SC5000VeriShieldSecurityScripts.pdf * DOC00501\_Operating\_System\_Programmers\_Manual.pdf * Verix eVo Volume I-III ## Overview ### XPI Generic Key Loader The XPI Generic Key Loader (Key Loader) is used to load different Key Loader configurations (keys) used for encrypting Debit PIN entry data or other sensitive card data. The application supports all commands of the previous Key Loader applications and merges them into one application. Supported Key Loader configurations include: * Acceo * Chase * FDMS * GPC * Loblaws * Moneris * Scotia Bank * TD Bank The Key Loader bundle has five packages: *Key\_Loader*, *secu*, *keymap*, *resources*, and *userbundles*. * *Key\_Loader* package contains the executable and the default connection profile *serial.xml*. * *secu* contains the SECu.VSO file. * *keymap* contains keymap.dat files, separated by folders. The application uses the keymap specified in appconfig.ini. * *resources* contains the HTML files. * *userbundles* contains the INI file. When connecting the terminal to the PC for key injection, the terminal makes use of the following connection profile: It is possible to adjust baud rate and serial port via the GUI. Upon selection of connection properties, the user can proceed to key injection. The key loader first reads configuration from *appconfig.ini*. This INI contains the application name and the set of commands the key loader accepts. Refer to [Configuration Variables](#_Configuration_Variables). After configuration, the terminal installs the VSS script and establishes connection to the PC. The terminal then waits for command requests. Refer to [Supported Commands](#_Supported_Commands). ### Steps in Key Loading {% stepper %} {% step %} ### Pre-installation * Define the type of Key Loader * Modify the Key Loader configuration files * Prepare the Key Loading Software * Sign the Key Loader bundle {% endstep %} {% step %} ### Configuring the Key Loader application This depends on the client’s requirement and requires modification of configuration files and bundle signing. {% endstep %} {% step %} ### Preparing the client’s tool Prepare the client’s tool that will communicate with the Key Loader application. {% endstep %} {% step %} ### Installation Install the Key Loader application to the terminal. {% endstep %} {% step %} ### Setting up to load the Key Loader application to the device Prepare the terminal for key injection. {% endstep %} {% step %} ### Sending Test keys Send test keys to the device using the client’s tool. {% endstep %} {% step %} ### Finishing tests Ensure that all test keys are sent and validated. {% endstep %} {% step %} ### Post-installation Complete post-installation tasks (installing CXPI application, configuring CXPI, installing key map bundle, etc.). {% endstep %} {% step %} ### Installing the CXPI application Install the CXPI application after key injection. {% endstep %} {% step %} ### Installing the key map bundle Install the key map bundle specific to the Key Loader used. {% endstep %} {% endstepper %} ## Key Loader Installation ### Pre-installation Topics covered: * Defining the type of Key Loader * Modifying the Key Loader configuration files * Preparing the Key Loading Software * Signing the Key Loader bundle #### Type of Key Loader The Key Loader supports multiple key loading configurations. Define the desired type in the pkg.config\appconfig.ini file. Refer to [Configuration Variables](#_Configuration_Variables) for more information. #### Modifying Key Loader Configuration Files Supported commands and configuration are available and can be modified in **pkg.config\appconfig.ini**. Refer to [Configuration Variables](#_Configuration_Variables) and [Supported Commands](#_Supported_Commands) for details. #### Preparing Key Loading Software Download and install the Key Loading Software you will use. For recommended settings, refer to [Configuring Communication Setting](#_Configuring_Communication_Setting) (in the Key Loading Software section). #### Signing Key Loader Bundle After modifying configuration files, sign the bundle. ### Installation Before you start, ensure to clear the terminal of old bundles to remove any previously installed Key Loader applications. Refer to the Release Notes for the minimum required OS / ADK bundle for the Key Loader application. > NOTE: For e280 device, ADK MAC version is required to install, in order to display the virtual keyboard. The following topics are covered in this section: * Installing the Key Loader application to the device * Configuring the communication setting of the Key Loading Software * Installing Keys * Completing the installation #### Installing Key Loader Application Follow these steps for direct installation. {% stepper %} {% step %} ### Establish connection Establish a connection between your workstation and the terminal. {% endstep %} {% step %} ### Download installer Download the Key Loader application to the terminal. The installer filename is *KeyLoader.tgz*. {% endstep %} {% step %} ### Launch The Key Loader application automatically launches after installation. On the application's screen, two options are displayed: * Start — initiates the key loading process. * Comms Settings — displays the communication settings (default COM1 / 9600). Adjust when necessary. {% endstep %} {% step %} ### Begin key loading To initiate key loading, select Start. {% endstep %} {% endstepper %} > NOTE: In some terminals, you have to press **1** for Start, **2** for Comms Settings. If the status message “READY” is displayed, the terminal is waiting for commands. #### Configuring Communication Setting Serial communication is the recommended medium. Recommended settings: * Baud rate: 9600 * Data: 8 bits * Parity: None * Stop bit: 1 Messages must follow standard protocol framing with and require messages to be ACK’d or NAK’d accordingly. #### Installing Keys Install keys using your Key Loading Software. Ensure the Key Loader application is in a ready state to accept key injection. #### Completing Installation On the terminal, press the Cancel/Annul or the red “X” key to terminate the Key Loader application. If the message “FINISHED” is displayed, the installation is done. ### Post Installation Topics covered: * Installing the CXPI application * Installing the Key Map #### Installing CXPI Application Before you start, set these variables in CAMCORE.INI: * MACMODE=1 * PINSEC=INTERAC For more information about MACMODE and PINSEC, refer to [Configuration Parameters](#_Configuration_Parameters). The CXPI application must be installed after keys are injected. To install CXPI, download the XPI bundle and the CFG bundle to the terminal. > NOTE: > > * Installing the CXPI application automatically removes the Key Loader application from the device (to avoid interference). > * The client may opt to remove the Key Loader application manually before installing CXPI. ![](/files/6c1dfb8386110ec474a43fab5226ec2ba5dadf12) #### Installing Key Map The key map specific to the Key Loader used must be installed after installing the CXPI application. The CXPI bundle removes files including keymap files and the VSO during installation. Installing the Key Map preserves the keymap and the VSO script used by the keyloader after installing CXPI. If the keymap is not installed, Interac Debit commands (S66, S67, etc.) will not work. Key map files are in a separate bundle released with the Key Loader application. ## Configuration Variables Example: ``` [config] app=chase appname=ChaseKeyloader keymapfolder=keymap_chase ``` * app — in the \[config] section, indicates the section prefix for commands. If set to *chase*, the terminal reads from \[chase.commands] and \[chase.config]. * appname — name of the key loader application. Used in RequestSN response. ## LIST OF COMMANDS (Short list of supported operations — see below for detailed command sections.) * LoadTMK - loads terminal master key * LoadMK - loads master key * LoadWK - loads working keys * RequestMAC - MAC request * ChangePW - change password * InteracRequest - interac request * InteracResponse - interac response * RequestSN - serial number request * LoadSDK - load sdk * LoadSecure - load secure * InjectBSN - inject bsn * GetBSN - get bsn * LoadBSN - load bsn * ChangeKTKPW - change KTK password * InjectKeys - inject keys * ReadCheckSum - read check sum * ReadSN - read serial number * LoadKeys - load keys Configuration examples and command mappings: **\[moneris.commands]** ``` 0x23=ReadSN 0x24=ChangeKTKPW 0x60=InjectKeys 0x61=ReadCheckSum S97=LoadKeys ``` **\[chase.commands]** ``` S66=RequestMAC S70=InteracRequest S71=InteracResponse S82=LoadMK S84=LoadWK S86=LoadTMK S95=RequestSN ``` **\[chase.config]** ``` LoadTMK_FS=false LoadTMK_UseDefPW=true LoadMK_FS=false InteracRequest_UseMAC=true InteracRequest_UseSN=true ``` Description of some config entries: | Parameter | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | | LoadTMK\_FS | Specifies if there is in the LoadTMK request. | | LoadTMK\_UseDefPW | Specifies if response for Interac Request should have serial number if default password is used for LoadTMK. | | LoadMK\_FS | Specifies if there is in the LoadMK request. | | InteracRequest\_UseMAC | Specifies if there is processing for MAC data. | | InteracRequest\_UseSN | Specifies if response for Interac Request should have serial number appended. | Other command groups and mappings are specified in corresponding INI sections (see original file for full lists for gpc, acceo, fdms, scotia, loblaws, tdcan, etc.). ### Configuration Parameters | Parameter | Description | Values | INI File Location | | -------------- | --------------------------------------------------------------------------------------------------: | ------------------------------------------------------------- | -------------------- | | KEYLOADER\_LOG | Enable/disable KeyLoader UI | 0 (Disabled), 1 (Enabled) Default: 0 | Config.usr1, \[reg] | | KLBAUD | Baud rate for keyloader comms | Default: 9600 | appconfig.ini/config | | KLCOM | Communication port | String: COM1, USBD Default: COM1 | appconfig.ini/config | | KLGUI | Enable/disable KeyLoader UI | 0 (Disabled), 1 (Enabled) Default: 1 | Config.usr1, \[reg] | | MACMODE | If MACing occurs on encrypted or unencrypted PAN when VSP is enabled. Affects S66 and S70 commands. | 0 - MACing on encrypted PAN (default), 1 - on unencrypted PAN | CAMCORE.INI | | PINSEC | PIN Security Type | INTERAC | CAMCORE.INI | ## Supported Commands This section describes commands supported by each Key Loader. (Each vendor section lists supported commands and references to detailed descriptions below.) * ACCEO — S51, S66, S70, S71, S79, S80, S81, S83, S84, S95, S98, S99 * Chase — S66, S70, S71, S79, S82, S84, S86, S95 * FDMS — S66, S70, S71, S79, S80, S83, S84, S86, S95 * GPC / Loblaws — S51, S66, S70, S71, S79, S80, S81, S83, S84, S95, S99 * Moneris — 0x23, 0x24, 0x60, 0x61, S97 * Scotia Bank — S79, S80, S83, S95, S99 * TD Bank — S66, S80, S81, S83, S84, S95 > NOTE: In UX devices, pin entry does not work using keyloader. Hence S70 is not supported and will result in an error response if sent. (For full command mapping and vendor-specific settings, refer to the INI sections in the original config.) ### Command Format (selected commands) Below are request/response formats and element descriptions for each command. Use exact framing: ... . #### S51 - Store Secure Command Request: ``` S51 ``` Response: ``` 00 ``` #### S66 - Create MAC Request Request: ``` S66 ``` Response: ``` ``` * response code: 00 = Success, 01 = Failure * response data: 8-character MAC block + 9-digit serial number #### S70 - Perform Interac Request Transaction Request format: ``` S70 ``` Elements: * Language Code (0 English, 1 French) * Must be 0 (sale) * 0.01–999999.99 * numeric, length >8 and <25 * formatted per host; may include \*D placeholder (for Chase replaced by account type) Response format: ``` ``` For Chase response: ``` ``` * response code: 00 success, 01 unsuccessful * accttype: 1 checking, 2 savings * response data includes 8-character MAC, 16-character PIN block, 9-char serial (padded) > NOTE: UX devices: S70 not supported. #### S71 - Perform Interac Response Analysis Request: ``` S71 ``` Response: ``` ``` * Response Code: 00 success, 01 unsuccessful * Supports single (16 bytes) and double (32 bytes) length keys for MSG, PIN, MAC keys. #### S79 - Change TMK Password Request: ``` S79 ``` Response: ``` ``` * Response codes: 00 success, 01 unsuccessful #### S80 - Inject TMKey Request: ``` S80 ``` Response: ``` ``` * Response codes include: 00 success, 01 unsuccessful, 10 incorrect TMK password, 99 security chip write failure #### S81 - Load SDK Request: ``` S81> ``` Response: ``` ``` #### S82 - Inject Master Key (Chase) Request: ``` S82 ``` Response: ``` ``` * response code: 00 success, 01 failure #### S83 - Inject Master Key (MKey) Request: ``` S83 ``` Response: ``` ``` * Response Code: 00 success, 01 unsuccessful * Index mapping: 0 = MSG Key, 1 = PIN Key, 2 = MAC Key #### S84 - Request Working Key Set Load (WKey) Request: ``` S84 ``` Response: ``` ``` * response code: 00 success, 01 failure #### S86 - Inject TMKey (Chase) / Load BSN (FDMS) * S86 has vendor-specific formats. For Chase: ``` S86 ``` * For FDMS (Load BSN): ``` S86 ``` Response codes differ by vendor (e.g., FDMS uses 18 = Success, 05 = Failure). #### S95 - Version Request Request: ``` S95 ``` Response: ``` ``` * response code: 00 success Alternative S95 Implementation for FDMS: * Serial number padded with 17 bytes (not 18) * 0 used as padding character instead of space * Application will not send OS version details in S95 response Sample FDMS S95 response: ``` 00FdmsKeyLoader0000000000000000000000000275062360x ``` Parameter added: * DEVID — Device ID value appended after the serial number in S95 response. (appconfig.ini) Sample FDMS response with DEVID: ``` 00FdmsKeyLoader0000000000000000000000000275062360*1513*~ ``` #### S97 - Load Keys Request: ``` S97 ``` * loadkeys: 0 = master keys, 1 = working keys * keylength: 0 = single, 1 = double Response: ``` ``` #### S98 - Get BSN Request: ``` S98> ``` Response: ``` ``` #### S99 - Inject BSN Request: ``` S99 ``` Response: ``` ``` * Response codes: 00 success, 01 unsuccessful, 02 BSN non-alphanumeric, 03 BSN length not 16 * NOTE: For GPC, only 00 and 01 are returned; remaining values apply for ACCEO and Scotia Bank. #### 0x23 - Read SN (Moneris) Request: ``` <0x23> ``` Response: ``` <0x23>00000020 ``` * serial# = 6 digits of terminal serial number #### 0x24 - Change KTK PW (Moneris) Request: ``` <0x24> ``` Response: * Success: ``` (0x24)[seq#] ``` * Failure: ``` (0x31)[seq#]00 ``` #### 0x60 - Inject Keys (Moneris) Request: ``` <0x60> ``` * keyinfo: 8-digit string indicating which keys and formats are present * keydata length depends on keyinfo bits (16 or 32 bytes) Response: * Success: ``` (0x60)[seq#] ``` * Failure: ``` (0x31)[seq#]00 ``` #### 0x61 - Read Check Sum (Moneris) Request: ``` <0x61> ``` Response: * Success: ``` (0x61)[seq#][keyinfo][keydata] ``` * Failure: ``` (0x31)[seq#] ``` ## Notes * Refer to the appconfig.ini and vendor-specific sections for exact command mappings, flags, config parameters, and examples. * For FDMS S95 variant and DEVID behavior, see the "Alternative S95 Implementation for FDMS" section above. * Serial/baud and other communication parameters must match between Key Loading Software and terminal. ## Contact / Vendor Info Verifone North America Development The Royal Center Four 11700 Great Oaks Way, Suite 210 Alpharetta, GA 30022 [www.verifone.com](http://www.verifone.com) (End of document) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verifone.com/xpi/tbd-documentation/keyloader/new_xpi_generic_keyloader_userguide_vers1.0e.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.