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.
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.
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).
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.
TABLE OF CONTENTS SECTION 1. SECURITY ............................................................................................................1 SECURITY LEVEL 2 ................................................................................................................................ 1 SECURITY LEVEL 3 ................................................................................................................................ 1 SECURITY LEVEL 4 ...................................................
Command Number ............................................................................................................................. 22 Data Length ........................................................................................................................................ 23 Data .................................................................................................................................................... 23 Result Code ...............................................
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) ............................................................
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.
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.
SECTION 2. COMMUNICATIONS The USB readers covered in this document conform to the USB specification revision 1.1 and to the Human Interface Device (HID) class specification version 1.1. The USB readers communicate to the host either as a vendor-defined HID device or as a HID Keyboard Emulation device. (Refer to Interface Type Property for information on how to change modes.) The latest versions of the Windows operating system come with standard Windows USB drivers that will support both modes.
MagneSafe V5 MAGNETIC STRIPE READER USAGE PAGE (HID) Magnetic Stripe Reader usage page 0xFF00: Usage ID (Hex) 1 20 21 22 23 28 29 2A 2B 30 31 32 33 38 39 40 42 46 47 48 49 4A 4B 4C 50 51 52 53 54 55 56 57 20 4 Usage Name Decoding reader device Track 1 decode status Track 2 decode status Track 3 decode status MagnePrint status Track 1 encrypted data length Track 2 encrypted data length Track 3 encrypted data length MagnePrint data length Track 1 encrypted data Track 2 encrypted data Track 3 encrypted data
Section 2. Communications REPORT DESCRIPTOR (HID) The Report Descriptor is made available to the hosting system during USB enumeration. The descriptor is shown here for completeness. Typically the hosting operating system will provide the ability to parse HID Reports based on the actual Report Descriptor, using the assigned Usage IDs. We strongly CAUTION the programmer to avoid depending on this specific structure as it may change in future versions.
MagneSafe V5 Item Report Size (8) Usage (MagnePrint data length) Report Count (1) Input (Data, Variable, Absolute, Bit Field) Usage (MagnePrint data) Report Count (128) Input (Data, Variable, Absolute, Buffered Bytes) 09 33 95 80 82 02 01 Usage (Device serial number) Report Count (16) Input (Data, Variable, Absolute, Buffered Bytes) 09 40 95 10 82 02 01 Usage (Reader Encryption Status) Report Count (2) Input (Data, Variable, Absolute, Buffered Bytes) 09 42 95 02 82 02 01 Usage (DUKPT Serial Number/Co
Section 2.
MagneSafe V5 Item Report Count (8) Input (Data, Variable, Absolute) Report Count (1) Report Size (8) Input (Constant) Report Count (5) Report Size (1) Usage Page (LEDs) Usage Minimum (1) Usage Maximum (5) Output (Data, Variable, Absolute) Report Count (1) Report Size (3) Output (Constant) Report Count (6) Report Size (8) Logical Minimum (0) Logical Maximum (101) Usage Page (Key Codes) Usage Minimum (0) Usage Maximum (101) Input (Data, Array) Logical Maximum (255) Usage Page (vendor defined (MSR)) Usage (co
Section 2. Communications Card data is only sent to the host on the Interrupt In pipe using an Input Report. The reader will send only one Input Report per card swipe. If the host requests data from the reader when no data is available, the reader will send a NAK to the host to indicate that it has nothing to send. When a card is swiped, the Input Report will be sent even if the data is not decodable. The following table shows how the input report is structured.
MagneSafe V5 Track 1 Decode Status Bits Value 7-1 Reserved 0 Error This is a one-byte value, which indicates the status of decoding track 1. Bit position zero indicates if there was an error decoding track 1 if the bit is set to one. If it is zero, then no error occurred. If a track has data on it that is not noise, and it is not decodable, then a decode error is indicated.
Section 2. Communications Track 3 Encrypted Data Length This one-byte value indicates the number of bytes in the Track 3 encrypted data field. The field is always a multiple of 8 bytes in length. This value will be zero if there was no data on the track or if there was an error decoding the track. Once the encrypted data is decrypted, there may be fewer bytes of decoded track data than indicated by this field. The number of bytes of decoded track data is indicated by the Track 3 Absolute Data Length field.
MagneSafe V5 may vary. Therefore, the Input Report always contains the maximum amount of bytes that can be encoded on the card and the number of valid bytes in each track is indicated by the Encrypted Data Length field. The encrypted data from each track is decoded and converted to ASCII, and then is encrypted. The encrypted track data includes all data starting with the start sentinel and ending with the end sentinel. The encryption begins with the first 8 bytes of the clear text track data.
Section 2. Communications MagnePrint Status This Binary field represents 32 bits of MagnePrint status information. Each character represents 4 bits (hexadecimal notation).
MagneSafe V5 Encrypted MagnePrint Data This 128 byte Binary field contains the MagnePrint data. Only the number of bytes specified in the MagnePrint data length field are valid. The least significant bit of the first byte of data in this field corresponds to the first bit of MagnePrint data. If the Enable/Disable MagnePrint property is set to disable MagnePrint, this field will not be sent. Device Serial Number This 16-byte ASCII field contains the device serial number.
Section 2. Communications masked; all other card types are either entirely masked or sent totally in the clear. There is a separate masking property for ISO/ABA cards and AAMVA cards. See the ISO Track Masking property and the AAMVA Track Masking property for more information. (Refer to Appendix E. Identifying ISO/ABA and AAMVA Cards for a description on how ISO/ABA and AAMVA cards are identified.
MagneSafe V5 For an AAMVA card, the DL/ID# is masked as follows: • The specified number of initial characters are sent unmasked. The specified number of trailing characters are sent unmasked. If Mod 10 correction is specified, all but one of the intermediate characters of the DL/ID#PAN are set to zero; one of them will be set such that last digit of the DL/ID# calculates an accurate Mod 10 check of the rest of the DL/ID# as transmitted.
Section 2. Communications MagneSafe Version Number This eight byte field contains the MagneSafe Version Number with at least one terminating byte of zero to make string manipulation convenient. See the MagneSafe Version Number Property for more information. Hashed Track 2 Data This twenty (20) byte field contains the hashed track 2 data with SHA1 algorithm.
MagneSafe V5 For the KB USB model, all data will be sent in upper case regardless of the state of the caps lock key on the keyboard. If no data is detected on a track then nothing will be transmitted for that track. If an error is detected on a track, the ASCII character “E” will be sent in place of the track data to indicate an error.
Section 2.
MagneSafe V5 Notes: (1) Encryption will only be performed when Encryption Enabled (bit 2) and Initial DUKPT key Injected (bit 1) are set. Otherwise, data that are normally encrypted are sent in the clear in ASCII HEX format; the DUKPT Serial Number/counter will not be sent.
Section 2. Communications Low Level Communications It is strongly recommended that application software developers become familiar with the HID USB specification before attempting to communicate directly with this reader. This document assumes that the reader is familiar with these specifications. These specifications can be downloaded free from www.usb.org. COMMANDS Most host applications do not need to send commands to the reader.
MagneSafe V5 Privileged Commands Some commands are, for security purposes, privileged. These commands are: 1. Set Property 2. Reset Device* 3. Set Key Map Item 4. Save Custom Key Map 5. Set Security Level† * The Reset Device command is usually not Privileged. The exception is during a sequence to Activate the Authenticated Mode. During this sequence the Reset Device command is Privileged to avoid a hacker using this sequence to exhaust DUKPT keys rendering the reader unusable.
Section 2. Communications Value 0x28 0x29 0x30 Command Number Power Down Command (Wireless USB Reader Only) Get Battery Status Command (Wireless USB Reader Only) Encrypt Bulk Data Description Powers down the MSR circuits (if running on battery turns reader off). Gets Charge Status of battery Encrypts Bulk Data Data Length This one-byte field contains the length of the valid data contained in the Data field.
MagneSafe V5 Get Property Request Data: Data Offset 0 Value Property ID Data Offset 0–n Value Property Value Get Property Response Data: Set Property Command Command number: Description: 0x01 The Set Property command sets a property in the reader. For security purposes, this command is privileged. When the Security Level is set to higher than 2 (see the Security section), this commands must be MACed in order to be accepted.
Section 2.
MagneSafe V5 Property ID HID KB Other mode mode 0x2F 0x2F PValue P47 Property ES Track 3 - 0x30 0x30 Send Encryption Counter 0x31 0x31 0x31 Mask Other Cards 0x32 0x32 0x32 0x33 0x33 0x33 0x34 0x34 0x34 0x38 - 0x3A 0x3A MSR Direction (Insert Reader only) Card Inserted (Insert Reader only) Send clear AAMVA card data flag HID SureSwipe Flag 0x53 Software ID 2 (wireless reader only) Inter-Key Delay Description End sentinel char for track 3 Enables/disables sending of Encryption Count
Section 2. Communications to the host using a USB cable, as is the case when doing firmware updates, this property will return the software ID of the wireless reader.
MagneSafe V5 Polling Interval Property (USB) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x02 Byte 1 byte Yes Yes 0x01 The value is a byte that represents the reader’s polling interval for the Interrupt In Endpoint. The value can be set in the range of 1 – 255 and has units of milliseconds. The polling interval tells the host how often to poll the reader for card data packets.
Section 2. Communications Device Serial Num Property Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x03 String 0 – 15 bytes Yes Yes (Once only) ASCII device serial number set when the reader is configured. The value is an ASCII string that represents the reader serial number. This string can be 0 – 15 bytes long. The value of this property, if any, will be sent to the host in the device serial number field of the USB input report when a card is swiped.
MagneSafe V5 Example Get MagneSafe Version Number property Request (Hex): Cmd Num 00 Data Len 01 Prp ID 04 Example Get MagneSafe Version Number property Response (Hex): Result Code 00 Data Len 03 Prp Value 56 30 35 Track ID Enable Property Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: id 0x05 Byte 1 byte Yes Yes 0x95 This property is defined as follows: 0 T3 T3 T2 T2 T1 T1 Id 0 – Decodes standard ISO/ABA cards only 1 – Decodes AAMVA and 7-bit car
Section 2. Communications Example Get Track ID Enable property Response (Hex): Result Code 00 Data Len 01 Prp Value 95 ISO Track Mask Property Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: • • • • 0x07 String 6 bytes Yes Yes ”04040Y” This property specifies the factors for masking data on ISO/ABA type cards: The first two bytes specify how many of the leading characters of the PAN should be sent unmasked. The range of masking is from “00” to “99.
MagneSafe V5 o The PAN will be masked according to the rules of this property (the Send Clear AAMVA Card Data property is ignored) o The character used for masking the PAN will be ‘0’ o All data after the PAN will be sent without masking • The sixth byte specifies whether the Mod 10 Correction should be applied to the DL/ID#. “Y” means Yes, the Mod 10 Correction will be applied. “N” means No, the Mod 10 will not be applied. (This option is only effective if the masking character is “0”.
Section 2.
MagneSafe V5 Bit 7 6 5 4 0 0 1 1 0 1 0 0 Description 3 0 1 0 1 2 0 0 0 0 1 1 1 1 1 0 0 1 1 0 0 1 1 0 0 1 0 1 0 1 0 1 Baud Rate 2400 Baud Rate 4800 Baud Rate 9600 Baud Rate 14400 Baud Rate 19200 Baud Rate 38400 Baud Rate 9600 Baud Rate 9600 No Parity (8 bit characters) Even Parity (7 bit characters) Odd Parity (7 bit characters) Mark (Parity = 1 all the time, 7 bit characters) 1 Stop Bit 2 Stop Bits Not used – set to zeroes This property is stored in non-volatile memory, so it will persist when
Section 2. Communications Bluetooth Disconnect Message Property (BulleT Only) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x0D String 7 bytes Yes Yes No string with a length of zero. This property specifies a string to be used as part of a Bluetooth Disconnect Message. The message is intended to give the connected host application a warning that the reader is disconnecting.
MagneSafe V5 Example Set Track Data Transmission Delay property Response (Hex): Result Code 00 Data Len 00 Data Example Get Track Data Transmission Delay property Request (Hex): Cmd Num 00 Data Len 01 Prp ID 0D Example Get Track Data Transmission Delay property Response (Hex): Result Code 00 Data Len 02 Prp Value 02 58 Stay Powered After Swipe Property (BulleT, Flash, Wireless USB) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x0E Byte 1 byte Yes Yes
Section 2. Communications This property should be the first property changed so that all other communications will not conflict with other pairs that may be in range. After this property is changed, the reader should be reset (see Command Number 2) before changing any other properties.
MagneSafe V5 Interface Type Property Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x10 Byte 1 byte Yes Yes 0x00 (HID) The value is a byte that represents the reader’s interface type. With USB readers, the value can be set to 0x00 for the HID interface or to 0x01 for the Keyboard Emulation interface. When the value is set to 0x00 (HID) the reader will correspond to the HID descriptions in this document.
Section 2.
MagneSafe V5 When minimizing key reports, the minimum number of key reports is sent to represent each character. When the ASCII-to-keypress conversion type property is set to ACTIVE KEYMAP, this consists of one key report per character (key down) if not sending the same key usage ID that was sent in the last key report sent or two key reports per character (one for the key down and one for the key up) when sending the same same key usage ID that was sent in the last key report sent.
Section 2. Communications This property is stored in non-volatile memory, so it will persist when the unit is power cycled. When this property is changed, the unit must be reset (see Command Number 2) or power cycled to have these changes take effect. Active Keymap Property (KB) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x16 Byte 1 byte Yes Yes 0x00 (United States) The value is a byte that represents the reader’s active key map.
MagneSafe V5 Example Get Active Keymap property Response (Hex): Result Code 00 Data Len 01 Prp Value 00 ASCII to Keypress Conversion Type Property (KB) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x17 Byte 1 byte Yes Yes 0x00 (keymap) The value is a byte that represents the reader’s ASCII-to-keypress conversion type.
Section 2.
MagneSafe V5 Keyboard SureSwipe Flag Property (KB, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x1A Byte 1 byte Yes Yes 0x01 This property is only effective in USB Keyboard and UART/RS-232 modes. If you wish to send SureSwipe data in USB HID mode, see the HID SURESWIPE FLAG PROPERTY. This property enables/disables SureSwipe emulation when the Security Level is 2 and the Interface Type is Keyboard.
Section 2. Communications This property is stored in non-volatile memory, so it will persist when the unit is power cycled. When this property is changed, the unit must be reset (see Command Number 2) or power cycled for these changes to take effect.
MagneSafe V5 ES JIS Type 2 Property Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x1D Byte 1 byte Yes Yes 0x7F ‘DEL’ This character is sent as the end sentinel for cards that are encoded in the JIS type 2 format. If the value is in the range 0 – 127 then the equivalent ASCII character will be sent. This property is stored in non-volatile memory, so it will persist when the unit is power cycled.
Section 2. Communications Post Card String Property (KB, BulleT, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x1F String 0 – 7 bytes Yes Yes No string with a length of zero. The value is an ASCII string that represents the reader’s post card string. This string can be 0 – 7 bytes long. This string is sent after all other card data. This property is stored in non-volatile memory, so it will persist when the unit is power cycled.
MagneSafe V5 Example Set Pre Track String property Response (Hex): Result Code 00 Data Len 00 Data Example Get Pre Track String property Request (Hex): Cmd Num 00 Data Len 01 Prp ID 20 Example Get Pre Track String property Response (Hex): Result Code 00 Data Len 03 Prp Value 31 32 33 Post Track String Property (KB, BulleT, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x21 String 0-7 bytes Yes Yes No string with a length of zero This str
Section 2. Communications Termination String Property (KB, BulleT, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x22 String 0-7 bytes Yes Yes 0x0D (carriage return) This string is sent after the all the data for a transaction. The string can be 0 – 7 bytes long. If the value is 0 no character is sent. This property is stored in non-volatile memory, so it will persist when the unit is power cycled.
MagneSafe V5 SS Track 2 ISO ABA Property (KB, BulleT, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x25 Byte 1 byte Yes Yes 0x3B ‘;’ This character is sent as the track 2 start sentinel for cards that have track 2 encoded in ISO/ABA format. If the value is 0 no character is sent. If the value is in the range 1 – 127 then the equivalent ASCII character will be sent.
Section 2. Communications SS Track 2 7bits Property (KB, BulleT, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x28 Byte 1 byte Yes Yes 0x40 (‘@’) This character is sent as the track 2 start sentinel for cards that have track 2 encoded in 7 bits per character format. If the value is 0 no character is sent. If the value is in the range 1 – 127 then the equivalent ASCII character will be sent.
MagneSafe V5 This property is stored in non-volatile memory, so it will persist when the unit is power cycled. When this property is changed, the unit must be reset (see Command Number 2) or power cycled to have these changes take effect.
Section 2. Communications ES Track 2 Property (KB, BulleT, UART, RS-232) Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x2E Byte 1 byte Yes Yes 0xFF (use ES property) This character is sent as the end sentinel for track 2 with any format. If the value is 0 no character is sent. If the value is in the range 1 – 127 then the equivalent ASCII character will be sent. If the value is 0xFF then the value of the ES property will be used instead of this property.
MagneSafe V5 NOTE: If this property is set to 0x01 and the Format Code is currently “0001”, the Format Code will be changed to “0002”. This property is stored in non-volatile memory, so it will persist when the unit is power cycled. When this property is changed, the unit must be reset (see Command Number 2) or power cycled to have these changes take effect.
Section 2. Communications This property is stored in non-volatile memory, so it will persist when the unit is power cycled. When this property is changed, the unit must be reset (see Command Number 2) or power cycled to have these changes take effect.
MagneSafe V5 Send Clear AAMVA Card Data Property Property ID: Property Type: Length: Get Property: Set Property: Default Value: Description: 0x34 Byte 1 byte Yes Yes 0x00 This property is used to control how to send out AAMVA card data when the security level is above 2. This property is stored in non-volatile memory, so it will persist when the unit is power cycled. When this property is changed, the unit must be reset (see Command Number 2) or power cycled to have these changes take effect.
Section 2. Communications This property controls whether, when the reader is configured with Interface Type HID and at Security Level 2, the reader functions as described in this manual or as described in 99875191 (USB HID SURESWIPE & USB HID SWIPE READER TECHNICAL REFERENCE MANUAL). When this property is set to 0x00, the reader functions as described in this document.
MagneSafe V5 wireless reader. To get the software ID from the dongle use the “SOFTWARE ID” property.
Section 2. Communications Example Set Inter-Key Delay property Response (Hex): Result Code 00 Data Len 00 Data Example Get Inter-Key Delay property Request (Hex): Cmd Num 00 Data Len 01 Prp ID 53 Example Get Inter-Key Delay property Response (Hex): Result Code 00 Data Len 01 Data 0C COMMAND LIST The following commands are available for use with the readers. Reset Device Command Command number: Description: 0x02 This command is used to reset the reader.
MagneSafe V5 Example Reset Device Response (Hex): Result Code 00 Data Len 00 Data Get Keymap Item Command (KB) Command number: Description: 0x03 This command is used to get a key map item from the active key map. The active key map is determined by the active key map property. Data from a magnetic stripe card is a sequence of ASCII characters. These ASCII characters are mapped to key strokes and these key strokes are sent to the host to represent the ASCII character.
Section 2. Communications Response Data: Offset 0 Field Name Key Usage ID 1 Key Modifier Byte Result codes: Description The value of the USB key usage ID that is mapped to the given ASCII value. For example, for the United States keyboard map, usage ID 56 (0x38) (keyboard / and ?) is mapped to ASCII character ‘?’. The value of the USB key modifier byte that is mapped to the given ASCII value.
MagneSafe V5 Starting with the firmware release with software ID 21042812F01, when both the key usage ID and the key modifier byte are set to 0xFF for a given ASCII value, the ALT ASCII code is sent instead of the key map values. The ALT ASCII code is a key press combination consisting of the decimal value of the ASCII character combined with the ALT key modifier.
Section 2. Communications Save Custom Keymap Command (KB) Command number: Description: 0x05 This command is used to save the active key map as the custom key map in non volatile memory. The active key map is determined by the active key map property. Once a key map item is modified, the changes take affect immediately. However, the changes will be lost if the reader is reset or power cycled. To make the changes permanent, the save custom key map command must be issued.
MagneSafe V5 Example Get DUKPT KSN and Counter Request (Hex): Cmd Num 09 Data Len 00 Data None Example Get DUKPT KSN and Counter Response (Hex): Result Code 00 Data Len 0A Data FFFF 9876 5432 10E0 0001 Set Session ID Command Command number: Description: 0x0A This command is used to set the current Session ID. The new Session ID stays in effect until one of the following ocurrs: 1. Another Set Session ID command is received. 2. The reader is powered down. 3. The reader is put into Suspend mode.
Section 2. Communications Activate Authenticated Mode Command Command number: Description: 0x10 This command is used to Activate the Authenticated Mode. When set to Security Level 4, this reader will not transmit card data unless it is in the Authenticated Mode. The Authenticated Mode may only be entered by this command. The application specifies a PreAuthentication Time Limit. This is the maximum number of seconds the reader will wait for the Activation Challenge Reply Command before timing out.
MagneSafe V5 Response Data: Offset 0 Field Name Current Key Serial Number 10 Challenge 1 18 Challenge 2 Result codes: 0x00 0x03 0x05 0x07 0x80 Description This eighty-bit field includes the Initial Key Serial Number in the leftmost 59 bits and a value for the Encryption Counter in the rightmost 21 bits. This eight byte challenge may be used later in an Activation Challenge Reply command shown below, and to authenticate the reader as mentioned above.
Section 2. Communications If the reader decrypts the CR response correctly the Activate Authenticated Mode has succeeded. If the reader can not decrypt the CR command correctly the Activate Authenticated Mode has failed, the DUKPT KSN advances.
MagneSafe V5 behavior is intended to discourage denial of service attacks. Exiting the Authenticated Mode by timeout or card swipe always increments the KSN, exiting Authenticated Mode by the Deactivate Authenticated Mode command may increment the KSN.
Section 2. Communications Data Structure: Request Data: None Response Data: The first byte specifies the current state as follows: Value 0x00 Name WaitActAuth 0x01 WaitActRply 0x02 0x03 WaitSwipe WaitDelay Current Reader State Meaning Waiting for Activate Authenticated Mode. The reader requires Authentication before swipes are accepted. Waiting for Activation Challenge Reply. Activation has been started, the reader is waiting for the Activation Challenge Reply command. Waiting for Swipe.
MagneSafe V5 Set Security Level Command Command number: Description: 0x15 This command is used to set the Security Level (see Section 1). The Security Level can be set higher, but never lower. There are two versions of this command, the first one is used to retrieve the current Security Level and does not require MACing. The second one is used to set the Security Level and requires Security/MACing.
Section 2. Communications Get Transaction Count Command (Flash Reader Only) Command number: Description: 0x16 This command is used to get the count of stored transactions (card swipes) currently stored in the reader. It will return one byte giving the count of stored transactions.
MagneSafe V5 Example Response Read Oldest Transaction (Hex): Result Code 00 Data Len 00 Data Erase Oldest Transaction Command (Flash Reader Only) Command number: Description: 0x18 This command is used to erase the oldest transaction (card swipe) stored in the reader. It has no request and no response data. The response indicates whether or not a transaction was erased. If there are no stored transactions, the request will fail indicating no stored transactions.
Section 2. Communications Request Data: None Response Data: Offset 0 Field Name Device Serial # 16 Actual Encryption Counter Description 16 bytes, if DSN is shorter than 15 bytes, left justify and fill with binary zeroes. At least one byte (usually the last one) must contain binary zero. This three byte field returns the current value of the Encryption Counter.
MagneSafe V5 Get Battery Status Command (Wireless USB Reader Only) Command number: Description: 0x29 This command is used to get the status of the battery. Data structure: Request Data: None Response Data: Offset 0 Result codes: Field Name Battery Status Description Value of 0x00 indicates battery charge is low; battery should be charged before further use. Value of 0x01 indicates battery charge is sufficient for normal use.
Section 2. Communications DSN – Device Serial Number, this data field will always be fixed at 16 bytes. If the serial number is less than 15 bytes, it will be left justified. The 16th byte will always be set to NULL. Cryptogram – Encrypted data, the length of which is always a multiple of 8, this field can be maximum of 120 characters. Result codes: 0x00 – success 0x02 – Bad Parameters, the Data Len is not supported 0x07 – Security Level < 2, MSCI CMUT was incorrect.
MagneSafe V5 76
SECTION 3. DEMO PROGRAM The demo program, which is written in Visual Basic, can be used to do the following: • Send command requests to the reader and view the command responses. • Guide application developers in their application development by providing examples, in source code, of how to properly communicate with the reader using the standard Windows APIs. • Read cards from the reader and view the card data (HID mode only).
MagneSafe V5 • • • • • • • To send commands to the reader, click the Send Commands tab (if not already selected). Enter a command in the Message edit box. All data entered should be in hexadecimal bytes with a space between each byte. Enter the command number followed by the command data if there is any. The application will automatically calculate and send the command data length for you if the Auto Add Length box is checked.
APPENDIX A. KEYBOARD USAGE ID DEFINITIONS This appendix is from the following document found on www.usb.org: Universal Serial Bus HID Usage Tables, Version 1.12 and specifically for this manual, Section 10, Keyboard/Keypad Page (0x07). KEYBOARD/KEYPAD PAGE (0X07) This section is the Usage Page for key codes to be used in implementing a USB keyboard. A Boot Keyboard (84-, 101- or 104-key) should at a minimum support all associated usage codes as indicated in the “Boot” column below.
MagneSafe V5 0C 0D 0E 0F 10 Keyboard i and I Keyboard j and J Keyboard k and K Keyboard l and L Keyboard m and M 17 18 19 20 21 22 11 12 13 14 15 16 Keyboard n and N 4 Keyboard o and O 4 Keyboard p and P 4 Keyboard q and Q Keyboard r and R 4 Keyboard s and S 23 24 25 26 27 28 17 18 19 1A 1B 1C Keyboard t and T Keyboard u and U Keyboard v and V 4 Keyboard w and W 4 Keyboard x and X 4 Keyboard y and Y 29 30 31 32 33 34 1D 1E 1F 20 21 22 Keyboard z and Z 4 Keyboard 1 and ! 4 Keyboard 2 and ! 4 Keybo
Appendix A. Keyboard Usage 52 53 54 55 56 34 35 36 37 38 Keyboard ‘ and “ 4 Keyboard Grave Accent and Tilde 4 Keyboard, and < 4 Keyboard.
MagneSafe V5 Ref: Typical AT-101 Position 92 97 102 91 96 5C 5D 5E 5F 60 Keypad 4 and Left Arrow Keypad 4 and Left Arrow Keypad 4 and Left Arrow Keypad 7 and Home Keypad 8 and Up Arrow 97 98 99 100 101 102 61 62 63 64 65 66 Keypad 9 and PageUp Keypad 0 and Insert Keypad .
132 133 134 135 136 84 85 86 87 88 Keyboard Locking Scroll Lock 27 Keypad Comma 29 Keypad Equal Sign 15-28 Keyboard International1 16 Keyboard International2 137 138 139 140 141 142 89 8A 8B 8C 8D 8E Keyboard International3 18 Keyboard International4 19 Keyboard International5 20 Keyboard International6 21 Keyboard International7 22 Keyboard International8 143 144 145 146 147 148 8F 90 91 92 93 94 Keyboard International9 25 Keyboard Lang1 26 Keyboard Lang2 30 Keyboard Lang3 31 Keyboard Lang4 32 Keyb
182 183 184 185 186 B6 B7 B8 B9 BA Keypad ( Keypad ) Keypad { Keypad} Keypad Tab 187 188 189 190 191 192 BB BC BD BE BF C0 Keypad Backspace Keypad A Keypad B Keypad C Keypad D Keypad E 193 194 195 196 197 198 C1 C2 C3 C4 C5 C6 Keypad F Keypad XOR Keypad ^ Keypad % Keypad < Keypad > 199 200 201 202 203 204 C7 C8 C9 CA CB CC Keypad & Keypad && Keypad | Keypad || Keypad : Keypad # 205 206 207 208 209 210 CD CE CF D0 D1 D2 Keypad Space Keypad @ Keypad ! Keypad Memory Store Keypad Memory Recall Key
222-223 224 225 226 227 DE-DF E0 E1 E2 E3 228 229 230 231 232 – 65535 E4 E5 E6 E7 E8-FFFF Ref: Typical AT-101 Position UNIX Usage ID (Hex) Mac Usage ID (Dec) PC-AT Appendix A. Keyboard Usage Reserved Keyboard LeftControl Keyboard LeftShift Keyboard LeftA;t 10;23 Keyboard Left GUI 58 44 60 127 √ √ √ √ √ √ √ √ √ √ √ √ Keyboard RightControl Keyboard RightShift Keyboard RightAlt 10;24 Keyboard Right GUI 64 57 62 128 √ √ √ √ √ √ √ √ √ √ √ √ Usage Name Boot Reserved Footnotes 1.
MagneSafe V5 29. 30. 31. 32. Used on AS/400 keyboards. Defines the Katakana key for Japanese USB word-processing keyboards. Defines the Hiragana key for Japanese USB word-processing keyboards. Usage 0x94 (Keyboard LANG5) “Defines the Zenkaku/Hankaku key for Japanese USB word-processing keyboards. 33. The symbol displayed will depend on the current locale settings of the operating system. For example, the US thousands separator would be a comma, and the decimal separator would be a period. 34.
APPENDIX B. MODIFIER BYTE DEFINITIONS This appendix is from the following document found on www.usb.org: Device Class Definition for Human Interface Devices (HID) Version 1.11, and specifically for this manual, Section 8.3 Report Format for Array Items. The modifier byte is defined as follows: Table B-1.
MagneSafe V5 88
APPENDIX C. GUIDE ON DECRYPTING DATA The key that was used to encrypt each data block can be determined by using the Key Serial Number field along with the Base Derivation Key associated with this reader. The resulting DUKPT key, as described in ANS X9.24 Part 1, is the key which was used to encrypt the data. (The key is described as the PIN key in the standard but since there are no PINs being used in this application, the derived key is used.
MagneSafe V5 90
APPENDIX D. COMMAND EXAMPLES This Appendix gives examples of command sequences and cryptographic operations. The intent is to clarify any ambiguities the user might find in the body of the document. Each example shows a sequence as it actually runs, thus the user can check algorithms against the examples to assure they are computing correctly. Example 1: Configuring a reader before encryption is enabled (Security Level 2).
MagneSafe V5 01 02 05 85 Request Response ; Set to read only Tracks 1 & 2 : CMND=01, LEN=02, DATA=05 85 : RC= 00, LEN=00, DATA= 00 01 07 Request Response ; Get current ISO Track Mask : CMND=00, LEN=01, DATA=07 : RC= 00, LEN=06, DATA=30 34 30 34 30 59 01 07 07 303430342A4E ; Set ISO Track Mask "0404*N" (uses * as mask char) Request : CMND=01, LEN=07, DATA=07 30 34 30 34 2A 4E Response : RC= 00, LEN=00, DATA= 00 01 0A Request Response ; Get Max Packet Size : CMND=00, LEN=01, DATA=0A : RC= 00, LEN=01, DAT
Appendix D.
MagneSafe V5 01 02 02 02 Request Response ; Set Polling Interval to 2 ms : CMND=01, LEN=02, DATA=02 02 : RC= 00, LEN=00, DATA= 00 01 03 Request Response ; Get current Device Serial Number : CMND=00, LEN=01, DATA=03 : RC= 00, LEN=00, DATA= 01 08 03 42303030373935 ; Set DSN to "B000795" Request : CMND=01, LEN=08, DATA=03 42 30 30 30 37 39 35 Response : RC= 00, LEN=00, DATA= 00 01 05 Request Response ; Get current Track ID Enable : CMND=00, LEN=01, DATA=05 : RC= 00, LEN=01, DATA=95 01 02 05 85 Request R
Appendix D.
MagneSafe V5 00 01 19 Request Response ; Get current CRC Flags (should return 03) : CMND=00, LEN=01, DATA=19 : RC= 00, LEN=01, DATA=03 00 01 1A Request Response ; Get Current SureSwipe Flag (should return 00, if Set was done) : CMND=00, LEN=01, DATA=1A : RC= 00, LEN=01, DATA=01 00 01 1E Request Response ; Get current Pre Card String (should return "CRDTST") : CMND=00, LEN=01, DATA=1E : RC= 00, LEN=06, DATA=43 52 44 54 53 54 00 01 1F Request Response ; Get current Post Card String (should return "CRD
Appendix D. Command Examples |010002AC501724CC063E08E2C52B53793DD53167753CDC3CE8EBC5C3555E30B68B73E4DB8912E6372CA772E 723EFEAADC02F02048C76 |B000795 |0000000000000000 | |DB3E | |1234 TXEND Example 3: HID reader card swipe in Security Level 2: This example shows the data received in a HID report for a reader at Security Level 2.
MagneSafe V5 840 00 00 00 00 00 00 00 00 00 00 00 00 3C 25 1F 36 According to the USB MagneSafe Swipe Reader Technical Reference Manual the HID report is broken down like this: Offset 0 1 2 3 4 5 6 7 - 118 119 - 230 231 - 342 343 344 - 347 348 349 - 476 477 - 492 493-494 495 - 504 505 506 507 508 - 619 620 - 731 732 - 843 844 - 851 852 853 854 855 Usage Name Track 1 decode status Track 2 decode status Track 3 decode status Track 1 encrypted data length Track 2 encrypted data length Track 3 encrypted data
Appendix D.
MagneSafe V5 844 - 851 852 853 854 855 00 00 00 00 00 00 00 00 00 00 00 00 Encrypted Session ID (user didn't load, all zeroes) 00 00 00 00 00 00 00 00 Track 1 Absolute data length (same as above) 3C Track 2 Absolute data length (same as above) 25 Track 3 Absolute data length (same as above) 1F MagnePrint Absolute data length (same as above) 36 Example 4: Keyboard or Serial reader card swipe in Security Level 2, SureSwipe Mode: This example shows the data received from a KB swipe for a reader at Security
Appendix D.
MagneSafe V5 |0000000000000000 | |6F36 | |1000 Note: The Device Serial Number field is empty because the DSN has not been set. Note: The MagnePrint Status, the MagnePrint Data, the DUKPT serial number/counter and Encrypted CRC fields are empty because this reader is at Security Level 2 (encryption not enabled).
Appendix D.
MagneSafe V5 Response : RC= 00, LEN=0A, DATA=FF FF 98 76 54 32 10 E0 00 02 15 00 Request Response ; Get current Security Level (Should be 04) : CMND=15, LEN=00, DATA= : RC= 00, LEN=01, DATA=04 Example 8: Changing from Security Level 3 to Security Level 4: ; This script demonstrates changing from Security Level 3 to Security Level 4. ; It assumes the reader is at Security Level 3 with the ANSI X9.24 Example ; key loaded and the KSN counter set to 2.
Appendix D. Command Examples Example 9: Configuring a reader after encryption is enabled (Security Level 3 or 4). In this example the reader is in Keyboard Mode: ; This script demonstrates configuration commands for KB mode. ; It assumes the reader is at Security Level 3 or 4 and that the KSN counter ; is at 0x10.
MagneSafe V5 00 01 20 Request Response ; Get current Pre Track String : CMND=00, LEN=01, DATA=20 : RC= 00, LEN=00, DATA= ; Form MAC for Set Property command ; Message to be sent is: 01 05 20 nnnnnnnn (nnnnnnnn is the MAC) ; Message to be MACd is: 0105200000000000 ; This is the simplest MAC, simply TDES encrypt the message to be MACd with ; the MAC Key: ; 0105200000000000 MACd with 9CF640F279C251E6 15F725EEEAC234AF ; gets 442A09E6588BBF04 ; MAC is first four bytes: 442A09E6 01 05 20 442A09E6 ; Set to "" R
Appendix D.
MagneSafe V5 |------- Current KSN -------| |---- Challenge 1 ---| |---- Challenge 2 ----| Response : RC= 00, LEN=1A, DATA=FF FF 98 76 54 32 10 E0 00 03 BE 5C 98 35 17 7E 45 2A A7 2D 2D B2 36 BF 29 D2 ; Challenge 1 Encrypted: BE5C9835177E452A ; Challenge 2 Encrypted: A72D2DB236BF29D2 ; Note that the KSN now ends with a counter of 3! ; Decrypt Challenge 1 using variant of Current Encryption Key ; (Current Encryption Key XOR with F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0) ; ; Current Key 0DF3D9422ACA561A 47676D07AD6BAD
Appendix D. Command Examples ; Build a Deactivate Authenticated Mode command (cmd, len, cryptogram) ; 12 08 XXXXXXXXXXXXXXXX ; ; The clear text input for the cryptogram is composed of the first seven bytes ; of the decrypted Challenge 2 followed by one byte specifying whether to ; increment the DUKPT KSN or not (00 = no increment, 01 = increment).
MagneSafe V5 480 500 520 540 560 580 600 620 640 660 680 700 720 740 760 780 800 820 840 00 32 30 20 30 00 00 3B 30 00 00 00 00 30 30 00 00 00 00 00 10 30 20 30 00 00 35 34 00 00 00 00 35 30 00 00 00 00 00 E0 37 20 30 00 00 34 30 00 00 00 00 30 3F 00 00 00 00 00 00 31 5E 30 00 00 35 30 00 00 00 00 30 00 00 00 00 00 00 08 38 30 30 00 00 32 30 00 00 00 00 30 00 00 00 00 21 00 3C 39 38 30 00 00 30 30 00 00 00 00 30 00 00 00 00 68 00 25 5E 30 30 00 00 30 30 00 00 00 00 34 00 00 00 00 5F 00 1F 48 34 3F 0
Appendix D.
MagneSafe V5 620 - 731 732 - 843 844 - 851 852 853 854 855 25 42 35 34 35 32 30 30 30 30 30 4F 47 41 4E 2F 50 41 55 4C 20 20 30 30 30 30 30 30 30 30 30 30 30 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 Track 2 Masked data 3B 35 34 35 32 30 30 30 30 30 30 30 34 30 30 30 30 30 30 30 30 30 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 Track 3 Masked data 3B 35 31 36 3
Appendix D.
MagneSafe V5 Ordering the decrypted blocks 1st to last we get: HEX ASCII 2542353435323330 %B545230 3035353132323731 05512271 38395E484F47414E 89^HOGAN 2F5041554C202020 /PAUL 2020205E30383034 ^0804 3332313030303030 32100000 3030373235303030 00725000 3030303F00000000 000? We can ignore the last four bytes because the Track 1 Absolute Length field cites only 60 characters. ASCII string "%B5452300551227189^HOGAN/PAUL ^08043210000000725000000?" This is an accurate decryption of the track.
Appendix D.
MagneSafe V5 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 As MagnePrint Data Length cites 56 bytes only, we can eliminate the trailing blocks: Block # 1 4703576BC5C2CB20 2 BC04C68B5CE1972A 3 E89E087B1C4D47D5 4 D0E31706106903E6 5 0B82030792690A57 6 1DB02D0A88855A35 7 ABB5549798006B42 Appendix C tells us to decrypt the last block: ABB5549798006B42 TDES Dec with 27F66D5244FF621E AA6F6120EDEB427F gets D3B7EDDFD3045A35 XOR 1DB02D0A88855A35 gets CE07C0D55B810000 (decrypted last block) Continue on in reverse bl
Appendix D. Command Examples BEA104C4EF584ED5 CE07C0D55B810000 We can ignore the last four bytes because the MagnePrint Data Absolute Length field cites only 54 characters. 01000184EA10B939408C872A5C513C90C78B57A6F3FAA663CE0678B879D0D78B7FADBCE8591AE7E4BEA104C4 EF584ED5CE07C0D55B81 This is an accurate decryption of the MagnePrint data.
MagneSafe V5 [P35] [P35] [P35] [P35] [P35] [P34] [Encrypted Session ID] [DUKPT serial number/counter] [Clear Text CRC] [Encrypted CRC] [Format Code] Each of the Pxx elements has the default value in this configuration, thus we can reinterpret the format as: %[Tk1 Masked Data]? ;[Tk2 Masked Data]? +[Tk3 Masked Data]? |[Reader Encryption Status] |[Tk1 Encrypted Data (including TK1 SS and ES)] |[Tk2 Encrypted Data (including TK2 SS and ES)] |[Tk3 Encrypted Data (including TK3 SS and ES)] |[MagnePrint Status]
Appendix D. Command Examples Note that all other fields are represented as Hexadecimal data, that is, two ASCII characters together give the value of a single byte. The data is coherent structurally, let's work on decryption. First, we note the KSN = FFFF9876543210E00008, counter is 8. For the standard ANSI key example, counter 8 gets us the following Encryption Key: 27F66D5244FF621E AA6F6120EDEB427F There 1. 2. 3. 4. 5.
MagneSafe V5 26D9182EC11353C0 TDES Dec with 27F66D5244FF621E AA6F6120EDEB427F gets BF110311E7D5453A XOR 87285D59A8920474 gets 38395E484F47414E (decrypted block 3) Continue on in reverse block order: 87285D59A8920474 TDES Dec with 27F66D5244FF621E AA6F6120EDEB427F gets F2692820A5E12B9B XOR C25C1D1197D31CAA gets 3035353132323731 (decrypted block 2) Continue on in reverse block order: C25C1D1197D31CAA TDES Dec with 27F66D5244FF621E AA6F6120EDEB427F gets 2542353435323330 (decrypted block 1) Ordering the decrypt
Appendix D.
MagneSafe V5 We can ignore the last byte because it is hex 00 and falls after the End Sentinel. ASCII string "+5163499080020443=000000000000? " This is an accurate decryption of the track.
Appendix D. Command Examples 010002D4B69CD2C0 C7617D0463316E85 3F9CB00FE2C5A355 6E9CE5A9B2E6DB89 14A6372CA7736703 6EFAADC02F02C4FB 76C6CFD8A59C0000 We can ignore the last two bytes because we know the MagnePrint data is actually 54 bytes long. 010002D4B69CD2C0C7617D0463316E853F9CB00FE2C5A3556E9CE5A9B2E6DB8914A6372C A77367036EFAADC02F02C4FB76C6CFD8A59C0000 This is an accurate decryption of the MagnePrint data.
MagneSafe V5 124
APPENDIX E. IDENTIFYING ISO/ABA AND AAMVA CARDS ISO/ABA FINANCIAL CARDS 1. If low level decoding algorithm finds data for available tracks to be in the ISO format particular to each track, the card is classified as ISO. In order to be considered for ISO Financial masking, the card must first be classed as ISO. 2. In order for any track on a card to be considered for ISO/ABA masking, the card must be classified as ISO by the low level decoding algorithm. 3.
MagneSafe V5 AAMVA DRIVER LICENSES 1. If the card reader reads three tracks of data and Track 1 is formatted per ISO Track 1 rules, Track 2 is formatted per ISO Track 2 rules, and Track 3 is formatted per ISO Track 1 rules, the card is considered to be an AAMVA card. Some MagTek readers do not support reading of Track 3, so this rule will not apply on such readers. 2.
APPENDIX F. LIST OF PROPERTIES This list shows all of the properties that are supported among the MagneSafe reader families. The properties associated with a particular MagneSafe model are indicated with a check mark. The default setting for each property is indicated.
MagneSafe V5 Properties 0x14 Track Data Send Flags 0x15 MP Flags 0x16 Active Keymap 0x17 ASCII To Keypress Conversion Type 0x19 CRC Flag 0x1A Keyboard SureSwipe Flag 0x1B Decode Enable Property (JIS) 0x1C SS JIS TYPE 2 0x1D ES JIS TYPE 2 0x1E Pre Card String 0x1F Post Card String 0x20 Pre Track String 0x21 Post Track String 0x22 Termination String 0x23 Field Separator 0x24 SS TK1 ISO ABA 0x25 SS TK2 ISO ABA 0x26 SS TK3 ISO ABA 0x27 SS TK3 AAMVA 0x28 SS TK2 7BITS 0x29 SS TK3 7BITS 0x2B End Sentinel 0x2C For
Appendix F. List of Properties Properties 0x30 Send Current Encryption Counter 0x31 Mask Other Cards 0x32 MSR Read Direction 0x33 Card Inserted 0x34 Send Clear AAMVA Card Data Flag 0x36 Enable MagneSafe 2.0 format 0x37 MagneSafe 2.0 Decode Status 0x38 HID SureSwipe Flag 0x39 MagneSafe 2.0 Track Handling 0x3A Software ID 2 0x3B MagneSafe 2.
MagneSafe V5 Properties 0x44 Hardware Error Message 0x45 Blank Card Message 0x46 Transaction Threshold Exhausted Message 0x47 Bad Read Message 0x48 Good Read Message 0x49 Authenticated Message 0x4A Waiting Authentication Message 0x4B Transaction Validation “Rejected” text 0x50 BundleSeedIDString 0x51 SDKProtocolToken 0x53 Inter-Key Delay 0xF0 Amber Balance – Green Component 0xF1 Amber Balance – Red Component 130 Default Dynamag HID KB Dynamo LCD BulleT SPP BulleT KB Flash iDynamo U-Finity I
