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: (562) 546-6400

FAX: (562) 546-6301

Technical Support: (651) 415-6800

www.magtek.com

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.

Corporation, Intel Corporation, Microsoft Corporation, NEC Corporation.

Appendix A is taken from Universal Serial Bus HID Usage Tables, Version 1.12, Section 10,

Appendix B is taken from Section 8.3 Report Format for Array Items, Device Class Definition

[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 (888) 624-8350.

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.

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

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

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

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

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

0x01

Set Property

0x02

Reset Device

0x03

Get Keymap Item

0x04

Set Keymap Item

0x05

Save Custom Keymap

0x09

Get DUKPT KSN and Counter

0x0A

Set Session ID

0x10

Activate Authenticated Mode

0x11

Activation Challenge Reply

0x12

Deactivate Authenticated Mode

0x14

Get Reader State

0x15

Set Security Level

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

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

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

Table of contents

Magtek MagneSafe V5 User manual

Popular Card Reader manuals by other brands