Multi-byte values like command and data lengths are always big-endian.
Message Types
Data
Data Messages are formed in response to a cardholder event such as swiping a card or pressing a button. These messages are formatted as a block of ASCII text and compatible with all interfaces.
Commands
Commands consist of a 2-byte command, a 2-byte Parameter Data Length, and Parameter Data as needed.
Table - Command Structure
Command
Parameter Data Len
Parameter Data
Responses consist of a 2-byte return code, a 2-byte response data length, and response data as needed.
Notifications consist of a 2-byte notification code, a 2-byte notification data length, and notification data when needed. They are sent asynchronously due to device events. They can also be used as delayed responses for commands that take longer to process.
Sentinels
Data for each card track is typically bracketed by a start and end sentinel. The sentinel characters can be changed by setting properties. The start sentinel can also indicate what format was used to encode the track.
[SS] Track Data [ES]
If a property value is set to 0, then no character will be sent.
Masking
The PAN field must always be partially masked. The device can be configured to expose the 0-8 leading characters and 0-4 trailing characters. The 8-digit limit for leading characters automatically drops to 6 for cards where the PAN length is less than 16 (e.g. American Express).
Properties 0x07 and 0x08 are used to configure PAN masking.
Data messages include DUKPT KEY information fields so the host can derive the correct decryption or MAC key.
Example:
Data messages will always be made up of ASCII text characters regardless of the interface for compatibility purposes. Text is used to address limitations when using keyboard emulation.
Any Field with no value will be empty between separator characters.
The device transmits an M002 message with three new data fields: Encrypted SCDE, KSN (SCDE) and DUKPT Key Info (SCDE) to the host instead of an M001 message when the following four conditions are satisfied. Selectable Card Data Encryption is enabled through Property 0x78.
Any of the defined property 0x78 bits are set to 1 (enabled),
Card Encode Type is ISO (a.k.a. financial card),
SCDE DUKPT key is injected or present in the device, and
If any one of the four conditions is not met, an M001 message will be returned to the host instead of an M002 message.
The encrypted SCDE field in the M002 message, [Encrypted SCDE], includes six data fields, field_1 ~ field_6. The six data fields are placed in a buffer prior to encryption. The selectable card data element starts with a field separator (FS) followed by a data field, and the last field separator is appended following the sixth data field (field_6) as shown below (total seven FS characters). The field separator used in the SCDE is the same FS used in the M001 or M002 message, which may be changed using Property 0x23.
Each data field in the SCDE is defined as follows.
The SCDE DUKPT key (DKPTM1F) is used to encrypt the six data fields (| field_1 | field_2 | field_3 | field_4 | field_5 | field_6 |)only. No other keys should be used for the SCDE.
The encrypted SCDE field in the M002 message is an encrypted blob holding six card data fields selected with Property 0x78 bits. If a defined bit is set to zero, the corresponding data field will be empty in the clear-text SCDE. The clear-text SCDE including enabled data fields will be encrypted with an SCDE DUKPT future key.
When all defined bits in the property 0x78 are set to zeros, the encrypted SCDE is disabled. As a result, the M001 message should be transmitted to the host instead of the M002 message.
This device uses configurable properties to define characters that get inserted into the message for parsing purposes. The simplest option is to have characters for start of message (SOM), end of message (EOM), and field separation (FS) only.
This is the message format for Qwantum cards, or for any card when Qwantum Mode is on.
This message is used when the device sends out encrypted data from the Secure Buffer.
This message is used when the device sends out when Qwantum Secure Data is empty.
T2ISO
Tk2 SS if ISO
1
0x25
0x3B ‘;’
T3ISO
Tk3 SS if ISO
1
0x26
0x2B ‘+’
T3AMV
Tk3 SS if AAMVA
1
0x27
0x23 ‘#’
T27BT
Tk2 SS if 7bit
1
0x28
0x40 ‘@’
T37BT
Tk3 SS if 7bit
1
0x29
0x26 ‘&’
ES
End sentinel
1
0x2B
0x3F ‘?’
ISO Only:
Expiration Date masking
Always fully unmasked (4 digits).
Always masked with 5th character from Property 0x07.
ISO Only:
Service Code masking
Can be enabled or disabled using Property 0x6E (3 digits).
Always masked with 5th character from Property 0x07.
AAMVA Only:
Expiration Date and Birth Date
Always fully unmasked (12 digits).
Always masked with 5th character from Property 0x08.
Discretionary Data masking
Unmasked if error. Otherwise, masked with 5th character from Property 0x07 or 0x08.
Unmasked if error. Otherwise, masked with 5th character from Property 0x07 or 0x08.
2
1
For Data Item
0x01 – RFU
0x01 – Message MAC
0x02 – MSR Data
0x03 – MP Token
0x04 – Qwantum Token
0x05 – Qwantum Data
3
1
Using Mode/Operation
0x00 – RFU
0x01 – ENC-CBC-0
0x02 – ENC-CBC-SECURE
0x03 – ENC-CTR
0x10 – MAC-CBC-0
0x11 – CMAC
0x12 – HMAC
0x13 – GMAC
4
1
Derived Key Algorithm
0x00 – 2-key TDEA
0x01 – 3-key TDEA
0x02 – AES 128-bit
0x03 – AES 192 bit
0x04 – AES 256 bit
0x05 – HMAC
5-6
2
Generated Key Length (bits)
0x0100 – 256 bits
0x0080 – 128 bits
7-8
2
Derived Key Usage
0x2002 – MAC, both ways
0x3002 – Data Encryption, both ways
0xFF00 – Legacy PIN Variant
0xFF01 – Legacy MAC, both ways
0xFF02 – Legacy Data Encryption
AES DUKPT: Use “Legacy: FFnn”, which means “shift FF left nn bytes”.
Track 1 Masked Data
Clear
ASCII
var
Per masking configuration
Track 2 Masked Data
Clear
ASCII
var
Per masking configuration
Track 3 Masked Data
Clear
ASCII
var
Per masking configuration
Track 1 Data
Encrypt
HEX
var
Encrypted with MSR key.
Track 2 Data
Encrypt
HEX
var
Encrypted with MSR key.
Track 3 Data
Encrypt
HEX
var
Encrypted with MSR key.
MP Status Code
Clear
HEX
8
MP Token
Encrypt
HEX
var
Encrypted with MSR or MP key as configured (see Property 0x15).
Session ID
Encrypt
HEX
16/32
Encrypted with MSR key. Session ID = RTC value.
KSN (MSR)
Clear
HEX
20/24
DUKPT Key Info (MSR)
Clear
HEX
16
KSN (MP)
Clear
HEX
0/20/24
Empty when MSR key is used
DUKPT Key Info (MP)
Clear
HEX
16
Empty when MSR key is used
Device Serial Number
Clear
ASCII
7
Indicates valid range of each hex digit –
‘0’ ~ ‘9’ (0x30 ~ 0x39),
’A’ ~ ‘F’ (0x41 ~ 0x46)
DUKPT Key Info (MAC)
Clear
HEX
16
Using MSR Key
Message Length
Clear
HEX
4
Include all of message except for MAC. Length required for MAC security. High byte first.
MAC
Clear
HEX
16/32
MAC variant of MSR encryption key is used to calculate MAC.
CBC MAC if MSR DUKPT key is TDES
CMAC if MSR DUKPT key is AES
Track 1 Masked Data
Clear
ASCII
var
Per masking configuration
Track 2 Masked Data
Clear
ASCII
var
Per masking configuration
Track 3 Masked Data
Clear
ASCII
var
Per masking configuration
Track 1 Data
Encrypt
HEX
var
Encrypted with MSR key.
Track 2 Data
Encrypt
HEX
var
Encrypted with MSR key.
Track 3 Data
Encrypt
HEX
var
Encrypted with MSR key.
MP Status Code
Clear
HEX
8
MP Token
Encrypt
HEX
var
Encrypted with MSR or MP key as configured (see Property 0x15).
Session ID
Encrypt
HEX
16/32
Encrypted with MSR key. Session ID = RTC value.
KSN (MSR)
Clear
HEX
20/24
DUKPT Key Info (MSR)
Clear
HEX
16
KSN (MP)
Clear
HEX
0/20/24
Empty when MSR key is used
DUKPT Key Info (MP)
Clear
HEX
0/16
Empty when MSR key is used
Device Serial Number
Clear
ASCII
7
Indicates valid range of each hex digit – ‘0’ ~ ‘9’ (0x30 ~ 0x39), ‘A’ ~ ‘F’ (0x41 ~ 0x46)
DUKPT Key Info (MAC)
Clear
HEX
16
Using MSR Key
Message Length
Clear
HEX
4
Include all of message except for MAC. Length required for MAC security. High byte first.
MAC
Clear
HEX
16/32
MAC variant of MSR encryption key is used to calculate MAC.
CBC MAC if MSR DUKPT key is TDES
CMAC if MSR DUKPT key is AES
Encrypted SCDE
Encrypt
HEX
var
KSN (SCDE)
Clear
HEX
20/24
DUKPT Key Info (SCDE)
Clear
HEX
16
SCDE DUKPT future keys are available (not exhausted)
field_2
PAN from Track 1or Track 2 (padding nibble=F)
CN
var (max 19)
bit 1
field_3
Expiration Date from Track 1 or Track 2
4N
2
bit 2
field_4
Service Code from Track 1 or Track 2
3N
2
bit 3
field_5
T1 discretionary data
AN
var
bit 4
field_6
T2 discretionary data (padding nibble=F)
CN
var
bit 5
0
0
EOM
End of Message
0-7
0x22
‘\r’ (0x0D)
0
FS
Field Separator
1
0x23
‘|’ (0x7C)
0
KSN (Token)
Clear
HEX
20/24
TDES or AES
DUKPT Key Info (Token)
Clear
HEX
16
Qwantum Status
Clear
HEX
8
from ASIC
Qwantum Token
Encrypt
HEX
var
Encrypted with Qwantum Token Key
Padded with zeros
Session ID
Encrypt
HEX
16/32
Encrypted with MSR key. Session ID = RTC value
Qwantum Card ID
Clear
HEX
64
32-byte SHA256 hash of TK1 name, TK2 PAN and TK2 Expiration Date
Device Serial Number
Clear
ASCII
7
Indicates valid range of each hex digit – ‘0’ ~ ‘9’ (0x30 ~ 0x39), ‘A’ ~ ‘F’ (0x41 ~ 0x46)
DUKPT Key Info (MAC)
Clear
HEX
16
for Qwantum Token Key
Message Length
Clear
HEX
4
Includes all of message fields except for MAC (High byte first)
MAC
Clear
HEX
16/32
MAC variant of MSR encryption key is used to calculate MAC.
CBC MAC if MSR DUKPT key is TDES
CMAC if MSR DUKPT key is AES
KSN (Token)
Clear
HEX
20/24
TDES or AES
DUKPT Key Info (Token)
Clear
HEX
16
Session ID
Encrypt
HEX
16/32
Encrypted with MSR key. Session ID = RTC value
Qwantum Buffer
Encrypt
HEX
1-2K
Encrypted with Qwantum Token Key
Padded with pad length
Device Serial Number
Clear
ASCII
7
Indicates valid range of each hex digit – ‘0’ ~ ‘9’ (0x30 ~ 0x39), ‘A’ ~ ‘F’ (0x41 ~ 0x46)
DUKPT Key Info (MAC)
Clear
HEX
16
for Qwantum Token Key
Message Length
Clear
HEX
4
Includes all of message fields except for MAC (High byte first)
MAC
Clear
HEX
16/32
MAC variant of MSR encryption key is used to calculate MAC.
CBC MAC if MSR DUKPT key is TDES
CMAC if MSR DUKPT key is AES
Message Code
Clear
ASCII
2
Text characters indicating message code
Message
Clear
ASCII
36
Message for empty buffer
2-bytes
2-bytes
0…n bytes
Return Code
Response Data Len
Response Data
2-bytes
2-bytes
0...n bytes
Notification ID
Notification Data Len
Notification Data
2-bytes
2-bytes
0...n bytes
Name
Description
Length
Property
Default
T1ISO
Tk1 SS if ISO
1
0x24
M001/M002 Message
Non-PCI
PCI
PAN masking
Can be configured using Property 0x07 and 0x08.
Can be configured using Property 0x07 or 0x08 with the following exceptions.
· Masking Character, ‘V’, is not supported in Property 0x07/0x08.
· Not allowed to unmask leading PAN digits more than 6 digits when PAN length is 15 digits.
Name masking
Always fully unmasked.
Byte
Len
Description
Values
Notes
1
1
DUKPT Key Info Version
0x00 – Legacy DUKPT
0x01 – Current (AES) DUKPT
Field Description
Prot
Type
Txt Len
Notes
Message ID = “M001”
Clear
ASCII
4
Field Description
Prot
Type
Txt Len
Notes
Message ID = “M002”
Clear
ASCII
4
Description
Type
Length (bytes)
Property 0x78
field_1
Cardholder Name from Track 1
AN
var (max 26)
Name
Description
Length
Property
Default
To Disable
SOM
Start of Message
0-7
Description
Prot
Type
Txt Len
Notes
Message ID = “Q001”
Clear
ASCII
4
Description
Prot
Type
Txt Len
Notes
Message ID = “Q002”
Clear
ASCII
4
Description
Prot
Type
Txt Len
Notes
Message ID = “Q003”
Clear
ASCII
4
Responses
Table - Response Structure
Notifications
Table - Notification Structure
Data Output
MSR Track Data
Table - Track Data Sentinel Properties
Note: PCI Requirement – SCR devices that can be used with consumer devices must fully mask cardholder name, expiration date, and service code with no exceptions.
PCI/Non-PCI Masking
Note: The description in this section is for non-PCI device case. The following table shows the difference between non-PCI device and PCI device masking rule.
DUKPT Key Info for Encrypted Data Output
Table - DUKPT Key Derivation Information
Note: Derived key algorithm, length, and usage information will be needed to generate the correct AES-DUKPT decryption key.
Data Messages
Normal Operation – Financial Card Read Message
Table - Data Message M001 Definition
Note: Text length may vary depending on the key type that is being used.
Normal Operation – Financial Card Read Message with Selectable Card Data Encryption Enabled
Table - Data Message M002 Definition
Note:
Text length may vary depending on the key type that is being used.
The three SCDE fields at the bottom of the message are not part of the MAC calculation.
Table - SCDE Data Fields
Table - Separating text fields for host parsing.
Note: Portion in bold shows the data included in the output MAC calculations.
Qwantum Card Read/Qwantum Mode All Card Read
Table - Data Message Q001 Definition
Quantum Buffer Output
Table - Qwantum Buffer Output Q002 Data Message
Empty Qwantum Buffer Output
Table - Qwantum Buffer Output Q003 Data Message
Example:
0x25 ‘%’
Always fully masked with ‘*’.
MSR Data Message
MSR Data Message
bit 0
0x1E
Qwantum Card message
Qwantum Buffer Message
Qwantum Buffer Message
00 02 01 00 0080 FF02 MSR encrypt CBC zero pad with legacy DUKPT 128-bit TDEA data variant.