Messages, Commands, Responses, and Notifications

About Messages, Commands, Responses, and Notifications

The host and the device communicate with each other by exchanging blocks of data called Messages, which can be either Commands, Responses to commands, or Notifications. For example, the host may send a command to the device to change a configuration setting, and the device may send a response that the command was successful; when a cardholder inserts a card, the device may send a notification to the host that a cardholder has initiated a transaction.

The device can only service one command at a time, and sends each response within a pre-determined finite amount of time after receiving the command. After sending a command, the host must wait until the device returns a response before sending another command.

The device sends notifications to the host if the device’s state changes or if an external event occurs, such as a cardholder inserting a card. The device can send a notification at any time, and does not expect a response or any specific action from the host.

Although the wrappers for messages may be different depending on the connection type the host and device are using to communicate, the message payload format and contents are exactly the same. For example, apart from the wrapper differences defined in section 3 Connection Types, a message sent over an RS-232 connection will be exactly the same as a message sent over a USB-HID connection.

About Big Block Commands and Notifications

There are some cases where data transmitted from the host to the device or from the device to the host requires special treatment. For example, some commands require the host or the device to transmit large blocks of data that exceed the maximum packet size of the chosen data transport layer; other commands require transmitted data to be encrypted and/or encoded, fully received, then decrypted and/or decoded as a single piece. For commands, responses, and notifications that require this special treatment, the usage information in this document indicates that the data should be sent as Big Block Data.

For commands from the host to the device that require big block messages, either because the message exceeds the current connection’s maximum packet size or because the message requires special treatment such as encryption, the host should first compose the full command message in local memory according to the usage table of the desired command, then transmit the message using Command 0x01::0x10 - Send Big Block Command. See that command’s documentation for details.

The host should always anticipate the device could send responses or notifications that exceed the current connection’s maximum packet size, and that the device will transmit them using multiple instances of Notification 0x01::0x10 - Big Block Device Data. The host must count all instances and concatenate them to form a complete message. See that notification’s documentation for usage details.

About Responses

ACK Response

After receiving a command that does not require the device to return data, the device sends a simple response to the host to acknowledge (“ACK”) the command. The response includes the Message Type Data Object (Tag C0) indicating it is a response, the Application ID Data Object (Tag C1) and the Command ID Data Object (Tag C2) identical to the command the device is acknowledging, and a Result Code Data Object (Tag C3) reporting the results of the command.

Table 2-1 shows an example of an ACK Response from the device after the host has sent Command 0x01::0x02 - Clear Transaction Data, where the device is reporting “OK / Done.”

Table - Example ACK Response “OK / Done”

Tag

Len

Value(s) / Description

Message Type Data Object (Tag C0) = Response

Application ID Data Object (Tag C1) =

Application Group 0x01 - General Messages

Command ID Data Object (Tag C2) =

Command 0x01::0x02 - Clear Transaction Data

Result Code Data Object (Tag C3) = OK / Done

Table 2-2 shows an example of an ACK Response from the device where the host has sent a command using an invalid message format (protocol violation) and the message is “Bad Message Format.”

Table -Example ACK Response “Bad Message Format”

Tag

Len

Value(s) / Description

Message Type Data Object (Tag C0) = Response

Application ID Data Object (Tag C1) = 0x01 General Messages

Command ID Data Object (Tag C2) =

Command 0x01::0x10 - Send Big Block Command

Result Code Data Object (Tag C3) = Bad Message Format

Message Format

Messages exchanged between the host and the device consist of a required header, which consists of three or four specific tag-length-value (TLV) data objects, plus in many cases a fifth top-level TLV data object containing a data payload. Table 2-3 shows the header TLV data objects in the order the host should use when sending messages, and should expect when receiving messages. Details about each of the top-level data objects are provided in the following sections, and every command and notification in section 4 Command Set provides concrete usage tables that show byte-by-byte how the host software should compose or interpret the message.

Table - Message Format

Tag

Data Value / Data Object(s)

Message Type Data Object (Tag C0), sometimes abbreviated MTYP (always included)

Application ID Data Object (Tag C1), sometimes abbreviated APPID (always included)

Command ID Data Object (Tag C2), sometimes abbreviated CMDID (always included)

Result Code Data Object (Tag C3), sometimes abbreviated RC (not always included)

Data Field Data Object (Tag C4 or E0), sometimes abbreviated DATA (not always included)

The TLV data objects are constructed using the Basic Encoding Rules (BER) for the industry standard format defined in ITU-T X.680|ISO/IEC 8824-1 and ITU-T X.690|ISO/IEC 8825-1. These standards are also the basis of EMV Integrated Circuit Card Specifications for Payment Systems 4.3, Part IV, Annex B Rules for BER-TLV Data Objects, so the latter can serve as a useful point of reference, especially for programmers who are familiar with the operation of chip cards. Summarizing those specifications, each TLV data object follows these basic rules:

The Tag portion is a single byte that identifies the TLV data object [such as 0xC0 in the case of

Message Type Data Object (Tag C0)].

· The Length portion is calculated as the total length of the Data portion that follows it. Lengths can be either one byte long from 0x00 to 0x7F, or multiple bytes starting with 0x80 or higher, in which case the lower 7 bits of the first byte specify how many subsequent bytes will indicate the length of the Data portion that follows. For example, in the case of Length 8201C3, 0x82 is greater than 0x7F, and the lower 7 bits equal 0x02, so the next 2 bytes 0x01C3 give the total length of the data block, 451 bytes.

The Data portion is the actual payload of the TLV data object.

Message Type Data Object (Tag C0)

The Message Type TLV data object specifies the message type: Either Command, Response, or Notification. Table 2-4 formally defines the TLV data object.

Table - Message Type TLV Data Object (Tag C0)

TAG

1 Byte

Message Type (MTYP) Tag

LEN

1 Byte

For this data object, Length is always 1 byte

DATA

Byte

Value

Definition

Data

Command message type

Data

Response message type

Data

Notification message type

For device operations that take a long time or an indefinite amount of time, the host usually sends a command that initiates the operation, and the device returns an ACK Response to indicate it has started the operation. When the operation completes, the device sends a Notification to the host.

Application ID Data Object (Tag C1)

The Application ID TLV data object specifies which Application ID the message belongs to. Each functional subsystem of the device has a unique Application ID, and contains a defined message set pertaining to that subsystem. For example, a device might contain an MSR application for its magnetic stripe reader and an EMV L2 Contact application for interacting with contact chip cards. Table 2-5 formally defines the TLV data object.

Table - Application ID TLV Data Object (Tag C1)

TAG

1 Byte

Application ID (APPID)

LEN

1 Byte

Length is Always 1

DATA

Byte

Value

Definition

00..08

Application Group 0x00 - Device Information Messages Application Group 0x01 - General Messages Application Group 0x02 - Authentication Messages

Application Group 0x03 - Device Configuration Messages Application Group 0x04 - Magnetic Stripe Reader (MSR) Messages

Application Group 0x05 - PAN Messages

Application Group 0x07 - EMV L2 Contact Messages (Chip Card L2 Mode Only)

Command ID Data Object (Tag C2)

The Command ID TLV data object has a different meaning for each of the possible values in the

Message Type Data Object (Tag C0):

For Commands, the Command ID defines the operation to be carried out by the device.
For Responses, the Command ID refers to the operation that was carried out by the device, and always contains the same value as the Command ID Data Object (Tag C2) from the originating command.
For Notifications, the Command ID specifies the event that has occurred in the device.

Table 2-6 formally defines the TLV data object.

Table - Command ID TLV Data Object (Tag C2)

TAG

1 Byte

CMDID

LEN

1 Byte

Length is Always 1

DATA

Byte

Value

Definition

Data

Command ID within specified Application Group

Result Code Data Object (Tag C3)

The Result Code TLV data object has different meaning for each of the possible values in the Message Type Data Object (Tag C0):

For Commands, the host should not send this data object to the device.
For Responses, the result code reports the result of the operation that was carried out by the device.
For Notifications, the result code reports the result of the event that has occurred in the device.

The Table below formally defines the TLV data object.

Table - Result Code TLV Data Object (Tag C3)

TAG

1 Byte

Result Code (RC)

LEN

1 Byte

Length is Always 1

DATA

Byte

Value

Definition

Data

1 (Result Code)

00..FF

0x00 = OK / Done 0x01 = Failure 0x02 = Warning

0x03 = Cardholder Cancel 0x04 = Timeout

0x05 = Host Cancel 0x06 = Verify fail

0x07 = Bad Message Header 0x08 = Bad Application ID 0x09 = Bad Message ID 0x0A = Bad Parameter 0x0B = System State Error

0x0F = Current Device Status Prohibits Command 0x10 = Command not supported

0x11 = Requested item not available 0x12 = No card inserted

0x13 = Wrong card inserted 0x14 = Smart card not accessible

0x15 = Application already running 0x16 = Requested item expired

0x17 = Configuration locked, modification prohibited 0x18 = Error state

0x19 = No encryption keys available 0xFF = Bad Message Format

80..FF

This range is for custom result codes. A custom result code has a unique meaning for a particular application.

0x80 = Device Error. A device error or tamper has been detected, the Device Certificate is missing or has been changed, or signature is not correct.

0x81 = Device not Idle

0x82 = Data Error or Bad Parameter(s). The command contains bad parameters. For example, in a big block command transfer, the parameters in any packet 1 through n don’t match (or don’t follow) the previous data packet’s parameters; it may also indicate a bad CBC- MAC ACKSTS, wrong serial number, or a bad key.

0x83 = Length Error or OID error. The data size is 0 or is larger than the available buffer size, or a data packet is incomplete, or MagTek device OID of the certificate doesn’t match the predefined OID

0x8A = Device not Available, Device Status is not OK, Touchscreen is not connected or doesn’t exist, or Mutual Authentication challenge token has timed out (i.e. is not used within 5 minutes)

0x90 = Certificate or associated CA doesn’t exist. For unbind/rebind/key injection, the associated certificate doesn’t exist

0x91 = Expired (Certificate/Certificate Revocation List) 0x92 = Invalid (Certificate/Certificate Revocation List/Message)

0x93 = Revoked (Certificate/Certificate Revocation List) 0x94 = Associated Certificate or Certificate Revocation List doesn’t exist

0x95 = Certificate exists

0x96 = Duplicate KSN/Key. The key already exists.

Data Field Data Object (Tag C4 or E0)

If there is additional data associated with the message, it is contained in the Data Field TLV data object. The length of this field is equal to the length of the whole message minus the length of the message header [Message Type Data Object (Tag C0), Application ID Data Object (Tag C1), Command ID Data Object (Tag C2), and Result Code Data Object (Tag C3)].

For Primitive data, the Data Field data object is identified with Tag C4. C4 is only used when the data portion of the message only contains raw data and will not include any embedded TLV data objects.

Table 2-8 formally defines the C4 data object.

Table - Primitive Data Field TLV Data Object (Tag C4)

TAG

Primitive tag, for raw data with no encryption

LEN

Length of Data

Data

Value (Hex)

Value of Data

For Constructed data, the Data Field data object is identified with Tag E0. E0 is used if the data portion of the message wraps additional TLV data objects. The TLV data objects that can be embedded in the Data Field are detailed in section 2.5 Data Field, or in the documentation in section 4 Command Set for messages that use them.

The data inside an E0 (Constructed type) Data Field is also encoded using the BER TLV data object rules explained in section 2.4 Message Format. It becomes very important pay careful attention to the length of every data object to encode/decode correctly. Programmers way wish to recursively construct those data objects by “nesting” from the inside out.

Table 2-9 formally defines the E0 data object.

Table - Constructed Data Field TLV Data Object (Tag E0)

TAG

E0 = Constructed tag, meaning Data contains other tags

LEN

Length of Data

Data

Value (Hex)

Other tags are present in data section

Linux Style Date-Time Stamps

Some commands embed Linux-style date-time stamps in their responses. To decode the time embedded in these commands, use a Linux shell to enter a command sequence similar to this:

# Convert the hex RTC value to a decimal number
# and assign it to ‘RTC_VAL’:

$ RTC_VAL=1502981285

# Run the Linux ‘date’ command with format below:
$ date +"%F %T %z" -d "1970-01-01 UTC + $RTC_VAL seconds" # Tamper occurred at:
2017-08-17 07:48:05 -0700

Data Field Content Objects

This section specifies the data objects that can be embedded in the Data Field Data Object (Tag C4 or E0) when it contains Constructed data tagged with type E0.

Primitive Data Types

Throughout this document, the tables that describe tag-length-value (TLV) data structures use the following primitive data types:

A = Alphabetic (string, no numbers).
AN = Alphanumeric (string).
B = Binary value, which includes bit combinations (“OR” types).
CN = Compressed numeric, as defined by EMV 4.3 Book 3, section Data Element Format Conventions.
N = Numeric, as defined by EMV 4.3 Book 3, section Data Element Format Conventions.
T = TLV Constructed data object (TLV Value contains additional layers of TLV-encoded data the parser should continue to process).

Data Object F1 - Device Status

The device uses a data object identified by tag F1 to send the device status:

Table - Contents of Data Object F1 Device Status

Tag

Len

Value(s) / Description

Calculated

Device Status <DF51><len><val> (see Table 2-11)

Device Certificate Status <DF52 ><len><val> (see Table 2-12) Reserved <DF53>..<DF5F><len><val>

Data Object DF51 Device Status

Hardware errors will cause the device to not respond to any command, except for device status inquiry.

Table - Contents of Data Object DF51 Device Status

Value

Bit 7

Byte 0 Hardware

UCI

Error 0 =

Normal 1 =

Error

TRNG

Error

0 = Normal

1 = Error

Crypto Engine Error

0 = Normal

1 = Error

Byte 1 Reserved

Battery voltage:

0 = Normal

1 = Low, which indicates the device is close to end of life. Voltage can drop off drastically at any time and the device is considered tampered if that occurs.

Byte 2 Reserved

Byte 3 Reserved

Byte 4 Security Status

Real Time Clock Status Setting

0 = RTC

has been set to current time.

1 = RTC

has not been set to current time.

SYSTEM- CLEARED

Tamper occurred: 0 = Device not tampered 1 = Device tampered

Tamper activated:

0 = Activated

1 = Not activated

Byte 5 One-Time-

Programmable (OTP) Memory Status

MAC

Address Status:

0 = MAC

has been written to OTP

1 = MAC

has not been written to OTP

Serial Number Status:

0 = SN has been written to OTP

1 = SN has been NOT written to OTP

Byte 6 Reserved

Byte 7 Reserved

Byte 8 Reserved

Byte 9 Reserved

Byte 10 Reserved

Byte 11 Reserved

Data Object DF52 Device Certificate & Key Status

Table - Contents of Data Object DF52 Device Certificate & Key Status

Value

Bit 7

Byte 0 Device Certificate Status

PIN CRL

MSR

Keyloader Cert

Device Cert

MSR

Sub CA Cert

PIN Sub CA Cert

Device CA

Cert

Unbind Cert

Byte 1 Device Certificate Status

Device Signing Cert

MSR CRL

Byte 2 Device Key Status

MSR DUKP T KEY

Byte 3 Reserved

Data Object F4 - Magnetic Stripe Reader Card Data

The device uses TLV Data Object F4 wrapped in Data Object F9 - MACed Message to transmit magnetic stripe data to the host. To find commands, responses, and notifications that use this data object, search this documentation for this section name.

The parent data object F9 contains additional tags alongside data object F4 that indicate the conditions and events that produced the magnetic stripe data:

POS Entry Mode (9F39) is included by the device automatically every time the host calls Command 0x04::0x12 - Request MSR Card Data, and is included in Notification 0x07::0x83 - EMV L2 ARQC Message if the host has configured the device to include it by adding 9F39 to data object list DFDF02 in EMV Contact Terminal Settings and Defaults. It contains one of the following based on the card’s service code:
- 0x80 = The card data came from a chip card (service code 2xx or 6xx).
- 0x90 = The card data came from a magnetic stripe card.
MSR Fallback (DFDF53) which contains one of the following based on the card’s service code and the state the device was in at the time it read the card:
- 0x00 = The host did not start an EMV transaction after the card was inserted. The device is returning MSR data from a magnetic stripe card.
- 0x01 = The host did not start an EMV transaction after the card was inserted. The device is returning MSR data from a chip card (service code 2xx or 6xx).
- 0x81 = The host started an EMV transaction using Command 0x07::0x00 - EMV L2 Start Transaction, the device detected a chip card but reported a transaction failure.
  - If EMV application setting DFDF67 is configured to MSR Fallback Not Supported, the device did not perform an MSR fallback operation on its own. The host performed host-driven MSR fallback using Command 0x04::0x09 - Read MSR Data, and the device read the magnetic stripe data during card removal.
  - If EMV application setting DFDF67 is set to MSR Fallback Supported, the device performed an MSR fallback operation automatically, used Notification 0x07::0x82 - EMV L2 User Selection Request to prompt the cardholder to remove the card, and the device read the magnetic stripe data during card removal. In this case:
    The transaction failure occurred before the GENAC1 phase. If a failure occurs after the GENAC1 phase, the device does not perform automatic MSR fallback.
    The device returns MSR data in the ARQC data in Notification 0x07::0x83 - EMV L2 ARQC Message in TLV data object F4.
    If terminal setting DFDF17 specifies F4 should be included in batch data, the device also includes MSR data in the batch data of Notification 0x07::0x84 - EMV L2 Transaction Result.
    If the card is in the Account Data Whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist) the device includes F4 in TLV data object 70.
    If the card is not in the Account Data Whitelist, the device includes F4 in encrypted TLV data object F8.
    The device returns tags DFDF53 and 9F39 in the ARQC message in TLV data object 70.

If the card’s PAN does not match any entry in the device’s configured Account Data whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist), data object F4 contains the tags shown in Table 2-13. If the card is in the device’s configured Account Data whitelist, data object F4 contains the tags shown in Table 2-14.

Table - Contents of TLV Data Object F9 - MSR Card Data (PAN Does Not Match Account Data Whitelist)

9F39<len><POS Entry Mode> 
DFDF53<len><MSR Fallback> 
F4<len>
    DFDF31<len><Masked Track 1 Data> 
    DFDF33<len><Masked Track 2 Data> 
    DFDF35<len><Masked Track 3 Data>
    DFDF36<len><Track 1 Status, 0x00 = OK, 0x01 = Data Error, 0x02 = 
Empty, 0x03 = PAN Error, 0x04 = Disabled>
    DFDF38<len><Track 2 Status, 0x00 = OK, 0x01 = Data Error, 0x02 = 
Empty, 0x03 = PAN Error, 0x04 = Disabled>
    DFDF3A<len><Track 3 Status, 0x00 = OK, 0x01 = Data Error, 0x02 = 
Empty, 0x03 = PAN Error, 0x04 = Disabled>
    DFDF43<len><MagnePrint Status Data>
    DFDF4F<len><Encode type,0x00 = Other, 0x01 = ISO, 0x02 = AAMVA >

    F8<len> /* container tag for encryption */ 
        DFDF59<len><encrypted data> 
        DFDF51<len><encryption type> 
        DFDF56<len><KSN>
        DFDF58<len><val> /* # of padding bytes added to DFDF59 
value to force length to a multiple of 8 bytes */
        DFDF25<len><Device Serial Number>

TLV data object F8 is an encrypted data object wrapping the encrypted track data and MagnePrint Data nested within data object DFDF59, plus supporting information as clear text in other tags.

The device encrypts the value inside data object DFDF59 using the current MSR DUKPT working key used in the relevant transaction. The device uses either the PIN variant or data variant of the key, depending on the current MSR Encryption Variant setting (see Command 0x03::0x72 - Get Device Configuration).

As a requirement for using the DUKPT TDES encryption algorithm, the device pads it so the length of its value is a multiple of 8 bytes. The device uses tag DFDF58 to report how many bytes of tag DFDF59 are padding. DFDF59 contains the following after the host decrypts it:

                FA <len>
                                DF41<len><Clear text Data for track 1> 
                                DF42<len><Clear text Data for track 2> 
                                DF43<len><Clear text Data for track 3> 
                                DF44<len><Magneprint Data>

Table - Contents of TLV Data Object F9 - MSR Card Data (PAN Matches Account Data Whitelist)

 9F39<len><POS Entry Mode> 
DFDF53<len><MSR Fallback> 
F4<len>
                DFDF31<len><Clear text Data for track 1> 
                DFDF33<len><Clear text Data for track 2> 
                DFDF35<len><Clear text Data for track 3>
                DFDF36<len><Track 1 Status, 0x00 = OK, 0x01 = Data Error, 0x02 = 
Empty, 0x03 = PAN Error, 0x04 = Disabled>
                DFDF38<len><Track 2 Status, 0x00 = OK, 0x01 = Data Error, 0x02 = 
Empty, 0x03 = PAN Error, 0x04 = Disabled>
DFDF3A<len><Track 3 Status, 0x00 = OK, 0x01 = Data Error, 0x02 = Empty, 0x03 = PAN Error, 0x04 = Disabled>
                DFDF4F<len><Encode type, 0x00 = Other, 0x01 = ISO, 0x02 = AAMVA >

The MAC value is calculated based on the padded <F9 TLV for MACed MSR data> (the MACing operation requires MACed data length to be multiple of 8). However, after MACing calculation, the padding bytes should not be included in the F9 TLV. The receiving end is responsible for padding the F9 TLV when verifying the corresponding MAC. The MAC is stored in the DFDF6C TLV. <E0 TLV len> is the total of the <F9 TLV for MACed MSR data> and <DFDF6C TLV for MAC value>.

Encryption Type data object DFDF51 uses one byte to represent the key scheme, encryption algorithm and variant. Table 2-15 lists the possible values.

Table - Contents of Encryption Type Data Object DFDF51

Tag

Description

DFDF51

MSR Encryption Type: 1xxx xxxx = DUKPT key xx00 xxxx = TDES

xx01 xxxx = AES128 xx10 xxxx - AES256 xxxx xx00 = Data variant xxxx xx01 = PIN variant xxxx xx10 = MAC variant

Data Object F8 - Encrypted Data

F8<len> /*container tag for encryption */
    DFDF59<len><val> /* Encrypted Data Primitive; decrypt data to 
read tags */
    DFDF56<len><val> /* Encrypted Transaction Data KSN */> 
    DFDF57<len><val> /* Encrypted Transaction Data Encryption Type */ 
    DFDF58<len><val> /* # of padding bytes added to DFDF59 value to
force length to a multiple of 8 bytes */

Data Object F9 - MACed Message

F9<len> /* container for MAC structure and generic data */ DFDF0B(Message Data Information Primitive)<len><val> DFDF54(MAC KSN)<len><val>
DFDF55(MAC Encryption Type)<len><val> DFDF25(IFD Serial Number)<len><val> FA<len>/* container for generic data */
…

<Padding to make F9 plus padding be a multiple of 8 bytes>

<Four byte CBC-MAC> or DFDF6C<len><MAC>

The device only uses DFDF6C as the MAC container when it sends this data object in a response to

Command 0x04::0x12 - Request MSR Card Data.

To calculate the F9 MAC to authenticate the message, include the F9 tag, length, and contents, and pad it with zeroes to make overall length a multiple of 8. Use the DUKPT MAC variant of the transaction key (DUKPT MAC variant constant = 0000 0000 0000 FF00 0000 0000 0000 FF00) with the CBC-MAC algorithm, and use the first 4 bytes of the 8.

Data Object DFDF0B Primitive - Message Data Information

Data object DFDF0B contains three bytes that indicate the nature of the data included in the FA container within Data Object F9 - MACed Message.

Byte 0 is data type:

0x00 = Reserved

0x01 = EMV Contact L2 Data

Byte 1 is encryption type 0x00 = Data is Encrypted

0x01 = Data is Clear Text (account number found in device whitelist)

Byte 2 is Reserved.

0x00 = Reserved

0x01 = Set to this value

Last updated 1 month ago