Rev. A 11/27/2017. ID TECH Configuration Utility Quick Start Guide

Transcription

1 Rev. A 11/27/2017 ID TECH Configuration Utility Quick Start Guide

2 Copyright 2017, International Technologies and Systems Corporation. All rights reserved. ID TECH Walker Street Cypress, CA USA This document, as well as the hardware and software it describes, is furnished under license and may only be used in accordance with the terms of such license. The content of this paper is furnished for informational use, subject to change without notice, and not to be construed as a commitment by ID TECH. ID TECH assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. Except as permitted by such license, no part of this publication may be reproduced or transmitted by electronic, mechanical, recorded, or any other method, or translated into another language or language form without the express written consent of ID TECH. ID TECH is a registered trademark of International Technologies and Systems Corporation. ViVOpay and Value through Innovation are trademarks of International Technologies and Systems Corporation. Other trademarks are the property of the respective owner. 2

3 CONTENTS WELCOME TO THE ID TECH CONFIGURATION UTILITY... 4 QUESTIONS?... 4 PREREQUISITES... 4 STARTING THE CONFIGURATION UTILITY... 4 MODES OF OPERATION... 5 BASIC MODE... 5 ADVANCED MODE... 6 Specifying the Utility's Default Connection Behavior (ADVANCED Mode)... 7 FILES CREATED BY THE CONFIGURATION UTILITY... 8 LOG FILES... 8 CONFIGURATION FILES (JSON)... 8 HOW TO CREATE A CONFIGURATION PROFILE... 9 HOW TO CONFIGURE A READER USING AN EXISTING JSON PROFILE... 9 HOW TO RUN A TEST TRANSACTION HOW TO ADJUST TERMINAL SETTINGS HOW TO EDIT OR REPLACE A CAPK HOW TO EDIT OR REPLACE AN AID FOR MORE INFORMATION

4 Welcome to the ID TECH Configuration Utility The ID TECH Configuration Utility is designed to make it easy for a non-technical operator to configure ID TECH card readers (using values stored in a simple text file) with a Windows app that features an intuitive graphical user interface. The Configuration Utility offers features that will be useful not only to non-technical users, but to advanced users who need to inspect and/or adjust individual device settings, one by one. The Utility also makes it easy for a user to "clone" device settings from a given device, essentially capturing a snapshot of the device's configuration settings. This guide is focused on helping the non-technical user become productive with the ID TECH Configuration Utility as quickly as possible. It does not go into detail with regard to all the advanced functionalities available in the ADVANCED tab of the UI. It concentrates mostly on the BASIC interface functionalities, which are aimed at allowing a user to configure devices very quickly with a minimum of UI interaction. Questions? If you have questions that aren't answered by this document, contact us at support@idtechproducts.com. Also be sure to check out our Knowledge Base at Prerequisites The Configuration Utility is a standalone Windows app that requires Windows 7 or higher. It requires approximately 5 megabytes of disk space. The Utility comes with a Windows installer program. You may need to run the installer in Administrator mode, and you may need to dismiss antivirus/malware messages in order to complete the installation. You will not need to reboot your machine, however. Please go ahead and run the installer before proceeding with the steps outlined below. Starting the Configuration Utility Find and double-click the ConfigUtility.exe file. You can plug a card reader in to your host computer at any time before or after starting the Utility, using either USB or a DB9 serial port. The Utility will auto-detect the device and connect automatically. 4

5 NOTE: Version 1.2.x of the Configuration Utility officially supports ID TECH Augusta (and Augusta S) card readers only, although it will connect to other ID TECH devices. Modes of Operation When the Utility starts, you'll see a large window with BASIC and ADVANCED headers near the top. (The application launches in BASIC mode by default.) You'll use the BASIC mode to view device information (device name, serial number, firmware version, etc.); select a configuration file; and load configurations into the connected device. You'll use the ADVANCED mode UI to export a JSON profile based on a connected device's existing configuration; read, edit, and/or set various configuration values in the connected device; run various commands in real time; switch a USB device between HID and Keyboard (KB) modes; and/or carry out other low-level operations (as described further below). BASIC MODE When the Configuration Utility first launches, it opens its main window in BASIC mode, showing BASIC device settings. (If you have not yet plugged a device into your machine, you can do so before or after launching the program.) NOTE: USB devices will be automatically detected, and will connect in a matter of a second or two. (Allow approximately 5 seconds for detailed device info to load.) If your device is connecting via a serial (COM) port, you may have to go into the ADVANCEDmode UI, click the DEVICE SELECTION button (at the top of the left panel), and choose appropriate serial settings in the Options UI (middle panel). In the black header bar at the top of the window, the name of the device is shown along with its connection mode (in parentheses). For example, in the screen shot below, the header bar says Augusta (USB HID). NOTE: Augusta can operate in HID mode, or in Keyboard (KB) mode. This is important because many commands are not available in KB mode. You can switch the device's USB mode in the ADVANCED interface (described further below). 5

6 The BASIC mode UI (see illustration above) shows three panels, or cards, called Device Information, Set Configuration, and Log. The Device Information card (left) shows the connection status of the device, Serial Number, Firmware Version, Key Status, and other basic statistics about the currently connected device. The Set Configuration panel (in the center) lists information that comes from the currently selected JSON configuration profile. If no profile has yet been selected, you can use the SELECT button to navigate your local file system in order to find a JSON configuration profile that you can use as the basis for updating your reader. (After selecting a profile, that profile remains in memory until you shut the application down, or select a different profile. Normally, you will select one profile, and use that profile throughout your session.) After a profile has been selected, a LOAD button will appear at the bottom of this panel. The Log card (right) will display human-readable messages, in real time, as various operations are carried out by the utility. ADVANCED MODE Near the top of the window, you can click the word ADVANCED to toggle the Advanced UI into view. 6

7 The Advanced UI has three panels (or cards). The leftmost card, Functions, will show the buttons depicted above, if the device is in USB-HID mode. (It will show fewer buttons if the device is in USB-KB mode, because many of Augusta's functions are available only in HID mode.) Notice the SET KB MODE button on the lower left. You can use this button to switch to keyboard mode at any time. Conversely, in KB mode, you can switch back to HID mode at any time. The middle card is dynamic, and will take on a different appearance depending on which buttons you've clicked in the Functions card. In the above screen shot, we have already clicked the TERMINAL SETTINGS button in Functions. As a result, the middle card has updated to show commands relevant to "Terminal Settings." As with the BASIC mode interface, the ADVANCED interface has a Log card on the right, to show real time log messages. Specifying the Utility's Default Connection Behavior (ADVANCED Mode) You can specify how the Configuration Utility should react when it recognizes a plugged-in device. The Utility can: Refresh the Device Information shown in the BASIC user interface. (This is the default behavior.) Immediately configure the device using the currently selected device profile. Or: Do nothing. 7

8 These options are available as radio buttons in the center card of the ADVANCED user interface, after you have clicked the DEVICE SELECTION button in the Functions card. The second option ("Install Selected Profile") is a power-user feature, designed to make it possible for a user to auto-configure multiple readers, one after another, simply by plugging in (and unplugging) readers. You would use this option after selecting a configuration profile that you know you want to replicate quickly across multiple devices. When the third option ("No action") is specified, the Utility will not pause to gather basic device information when a new device is plugged in. Instead, the Utility will show "Connected" when the device is recognized, at which point the user can immediately carry out various BASIC or ADVANCED options without further ado. This option is for users who don't want to wait any longer than necessary to use the Utility's UI after plugging in a device. Files Created by the Configuration Utility Take a moment to become familiar with the files created by ID TECH's Configuration Utility. Log FIles The Configuration Utility automatically generates log files, which are written to %appdata%\roaming\configutility\logs. Log files are automatically named according to the year, month, and day they were created (with names that conform to YYYY-MM-DD.log). These files are simple text files that can be opened in any text editor (or web browser). Within log files, log entries are timestamped and show which devices have been plugged in, which operations took place, and information about any errors that occurred. NOTE: It's a good idea to create a bookmark, pointing at the Log folder, in your favorite browser, so you can get to the logs quickly. (You will want to have ready access to the log files if any errors occur during configuration, or if you need to contact ID TECH's Technical Support team.) The bookmarked URL will be of the form file:///c:/users/[username]/appdata/roaming/configutility/logs/, where [username] is the Windows log-in name of the user. Configuration Files (JSON) The ID TECH Configuration Utility can create and use JSON-based configuration profiles, which you can (re)name and store on disk, send to other team members via , inspect using your favorite JSON editor, etc. 8

9 NOTE: JSON (JavaScript Object Notation) is a commonly used data format for textbased data that can capture complex hierarchical relationships. It serves the same purpose as XML, but is less verbose, and more easily human-readable. If you did not receive a JSON profile with your Configuration Utility, or you've lost the one you had, you can create a new one very easily, as follows. How to Create a Configuration Profile To create a JSON profile: 1. Launch the Configuration Utility. 2. Plug an Augusta (or Augusta S) reader into your host computer. 3. Select the ADVANCED interface tab. 4. In the Functions card, click the CREATE PROFILE FROM DEVICE button. 5. A dialog appears, asking "Capture Device Settings to Configuration Profile?" Click Yes. 6. The Utility will read all configuration settings from the device, writing progress messages to the Log pane; then it will present a Save File dialog. Choose a name for your config file (ending in.json), and Save it to disk. The above procedure essentially clones all the settings from a particular device, and captures them in a configuration file you can use to configure other devices. How to Configure a Reader Using an Existing JSON Profile If you already have a configuration profile that you want to use for configuring a device, you can use the following procedure. To configure a device with an existing JSON profile: 1. Launch the Configuration Utility. (If the Utility is already running, and is not already in BASIC mode, click the BASIC tab near the top of the screen.) 2. Plug a reader into your host machine. Allow a few seconds for it to connect. (The Device Information card of the UI should populate with Serial Number and other information.) If you are using a serial (COM) port rather than a USB port, you may need to switch to the ADVANCED tab, click the Device Selection button in the Functions card, and make appropriate choices in the center card, to establish a connection. 3. If you have not already done so, click the SELECT button in the middle card of the BASIC interface. A file-navigator dialog will appear. 4. Navigate to where your.json file is stored, and select. Use the Open button of the dialog to dismiss the dialog. 5. Click the LOAD button to begin the loading process. You should see various messages appear in the Log card, in real time. (The final message should say "Finished Loading Profile to the Device.") Allow approximately 15 seconds for the operation to finish. This time is highly variable and will depend on the actual settings contained in the.json file. 9

10 Once you click the LOAD button, the Utility will begin sending configuration settings to the connected device. If any error messages appear in the Log card, you can check your log file (see Log Files, above) to see additional information on the nature of the error(s). In most cases, if an error occurs, you can simply click the LOAD button again to complete the process. (If this does not correct the error, contact ID TECH Technical Support.) If the above process ran without errors, you can configure another device very easily. Just unplug the current device, plug a new device in, wait for it to register, then click the LOAD button. After a successful load, the Utility's main window should look similar to the following: Note that if the device has already been key-injected, you may see failures (in the Log screen) for certain operations, such as setting the encryption algorithm, or setting the key variant. This is expected, because those particular operations are intended for devices that have not yet been keyinjected. How to Run a Test Transaction You can verify whether the device is working properly by going into the ADVANCED interface and using either the TEST CONTACT button (to try a contact EMV transaction) or the TEST MSR SWIPE button (to try a magnetic-stripe card swipe). NOTE: The TEST CONTACT button will not appear if the device is in USB-KB mode. (Switch the device to USB-HID mode first.) If you run an MSR test-swipe, the screen should show information similar to the following: 10

11 In the Log pane, you can see track data (redacted, in this illustration, for security reasons) along with a KSN (near the bottom), and "Encryption Type: TDES." Note that a KSN will not be present if the device has not been key-injected or is not outputting encrypted data. To run a contact EMV transaction, use the TEST CONTACT button. Assuming the device has been properly configured with CAPKs, AIDs, and Terminal Settings, TLV data produced by the transaction will show up in the Log card. NOTE: For security reasons, we strongly recommend you use test cards (rather than live credit cards) in testing, because although the Configuration Utility will not go online nor charge your card, it will display live card data on the screen (and in some cases, persist it to log files). How to Adjust Terminal Settings Configuring a reader for EMV often means making adjustments to Terminal Settings. This is a potentially complex subject; for an introduction to it, we recommend that you take a look at the Knowledge Base article called "Which Terminal Settings Am I Allowed to Change?" at Terminal Settings are specified using TLV data (tag/length/value format). Most settings use industry-standard (EMVCo-defined) tags. Some use ID TECH proprietary tags. (For information on these tags, consult the latest revision of ID TECH's TLV Tag Reference Guide, available at 11

12 In some cases, you may want to add a TLV to those that already exist in your device's Terminal Settings, or change an individual TLV's value (or maybe add several new TLVs). Below, we give the procedure for adding a new TLV containing the proprietary DFEF4B tag, which tells Augusta to include a tag DFEF4D, in the transaction output, with track-equivalent encrypted data in a controllable output format. (See Tech Note 010, "How to Control Track Data Output in Augusta," available from the URL mentioned above.) The data for this tag is 3 bytes, and a typical setting is , which means to output (in DFEF4D) Track 2 data only, with sentinels. To add a custom TLV to Terminal Settings: 1. Launch the Configuration Utility and go to the ADVANCED tab. (Also: Plug in an Augusta reader, if you have not already done so.) 2. In the Functions card, click the Terminal Settings button. The center card will update. 3. In the center card's text area, type DFEF4B030000, as shown below: 4. Click the Add/Update button at the bottom. 5. A dialog appears, asking "Add the data to the terminal configuration?" Click Yes. 6. The Utility will add the TLV to Augusta's Terminal Settings. To confirm that it was added, click the GET TERMINAL SETTINGS button in the center card. You should see a display similar to that shown below. 12

13 In the center card, the text area contains all Terminal Settings TLVs as a continuous block. In the Log card (at right), the same TLVs are listed individually, one per line, with DFEF4B shown on the last line. How to Edit or Replace a CAPK An important part of configuring an EMV card reader for L3 certification or completing production transaction is provisioning it with CAPKs (Certificate Authority Public Keys). If the terminal configuration has offline data authentication enabled, the reader's EMV L2 kernel needs to have applicable public keys on hand for all the cards and card brands with which it is expected to interact in production. These keys are required so that the kernel can perform the necessary offline data authentication calculations for the transaction. If the needed CAPKs are not present during a transaction (or are out of date), the transaction will indicate offline data authentication failure and most likely be declined by the host (or for offline transactions, declined if the Terminal Actions Codes do not allow offline approval with failed offline data authentication). This is, in fact, a common reason for transaction declines in EMV devices that are otherwise correctly configured. NOTE: CAPKs are created by the card brands and are usually available from transaction processors. Ask your gateway or processor for details. ID TECH does not maintain a CAPK database. Any CAPKs provided by ID TECH are provided for testing purposes only. Production CAPKs must be obtained from the issuers and/or their representatives. Since CAPKs periodically expire and need to be replaced individually, it's handy to know how to replace an individual CAPK. The procedure for doing this is outlined below. (Note: This procedure assumes that your device already contains one or more CAPKs.) 13

14 To edit or replace a CAPK: 1. Launch the Configuration Utility and go to the ADVANCED tab. (Also: Plug in a card reader, if you have not already done so.) 2. In the Functions card (on the left), click the CONTACT CAPK button. The center card will update its appearance. 3. In the center card ("Contact CAPK"), click the top button, LIST INSTALLED CONTACT CAPK. The right-hand (Log) card will update with a list of the CAPKs that are in your reader. 4. In the Log, find the name of the CAPK you wish to replace. Copy the name of the CAPK from the Log and Paste it into the NAME field of the center card. (For this example, we will use the CAPK identified as 'a e5'.) 5. In the center card, click the RETRIEVE button. The card's large text area will fill with hexadecimal data: 14

15 6. Click the button labeled SHOW CAPK FORM. A dialog appears, with various controls already pre-populated (see screen shot below). 7. Edit any fields that need updating. 8. Click OK. 9. Click the ADD/UPDATE button at the bottom of the center card. This will push the updated CAPK into the connected reader. (If the operation succeeds, the Log card will contains a message: "Save CAPK Successful.") How to Edit or Replace an AID Chip cards contain "applications" (which are really just sets of TLVs) known by their Application Identifiers (or AIDs). The card reader's EMV L2 kernel needs to be provisioned with a list of the AIDs for the cards it expects to interact with in production. For every card brand the terminal will be allowed to process, there must be a matching aid installed on the terminal, or the transaction will terminate. Missing AID files and being unable to match the Application Identifier of an inserted card is the main reason a transaction will fail. Generally speaking, these AIDs, unlike CAPKs, are static and do not go out of date (hence will not require periodic replacement), but it's quite possible you will want to edit some of the tag values associated with a given AID, to reflect the transaction environment as it applies to a given production site. For example, one of the tags in a typical "application" is 5F2A, which specifies the Country Identifier. For a customer in the United States, this tag would have a value of 0840, whereas for a customer in Canada, it would need to be set to

16 The procedure below explains how to edit the fields of an AID. (It assumes that your reader already has at least one AID installed.) To edit or replace an AID: 1. Launch the Configuration Utility and go to the ADVANCED tab. (Also: Plug in a card reader, if you have not already done so.) 2. In the Functions card (on the left), click the CONTACT AID button. The center card will update its appearance. 3. In the center card, use the top button (LIST INSTALLED CONTACT AID) to make all installed AIDs show up in the Log card. 4. Copy the AID of interest from the Log card, and Paste it into the NAME field of the center card. 5. Click the center card's RETRIEVE button. The card's text area will update to show the TLV data of the AID. 6. Find the tag of interest and hand-edit its value. For example, locate tag 5F2A, and change '0840' to '0124' (or to the country code that applies): 16

17 9f f f2a f f f1b a98df25039f3704df28039f0802dfee150101df df df df180100df df In the center card, click the ADD/UPDATE button to send the updated AID data to your connected reader. On success, a message will appear in the Log card ("Save AID Successful"). For More Information If you have questions that aren't answered by this document, contact us at support@idtechproducts.com. Also be sure to check out our Knowledge Base at For additional information on EMV transactions and what the various configuration options mean, we recommend you download the white paper at saction%20with%20universal%20sdk.pdf?api=v2 (immediate download, no registration required). 17