Magtek MagneSafe V5 User manual

MagneSafe V5
COMMUNICATION REFERENCE MANUAL
PART NUMBER 99875475-10
NOVEMBER 2012
REGISTERED TO ISO 9001:2008
1710 Apollo Court
Seal Beach, CA 90740
Phone: [phone]
FAX: [phone]
Technical Support: [phone]
www.magtek.com

ii
Copyright©2001-2013
MagTek®, Inc.
Printed in the United States of America
Information in this document is subject to change without notice. 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.
MagnePrint is a registered trademark of MagTek, Inc.
MagneSafe™is a trademark of MagTek, Inc.
Magensa™is a trademark of MagTek, Inc.
USB (Universal Serial Bus) Specification is Copyright©1998 by Compaq Computer
Corporation, Intel Corporation, Microsoft Corporation, NEC Corporation.
Appendix A is taken from Universal Serial Bus HID Usage Tables, Version 1.12, Section 10,
Keyboard/Keypad Page (0x07) ©1996-2005 USB Implementers’ Forum
Appendix B is taken from Section 8.3 Report Format for Array Items, Device Class Definition
for Human Interface Devices (HID) Version 1.11, ©1996-2001 USB Implementers’ Forum,
[email protected]
REVISIONS
Rev
Number
Date
Notes
1.01
08 Jan 10
Initial Release (previously part of 99875388)
2.01 03/29/2010 Corrected settings for SureSwipe mode; corrected data length
values in a few of the examples
3.01
May 25, 2010
Updated some text to be consistent with other manuals
4.01
July 2, 2010
Added Bulk Encryption
5.01
June, 24, 2011
Corrected default for MP Flags Property; added properties and
commands for Flash, Insert and Serial readers; corrected references
to USB and other interface types; included comprehensive property
map
6.01
November 4, 2011
Property 0x0E available for BulleT
7.01
November 8, 2011
Removed “only once” from the Set Property entry of the USB Serial
Num Property and changed default value to the device serial
number; changed default value of Device Serial Num Property to the
device serial number
8.01 January 12, 2012 Changed “Wireless USB Reader Only” to “BulleT, Flash, Wireless
USB” on Activity Timeout Period and Stay Powered After Swipe
Property.; added note showing how to leave power on continuously
9.01
January 25, 2012
Updated some properties to reflect UART/RS-232 operation
10.01
November 30, 2012
Added BulleT KB interface

iii
LIMITED WARRANTY
MagTek warrants that the products sold pursuant to this Agreement will perform in accordance with MagTek’s
published specifications. This warranty shall be provided only for a period of one year from the date of the
shipment of the product from MagTek (the “Warranty Period”). This warranty shall apply only to the “Buyer”
(the original purchaser, unless that entity resells the product as authorized by MagTek, in which event this
warranty shall apply only to the first repurchaser).
During the Warranty Period, should this product fail to conform to MagTek’s specifications, MagTek will, at its
option, repair or replace this product at no additional charge except as set forth below. Repair parts and
replacement products will be furnished on an exchange basis and will be either reconditioned or new. All replaced
parts and products become the property of MagTek. This limited warranty does not include service to repair
damage to the product resulting from accident, disaster, unreasonable use, misuse, abuse, negligence, or
modification of the product not authorized by MagTek. MagTek reserves the right to examine the alleged
defective goods to determine whether the warranty is applicable.
Without limiting the generality of the foregoing, MagTek specifically disclaims any liability or warranty for
goods resold in other than MagTek’s original packages, and for goods modified, altered, or treated without
authorization by MagTek.
Service may be obtained by delivering the product during the warranty period to MagTek (1710 Apollo Court,
Seal Beach, CA 90740). If this product is delivered by mail or by an equivalent shipping carrier, the customer
agrees to insure the product or assume the risk of loss or damage in transit, to prepay shipping charges to the
warranty service location, and to use the original shipping container or equivalent. MagTek will return the
product, prepaid, via a three (3) day shipping service. A Return Material Authorization (“RMA”) number must
accompany all returns. Buyers may obtain an RMA number by contacting Technical Support at [phone].
EACH BUYER UNDERSTANDS THAT THIS MAGTEK PRODUCT IS
OFFERED AS IS. MAGTEK MAKES NO OTHER WARRANTY, EXPRESS OR
IMPLIED, AND MAGTEK DISCLAIMS ANY WARRANTY OF ANY OTHER
KIND, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
IF THIS PRODUCT DOES NOT CONFORM TO MAGTEK’S SPECIFICATIONS, THE SOLE REMEDY
SHALL BE REPAIR OR REPLACEMENT AS PROVIDED ABOVE. MAGTEK’S LIABILITY, IF ANY,
SHALL IN NO EVENT EXCEED THE TOTAL AMOUNT PAID TO MAGTEK UNDER THIS
AGREEMENT. IN NO EVENT WILL MAGTEK BE LIABLE TO THE BUYER FOR ANY DAMAGES,
INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OF, OR INABILITY TO USE, SUCH PRODUCT, EVEN IF
MAGTEK HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY
ANY OTHER PARTY.
LIMITATION ON LIABILITY
EXCEPT AS PROVIDED IN THE SECTIONS RELATING TO MAGTEK’S LIMITED WARRANTY,
MAGTEK’S LIABILITY UNDER THIS AGREEMENT IS LIMITED TO THE CONTRACT PRICE OF THIS
PRODUCT.
MAGTEK MAKES NO OTHER WARRANTIES WITH RESPECT TO THE PRODUCT, EXPRESSED OR
IMPLIED, EXCEPT AS MAY BE STATED IN THIS AGREEMENT, AND MAGTEK DISCLAIMS ANY
IMPLIED WARRANTY, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
MAGTEK SHALL NOT BE LIABLE FOR CONTINGENT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES TO PERSONS OR PROPERTY. MAGTEK FURTHER LIMITS ITS LIABILITY OF ANY KIND
WITH RESPECT TO THE PRODUCT, INCLUDING ANY NEGLIGENCE ON ITS PART, TO THE
CONTRACT PRICE FOR THE GOODS.
MAGTEK’S SOLE LIABILITY AND BUYER’S EXCLUSIVE REMEDIES ARE STATED IN THIS SECTION
AND IN THE SECTION RELATING TO MAGTEK’S LIMITED WARRANTY.

iv
FCC WARNING STATEMENT
This equipment has been tested and was found to comply with the limits for a Class B digital device pursuant to
Part 15 of FCC Rules. These limits are designed to provide reasonable protection against harmful interference
when the equipment is operated in a residential environment. This equipment generates, uses, and can radiate
radio frequency energy and, if not installed and used in accordance with the instruction manual, may cause
harmful interference with radio communications. However, there is no guarantee that interference will not occur
in a particular installation.
FCC COMPLIANCE STATEMENT
This device complies with Part 15 of the FCC Rules. Operation of this device is subject to the following two
conditions: (1) this device may not cause harmful interference, and (2) this device must accept any interference
received, including interference that may cause undesired operation.
CANADIAN DOC STATEMENT
This digital apparatus does not exceed the Class B limits for radio noise from digital apparatus set out in the
Radio Interference Regulations of the Canadian Department of Communications.
Le présent appareil numérique n’émet pas de bruits radioélectriques dépassant les limites applicables aux
appareils numériques de la classe B prescrites dans le Réglement sur le brouillage radioélectrique édicté par le
ministère des Communications du Canada.
This Class B digital apparatus complies with Canadian ICES-003.
Cet appareil numériqué de la classe B est conformé à la norme NMB-003 du Canada.
CE STANDARDS
Testing for compliance with CE requirements was performed by an independent laboratory. The unit under test
was found compliant with standards established for Class B devices.
UL/CSA
This product is recognized per Underwriter Laboratories and Canadian Underwriter Laboratories 1950.
RoHS STATEMENT
When ordered as RoHS compliant, this product meets the Electrical and Electronic Equipment (EEE) Reduction
of Hazardous Substances (RoHS) European Directive 2002/95/EC. The marking is clearly recognizable, either as
written words like “Pb-free”, “lead-free”, or as another clear symbol ( ).

v
TABLE OF CONTENTS
SECTION 1. SECURITY............................................................................................................1
SECURITY LEVEL 2 ................................................................................................................................1
SECURITY LEVEL 3 ................................................................................................................................ 1
SECURITY LEVEL 4 ................................................................................................................................1
COMMANDS AND SECURITY LEVELS..................................................................................................2
SECTION 2. COMMUNICATIONS.............................................................................................3
HID USAGES............................................................................................................................................ 3
MAGNETIC STRIPE READER USAGE PAGE (HID) ..............................................................................4
REPORT DESCRIPTOR (HID) ................................................................................................................5
MAGNETIC STRIPE READER USAGE PAGE (KB)................................................................................7
REPORT DESCRIPTOR (KB)..................................................................................................................7
CARD DATA (HID) ...................................................................................................................................8
Track 1 Decode Status.......................................................................................................................10
Track 2 Decode Status.......................................................................................................................10
Track 3 Decode Status.......................................................................................................................10
Track 1 Encrypted Data Length..........................................................................................................10
Track 2 Encrypted Data Length..........................................................................................................10
Track 3 Encrypted Data Length..........................................................................................................11
Track 1 Absolute Data Length............................................................................................................11
Track 2 Absolute Data Length............................................................................................................11
Track 3 Absolute Data Length............................................................................................................11
Card Encode Type..............................................................................................................................11
Encrypted Track Data.........................................................................................................................11
Track 1 Encrypted Data......................................................................................................................12
Track 2 Encrypted Data......................................................................................................................12
Track 3 Encrypted Data......................................................................................................................12
Card Status.........................................................................................................................................12
MagnePrint Status..............................................................................................................................13
MagnePrint Data Length.....................................................................................................................13
MagnePrint Absolute Data Length .....................................................................................................13
Encrypted MagnePrint Data ...............................................................................................................14
Device Serial Number.........................................................................................................................14
Track 1 Masked Data Length .............................................................................................................14
Track 2 Masked Data Length .............................................................................................................14
Track 3 Masked Data Length .............................................................................................................14
Masked Track Data ............................................................................................................................14
Track 1 Masked Data .........................................................................................................................15
Track 2 Masked Data .........................................................................................................................15
Track 3 Masked Data .........................................................................................................................16
Encrypted Session ID.........................................................................................................................16
DUKPT Key Serial Number................................................................................................................16
Encryption Counter.............................................................................................................................16
MagneSafe Version Number..............................................................................................................17
Hashed Track 2 Data..........................................................................................................................17
Clear Text CRC ..................................................................................................................................17
Encrypted CRC...................................................................................................................................17
CARD DATA (KB AND OTHER MODELS)............................................................................................17
Reader Encryption Status...................................................................................................................19
Format Code.......................................................................................................................................20
PROGRAMMABLE CONFIGURATION OPTIONS ................................................................................20
Low Level Communications................................................................................................................21
COMMANDS ..........................................................................................................................................21
Privileged Commands ........................................................................................................................22

vi
Command Number.............................................................................................................................22
Data Length........................................................................................................................................23
Data....................................................................................................................................................23
Result Code........................................................................................................................................23
GET AND SET PROPERTY COMMANDS ............................................................................................23
Get Property Command......................................................................................................................23
Set Property Command......................................................................................................................24
Result Codes......................................................................................................................................24
PROPERTIES.........................................................................................................................................24
Property ID..........................................................................................................................................24
Property Default Values......................................................................................................................26
Software ID Property..........................................................................................................................26
USB Serial Num Property (USB)........................................................................................................27
Polling Interval Property (USB) ..........................................................................................................28
Device Serial Num Property...............................................................................................................29
MagneSafe Version Number..............................................................................................................29
Track ID Enable Property...................................................................................................................30
ISO Track Mask Property...................................................................................................................31
AAMVA Track Mask Property.............................................................................................................31
Max Packet Size Property (HID) ........................................................................................................32
UART/RS-232 COMMUNICATIONS PROPERTY (UART/RS-232 READERS ONLY).........................33
Activity Timeout Period Property (BulleT, Flash, Wireless USB).......................................................34
Bluetooth Disconnect Message Property (BulleT Only).....................................................................35
Track Data Transmission Delay Property (Flash Only)......................................................................35
Stay Powered After Swipe Property (BulleT, Flash, Wireless USB)..................................................36
RF Address Property (BulleT and Wireless USB Reader).................................................................36
Interface Type Property......................................................................................................................38
Track Data Send Flags Property (KB, BulleT SPP, Bullet KB, UART, RS-232)................................39
MP Flags Property..............................................................................................................................40
Active Keymap Property (KB).............................................................................................................41
ASCII to Keypress Conversion Type Property (KB)...........................................................................42
CRC Flag Property (KB and Serial Models).......................................................................................43
Keyboard SureSwipe Flag Property (KB, UART, RS-232).................................................................44
Decode Enable Property ....................................................................................................................44
SS JIS Type 2 Property......................................................................................................................45
ES JIS Type 2 Property......................................................................................................................46
Pre Card String Property (KB, BulleT, UART, RS-232) .....................................................................46
Post Card String Property (KB, BulleT, UART, RS-232)....................................................................47
Pre Track String Property (KB, BulleT, UART, RS-232)....................................................................47
Post Track String Property (KB, BulleT, UART, RS-232)...................................................................48
Termination String Property (KB, BulleT, UART, RS-232).................................................................49
FS Property (KB, BulleT, UART, RS-232)..........................................................................................49
SS Track 1 ISO ABA Property (KB, BulleT, UART, RS-232).............................................................49
SS Track 2 ISO ABA Property (KB, BulleT, UART, RS-232).............................................................50
SS Track 3 ISO ABA Property (KB, BulleT, UART, RS-232).............................................................50
SS Track 3 AAMVA Property (KB, BulleT, UART, RS-232)...............................................................50
SS Track 2 7bits Property (KB, BulleT, UART, RS-232)....................................................................51
SS Track 3 7bits Property (KB, BulleT, UART, RS-232)....................................................................51
ES Property (KB, BulleT, UART, RS-232)..........................................................................................51
Format Code Property (KB, BulleT, UART, RS-232) .........................................................................52
ES Track 1 Property (KB, BulleT, UART, RS-232).............................................................................52
ES Track 2 Property (KB, BulleT, UART, RS-232).............................................................................53
ES Track 3 Property (KB, BulleT, UART, RS-232).............................................................................53
Send Encryption Counter Property (KB, BulleT, UART, RS-232)......................................................53
Mask Other Cards Property................................................................................................................54
MSR Direction Property (Insert Reader Only)....................................................................................54

vii
Card Inserted Property (Insert Reader Only) .....................................................................................55
Send Clear AAMVA Card Data Property............................................................................................56
HID SureSwipe Flag Property (HID)...................................................................................................56
Software ID 2 Property (Wireless USB Reader Only)........................................................................57
Inter-Key Delay Property (BulleT KB).................................................................................................58
COMMAND LIST ....................................................................................................................................59
Reset Device Command.....................................................................................................................59
Get Keymap Item Command (KB)......................................................................................................60
Set Keymap Item Command (KB)......................................................................................................61
Save Custom Keymap Command (KB)..............................................................................................63
DUKPT Operation...............................................................................................................................63
Get DUKPT KSN and Counter Command.....................................................................................63
Set Session ID Command..................................................................................................................64
Activate Authenticated Mode Command............................................................................................65
Activation Challenge Reply Command...............................................................................................66
Deactivate Authenticated Mode Command........................................................................................67
Get Reader State Command..............................................................................................................68
Set Security Level Command.............................................................................................................70
Get Transaction Count Command (Flash Reader Only)....................................................................71
Read Oldest Transaction Command (Flash Reader Only) ................................................................71
Erase Oldest Transaction Command (Flash Reader Only)................................................................72
Get Encryption Counter Command....................................................................................................72
Power Down Command (Wireless USB Reader Only) ......................................................................73
Get Battery Status Command (Wireless USB Reader Only) .............................................................74
Encrypt Bulk Data Command.............................................................................................................74
SECTION 3. DEMO PROGRAM..............................................................................................77
INSTALLATION ......................................................................................................................................77
OPERATION...........................................................................................................................................77
SOURCE CODE.....................................................................................................................................78
APPENDIX A. KEYBOARD USAGE ID DEFINITIONS ...........................................................79
KEYBOARD/KEYPAD PAGE (0X07).....................................................................................................79
APPENDIX B. MODIFIER BYTE DEFINITIONS......................................................................87
APPENDIX C. GUIDE ON DECRYPTING DATA.....................................................................89
APPENDIX D. COMMAND EXAMPLES..................................................................................91
APPENDIX E. IDENTIFYING ISO/ABA AND AAMVA CARDS.............................................125
ISO/ABA FINANCIAL CARDS..............................................................................................................125
AAMVA DRIVER LICENSES................................................................................................................126
APPENDIX F. LIST OF PROPERTIES ..................................................................................127

viii

1
SECTION 1. SECURITY
The readers in the family are intended to be secure readers. Security features include:
•Supplies 54 byte MagnePrint value
•Includes Device Serial Number
•Encrypts all track data and the MagnePrint value
•Provides clear text confirmation data including card holder’s name, expiration date, and a
portion of the PAN as part of the Masked Track Data
•Supports Mutual Authentication Mode for use with Magensa.net
•Offers selectable levels of Security
Most of the MagneSafe readers support three Security Levels. The Security Level can be
increased by command but can never be decreased.
SECURITY LEVEL 2
Security Level 2 is the least secure user mode. In this mode, keys are loaded but not used for
most operations (only used to load new keys or move to Security Level 3 or 4). All other
properties and commands are freely usable.
For those products that support keyboard emulation mode or those that provide serial
information (e.g., via RS-232 communication), the reader sends data in the SureSwipe format as
defined in MagTek document 99875206. The default SureSwipe mode can be changed to allow
the reader to send data in the V5 format as described in this document but the MagnePrint data
will not be sent.
In the HID mode, the reader sends track data but does not send MagnePrint data. By default, the
data is sent in the format defined in this manual. Changing the HID SureSwipe Flag property to
0x01 will cause the reader to use the SureSwipe VID/PID and send data as defined in 99875191
(USB HID SureSwipe & USB HID Swipe Technical Reference Manual).
SECURITY LEVEL 3
Security Level 3 enables encryption of track data, MagnePrint data, and the Session ID.
MagnePrint data is always included and it is always encrypted. The format for the data is
detailed later in this document. At Security Level 3, many commands require security—most
notably, the Set Property command. Transition to Security Level 4 requires security.
SECURITY LEVEL 4
When the reader is at Security Level 4, a correctly executed Authentication Sequence is required
before the reader will emit data from a card swipe. Correctly executing the Authentication
Sequence also causes the Green LED to blink, alerting the user to the fact that the reader is being
controlled by a Host with knowledge of the keys—that is, an Authentic Host.
Commands that require security must be sent with a four byte Message Authentication Code
(MAC) appended to the end. The MAC is calculated as specified in ANSI X9.24 Part 1 – 2004,

MagneSafe V5
2
Annex A. Note that data supplied to the MAC algorithm should NOT be converted to the
ASCII-Hex, rather it should be supplied in its raw binary form. The MAC key to be used is as
specified in the same document (“Request PIN Entry 2” bullet 2). Calculating the MAC requires
knowledge of the current DUKPT KSN, which can be retrieved using the Get DUKPT KSN
and Counter command. For each command processed successfully, the DUKPT Key is
advanced.
COMMANDS AND SECURITY LEVELS
The following table shows how security levels affect the various commands. “Y” means the
command can run. “N” means the command is prohibited. “S” means the command is protected
(requires MACing). “X” means other (notes to follow).
Number
Command
Level 2
Level 3
Level 4
0x00
Get Property
Y
Y
Y
0x01
Set Property
Y
S
S
0x02
Reset Device
Y
X*
X*
0x03
Get Keymap Item
Y
Y
Y
0x04
Set Keymap Item
Y
S
S
0x05
Save Custom Keymap
Y
S
S
0x09
Get DUKPT KSN and Counter
Y
Y
Y
0x0A
Set Session ID
Y
Y
Y
0x10
Activate Authenticated Mode
N
Y
Y
0x11
Activation Challenge Reply
N
Y
Y
0x12
Deactivate Authenticated Mode
N
Y
Y
0x14
Get Reader State
Y
Y
Y
0x15
Set Security Level
S
S
S
0x16
Get Transaction count Command (Flash
Reader Only)
Y Y Y
0x17
Read Oldest Transaction Command
(Flash Reader Only)
Y Y Y
X018
Erase Oldest Transaction Command
(Flash Reader Only)
Y Y Y
0x1C
Get Encryption Counter
Y
Y
Y
0x28
Power Down Command (Wireless USB
Reader Only) Y Y Y
0x29
Get Battery Status Command (Wireless
USB Reader Only) Y Y Y
0x30
Encrypt Bulk Data Command
N
Y
Y
* The Reset command has special behavior. When an Authentication sequence has failed, only a
correctly MACd Reset command can be used to reset the reader. This is to prevent a dictionary
attack on the keys and to minimize a denial of service attack.