Linux Sample Code Manual

Manual Part Number: D998200733-100

REGISTERED TO ISO 9001:2015

Information in this publication is subject to change without notice and may contain technical inaccuracies or graphical discrepancies. Changes or improvements made to this product will be updated in the next publication release. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of MagTek, Inc.

MagTek® is a registered trademark of MagTek, Inc. MagneSafe® is a registered trademark of MagTek, Inc. iDynamo™, and uDynamo are trademarks of MagTek, Inc.

eDynamo™, Dynamag, and DynaMAX are trademarks of MagTek, Inc.

DynaProx™, DynaFlex Pro™, and DynaFlex II PED™ are trademarks of MagTek, Inc.

The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by MagTek is under license.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. Ubuntu® is a registered trademark of Canonical Ltd.

Microsoft®, Windows® and .NET® are registered trademarks of Microsoft Corporation.

EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, LLC.

All other system names and product names are the property of their respective owners.

IMPORTANT: YOU SHOULD CAREFULLY READ ALL THE TERMS, CONDITIONS AND RESTRICTIONS OF THIS LICENSE AGREEMENT BEFORE INSTALLING THE SOFTWARE PACKAGE. YOUR INSTALLATION OF THE SOFTWARE PACKAGE PRESUMES YOUR ACCEPTANCE OF THE TERMS, CONDITIONS, AND RESTRICTIONS CONTAINED IN THIS AGREEMENT. IF YOU DO NOT AGREE WITH THESE TERMS, CONDITIONS, AND RESTRICTIONS, PROMPTLY RETURN THE SOFTWARE PACKAGE AND ASSOCIATED DOCUMENTATION TO THE ADDRESS ON THE FRONT PAGE OF THIS DOCUMENT, ATTENTION: CUSTOMER SUPPORT.

MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to as the "Software."

LICENSE: Licensor grants you (the "Licensee") the right to use the Software in conjunction with MagTek products. LICENSEE MAY NOT COPY, MODIFY, OR TRANSFER THE SOFTWARE IN WHOLE OR IN PART EXCEPT AS EXPRESSLY PROVIDED IN THIS AGREEMENT. Licensee may not decompile, disassemble, or in any other manner attempt to reverse engineer the Software. Licensee shall not tamper with, bypass, or alter any security features of the software or attempt to do so.

TRANSFER: Licensee may not transfer the Software or license to the Software to another party without the prior written authorization of the Licensor. If Licensee transfers the Software without authorization, all rights granted under this Agreement are automatically terminated.

COPYRIGHT: The Software is copyrighted. Licensee may not copy the Software except for archival purposes or to load for execution purposes. All other copies of the Software are in violation of this Agreement.

TERM: This Agreement is in effect as long as Licensee continues the use of the Software. The Licensor also reserves the right to terminate this Agreement if Licensee fails to comply with any of the terms, conditions, or restrictions contained herein. Should Licensor terminate this Agreement due to Licensee's failure to comply, Licensee agrees to return the Software to Licensor. Receipt of returned Software by the Licensor shall mark the termination.

LIMITED WARRANTY: Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded are free from defects in material or workmanship under normal use.

THE SOFTWARE IS PROVIDED AS IS. LICENSOR MAKES NO OTHER WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Because of the diversity of conditions and PC hardware under which the Software may be used, Licensor does not warrant that the Software will meet Licensee specifications or that the operation of the Software will be uninterrupted or free of errors.

IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE, OR INABILITY TO USE, THE SOFTWARE. Licensee's sole remedy in the event of a defect in material or workmanship is expressly limited to replacement of the Software disk(s) if applicable.

GOVERNING LAW: If any provision of this Agreement is found to be unlawful, void, or unenforceable, that provision shall be removed from consideration under this Agreement and will not affect the enforceability of any of the remaining provisions. This Agreement shall be governed by the laws of the State of California and shall inure to the benefit of MagTek, Incorporated, its successors or assigns.

ACKNOWLEDGMENT: LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT, UNDERSTANDS ALL OF ITS TERMS, CONDITIONS, AND RESTRICTIONS, AND AGREES TO BE BOUND BY THEM. LICENSEE ALSO AGREES THAT THIS AGREEMENT SUPERSEDES ANY AND ALL VERBAL AND WRITTEN COMMUNICATIONS BETWEEN LICENSOR AND LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.

QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED, ATTENTION: CUSTOMER SUPPORT, AT THE ADDRESS LISTED IN THIS DOCUMENT, OR E-MAILED TO .

DEMO SOFTWARE / SAMPLE CODE: Unless otherwise stated, all demo software and sample code are to be used by Licensee for demonstration purposes only and MAY NOT BE incorporated into any production or live environment. The PIN Pad sample implementation is for software PIN Pad test purposes only and is not PCI compliant. To meet PCI compliance in production or live environments, a third-party PCI compliant component (hardware or software-based) must be used.

Configuration Update

This document provides instructions to use the RMS Sample Code. Combining MagTek Linux SDK and web API calls to the Reader Management System (RMS) web service, the sample code assist in setting configurations, key injection, updating EMV Tags/CAPKs, and updating firmware for MagTek readers. The sample code is parsed into a collection of CLI apps (command line interface).

• Configuration app

• EMV Tags app

• Firmware app

For details on the RMS API see:

This sample code is built with a public RMS Profile. MagTek will provide the necessary Profile configurations and authorization Web API Keys if requested.

The MagTek Reader Management System (RMS) provides several key benefits for merchants and businesses, these include:

• Centralized Management: RMS allows for the remote management and configuration of MagTek readers across multiple locations from a single platform. Merchants can update firmware, keys, terminal settings, and CAPKs without manual intervention, reducing time, cost, and effort.

• Enhanced Security: RMS supports compliance with industry standards, such as PCI DSS, by ensuring secure payment card transactions and protecting sensitive customer data. It enables a secure process for keeping readers up to date with the latest firmware and configurations.

• Efficient Updates: RMS automates firmware updates and maintenance, allowing merchants to push updates remotely. This ensures all devices run the latest firmware, enhancing system reliability and reducing the need for manual updates.

The following packages are needed on the Linux host to build the sample code. Other dependencies are included in the makefile.

• make

• cmake

• g++

• Unzip the package.

• Go to Sample folder:

• Build the sample code using:

Various libraries and folders are generated. The two folders used for RMS Sample code are:

Each sample code folder contains an account credential for access to RMS. This is by default configured for general public use. When accessing RMS for a custom profile, reassign the values as needed in the files:

• API – Application Programming Interface

• EMV –Europay, MasterCard® and Visa®

• KSN - Key Serial Number

• MUT - MagTek Update Token

• SDK – Software Developer’s Kit

• SN - Serial Number

• UIK - Unique Identifier Key

• Force update – Supplying Version:0 in the web API call. Otherwise RMS determines of update.

Configuration Update

• Go to the folder: rms_scra and open a terminal.

• Connect the reader to a USB port.

• Enter command below. Enter password if prompted. This is for device port access.

$ sudo ./rms_scra_config_update

• A list of available configurations is returned. List depends on the firmware ID and RMS Profile. Example:

• At the prompt, select a configuration by entering its number listed to its left. A sequence of commands are downloaded from RMS and sent to the reader. Status of the configuration is shown as updated or failed and the end of the sequence.

• Whenever a configuration reports is up to date, it may be redone by entering *N, where N is the configuration. Example: *1

• Go to the folder: rms_scra and open a terminal.

• Connect the reader to a USB port.

• Enter command below. Enter password if prompted. This is for device port access.

• The sample code downloads the sequence of commands to update the EMV Tags and CAPKs available for the reader. Example:

• Whenever a configuration result is: Configuration is up to date it may be redone by adding -f to force the update.

• Go to the folder: rms_scra and open a terminal.

• Connect the reader to a USB port.

• Enter command below. Enter password if prompted. This is for device port access.

• The parameters for the firmware update is as follows.

• Example for updating MAIN firmware.

• A sequence of commands are downloaded from RMS and sent to the reader. Status of the update is shown as finished or failed and the end of the sequence.

• Whenever a firmware result is: Firmware is up to date. It may be redone by adding -f to force the update.