Messages
The host and the device communicate with each other by exchanging blocks of data called Messages, which are standardized wrappers containing a payload that is either a command Request, a command Response, an unsolicited Notification, or a File. For example, the host may send a command request message to the device to change a configuration setting, and the device may send a command response message to indicate the command was successful; when a cardholder inserts a card, the device may send a notification message to the host that a cardholder has initiated a transaction; the host may send the device a file message to load firmware.
Messages can be nested. For example, a top-level secure wrapper request from the host to the device may contain an encrypted or signed command request for the device to unpack, validate, and execute.
Requests and Responses
Requests and responses are two of the message payload types the host and device exchange inside messages. The combination of a message that contains a request payload and a message that contains the corresponding response payload is referred to generally in this document as a Command.
The device can only service one command request at a time, and sends each command response within a pre-determined finite amount of time after receiving the request.
After sending a command request, the host must wait until the device returns a response before sending another request, or until the request is unanswered after a reasonable host-defined timeout period passes.
Notifications
Notifications are a message payload type the host and device exchange inside messages. The device sends notification messages 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.
By default, the device sends all notifications to the USB interface. To configure the device to send notifications on additional connections, use Command 0x1F02 - Set Notification Subscriptions.
Data Files
Data Files are a message payload type the host and device exchange inside messages. The device handles them as a stream: it begins storing the payload of the message before it has received the final packet of the message, allowing for much larger payloads than standard requests.
This streaming behavior is possible because the message is restricted to transferring a file and thus the message payload is primitive data only; it cannot contain composed TLV data objects.
Regardless of connection type, all MMS devices use the same schema for sending and receiving messages, which is documented inMessage Format. For information about transmitting and receiving messages using specific connection types (which involves following connection-specific rules for breaking messages down into transmittable Message Streams), see section 2 Connection Types.
Tag-Length-Value (TLV) Encoding
About TLV Encoding
All messages exchanged between the host and the device are formatted using the tag-length-value Distinguished Encoding Rules (DER) defined in ITU-T X.680 | ISO/IEC 8824-1 and ITU-T X.690 | ISO/IEC 8825-1. A subset of these standards is also used in 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.
Summarizing those specifications, each TLV data object follows these basic rules:
The DER standard designates the least significant bit of a byte as bit 1, and the most significant bit of a byte as bit 8. This is different from the remainder of the MMS standard, which indexes bit numbers starting at 0 to be consistent with each bit position number representing that bit’s power of 2.
The Tag or Identifier portion of a TLV data object identifies the TLV data object. DER assigns the tag portion as follows:
Bits 8 and 7 specify whether the TLV data object is universal, application-defined, context-specific, or private. Most messages in this standard contain context-specific tags (bits 8 and 7 = 10), meaning different messages reuse the same tags, and the tags represent sequentially numbered parameters passed in any message.
Bit 6 specifies whether the tag is primitive (bit 6 = 0), meaning it contains its values directly, or constructed (bit 6 = 1), meaning the TLV data object contains more TLV data objects.
Bits 5 to 1 specify a unique tag number, with 11111 reserved to mean the tag is not a single byte long. In that multi-byte case:
Bits 7 to 1 of subsequent bytes with bit 8 set to 1 are also part of the tag identifier with the most significant of the whole tag number in bit 7.
Bits 7 to 1 of the final byte with bit 8 set to 0 are also part of the tag identifier.
The Length portion is the total length of the Data portion that follows it. Lengths can be either short form or long form:
Short form: one byte long in the range 0x00 to 0x7F.
Long form: multiple bytes long, starting with one byte 0x80 or greater, where the lower 7 bits specify how many subsequent bytes are used to indicate the length. Example: length 8201C3 — 0x82 indicates two subsequent bytes (0x01C3) giving the total length of the data block (451 bytes).
DER stipulates all TLV objects should be encoded using the smallest length required to fit the data.
The Value or Data portion is the actual payload of the TLV data object.
This document provides message definitions in hexadecimal format; when the host constructs or interprets a message, if no additional encode/decode filtering or translation is in place at the platform layer, it should expect each hexadecimal value shown in this document to be represented as binary bytes in the message stream, not as string literals. For example, FF is a single byte with all bits set to 1, not the two-byte string literal "FF."
TLV Example
Below is an example of a TLV-encoded request and response for Command 0xDF01 - Echo, wrapped in the standard message format.
Host sends the device the binary byte stream:
Breakdown:
AA00 = Standard Start of Message / API Framework Version (not TLV)
81, 04, 0101DF01
Tag 81 = Request Message Parameter 1, Message Information
Length 04
Value 01 01 DF 01
01 = Request from host to device
01 = Message reference number
DF01 = Command 0xDF01 - Echo
84, 07, DF018103010203
Tag 84 = Request Message Parameter 4, Request Payload
Length 07
Value DF01 81 03 01 02 03
DF01 = Payload format is for Request Command 0xDF01 - Echo (not TLV)
Tag 81 = Payload Parameter 1, Value to Echo
Length 03
Value 01 02 03 = Value to Echo
Device responds with the binary byte stream:
Breakdown:
AA00 = Standard Start of Message / API Framework Version (not TLV)
81, 04, 8201DF01
Tag 81 = Response Message Parameter 1, Message Information
Length 04
Value 82 01 DF 01
82 = Response from device to host
01 = Message reference number
DF01 = Command 0xDF01 - Echo
82, 04, 00000000
Tag 82 = Response Message Parameter 2, Response Status (one byte Operation Status Summary, three bytes Operation Status Detail)
Length 04
Value 00 00 00 00 = OK / Done, General / All Good / Requested operation was successful
84, 07, DF018103010203
Tag 84 = Response Message Parameter 4 for Response Payload
Length 07
Value DF01 81 03 01 02 03
DF01 = Payload format is for Response Command 0xDF01 - Echo (not TLV)
Tag 81 = Payload Parameter 1, Value to Echo
Length 03
Value 01 02 03 = Value to Echo
How to Read TLV Tables
Tables that show TLV data objects use slashes in front of the Tag identifier to indicate that object’s relative level of nesting/containment within other TLV data objects in the same table. These levels are relative and not absolute: a given TLV object may be nested within other TLV objects at any level.
Example of slash notation:
Earth contains
/North America, which contains
//United States, which contains
///California
In TLV tables, a Length of var means the length is variable and must be calculated based on nested objects.
See Table 10 below for an example.
Table 10 - TLV Table Example
A1
var
TLV data object A1 contains four directly nested TLV data objects: 81, 82, A3, and 84 (A1/81, A1/82, A1/A3, and A1/84). A1/82 is optional (Req = O), so the length of A1 will vary depending on whether or not A1/82 is included (Len = var).
T
R
/81
01
TLV data object A1/81 contains one byte and is required. It has no default value because it must be explicitly included.
B
R
/82
03
TLV data object A1/82 contains three bytes but is optional. If not included, the device assumes the default value 0x4D6F6D.
B
O
0x4D6F6D
/A3
08
TLV data object A1/A3 contains two TLV data objects: 81 and 82 (A1/A3/81 and A1/A3/82). Its length is the combined length of its two nested objects.
T
R
//81
03
TLV data object A1/A3/81 contains three bytes and is required.
B
R
//82
01
TLV data object A1/A3/82 contains one byte and is required.
B
R
/84
03
TLV data object A1/84 contains three bytes that represent distinct values stored directly inside A1/84 instead of separate nested TLVs.
B
R
//null
(1)
Raw byte inside 84 (no TLV). Tag shown as /null, length in parentheses.
B
R
//null
(1)
Another raw byte inside 84.
B
R
//null
(1)
Another raw byte inside 84.
B
R
Each message type follows a specific structure described below.
Request Message
Table - Request Message Format
-
-
One byte standard Start of Message constant, not in TLV format. 0xAA = Standard start of message byte.
-
-
-
-
-
One-byte standard API Framework Version, not TLV. Values: 0x00 = Pre-production, 0x01 = First production release, 0x02 = Second production release, etc.
-
-
-
81
var
Message Information
B
R
/null
(1)
Message Type & Direction: 0x01 = Request from host to device; 0x81 = Request from device to host (Reserved)
B
R
/null
(1)
Message Reference Number
B
R
/null
(2)
Command ID — fully qualified Command number (Command Group, Command within that group). If the Request Payload contains wrappers, the host should specify the command invoked at the core after wrappers are removed.
B
R
/null
(var)
Reserved
O
84
var
Request Payload — as documented in the message’s Request table in section Commands.
B
R
9E
var
Reserved
B
O
Notes:
Message Reference Number: host can use any value to match responses; device echoes it in responses. Recommended: incrementing counter per request within a session.
Response Message
Table - Response Message Format
Table - Operation Status Detail Codes
The tables below list operation status detail codes grouped by source and code. (Only a representative subset is shown here; see the full document for all codes.)
General (group 0x00)
The General group 0x00 contains operation status detail codes related to the platform that do not originate from a specific functional module.
Subgroup 0x00 = General
Grp
Sub
Cde
Meaning
00
00
00
All good / requested operation was successful.
00
00
02
Requested Operation Failed
00
00
10
Setting up RTC data and time failure
00
00
11
Setting up RTC alarm failure
00
00
12
Key generation failure
00
00
13
Tamper setting is locked, can’t be changed
00
00
14
Tamper setting requires system reset to continue
00
00
15
Tamper status can’t be cleared, failure
00
00
16
Device has been tampered, need attention
00
00
17
Tamper module failed for other cases
00
00
18
Setting WLAN SoftAP password failure
Message Handler (group 0x01)
The Message Handler group 0x01 contains operation status detail codes related to parsing and validating messages.
Subgroup 0x01 = Device issues that prevent Message Processing (e.g., Critical Battery, Pending Reset, System Failure, System Busy).
Grp
Sub
Cde
Meaning
01
01
01
Generic Failure.
01
01
02
Bad message parameter. The host has sent a message to the device that is not constructed properly.
01
01
09
Device offline, can not process messages. For example, the device returns this detail code when it does not have keys injected or has registered a tamper.
01
01
10
PIN Key Not Mapped.
01
01
13
Feature Not Available
Request Handler (group 0x02) — representative entries
The Request Handler group 0x02 contains operation status detail codes related to starting actual command requests.
Subgroup 0x01 = Data issues (bad, missing, unknown…)
Subgroup 0x02 = Security / permission problems
Subgroup 0x03 = Device state issues (busy, not permitted, tampered, low battery)
Subgroup 0x04 = Device issues (missing hardware or features)
Subgroup 0x05 = TR31 Errors
Grp
Sub
Cde
Meaning
02
00
00
Reserved
02
01
00
Reserved
02
01
01
Generic Failure
02
01
02
Bad Message Parameter
02
01
03
Response Payload too big
02
01
07
Internal FW Failure
02
01
0A
Image Failure
02
01
19
Key does not exist
02
01
1A
Not Secured
02
01
1B
Passcode validation failed
02
01
1C
Device is locked
02
01
1D
Device in Restricted mode
02
02
00
Reserved
02
03
04
Failed, device state issue, no transaction.
02
03
05
Failed, device state issue, cannot cancel.
02
03
08
Failed, device state, Transaction in Progress.
02
03
0C
Failed, device state, Signature Not allowed
02
03
0D
Failed, device state, Wrong Transaction State
02
03
0E
Failed, device state, Invalid PIN Entry State
02
03
0F
Failed, device state, PIN Entry in Session.
02
03
11
Failed, device state, Barcode Read in Progress.
02
03
12
Failed, device state, Pass-through command Not Activated.
02
03
14
Failed, device state, UI Settings in Progress.
02
03
15
Failed, device state, Buzzer in Progress
02
03
16
Failed, device state, Low Battery (5% or less)
02
03
18
Request is invalid while card emulation is in progress
02
03
1E
Failed, device state, pass-through mode started
02
03
1F
Failed, device state, pass-through mode is not started
02
03
20
Failed, device state, pass-through mode APDU is in progress
02
04
13
Failed, BCR hardware not found.
02
05
01
Invalid TR31parameter
02
05
02
Invalid AES length
02
05
03
Invalid 16-Byte Boundary
02
05
04
Invalid Length in Message
02
05
05
Invalid number of optional KBH
02
05
06
Error in conversion of data type
02
05
07
Invalid KCV algorithm
02
05
08
Invalid KCV length
02
05
09
Invalid Optional KBH ID
02
05
0A
Invalid KBH ID
02
05
0B
Invalid algorithm used in KBH
02
05
0C
Invalid KBH usage
02
05
0D
Invalid KBH length
02
05
0E
Invalid version ID for key derivation
02
05
0F
Invalid KBH mode of use
02
05
10
TR31 engine not installed
02
05
11
Invalid Cryptographic operation
02
05
12
MAC Verification Failed
02
05
13
Error in Decrypting Key data
02
05
14
Error in computing MAC over entire message
02
05
15
Invalid MAC length
02
05
16
KDF Error
02
05
17
Buffer Insufficient
02
05
18
Invalid Storage KPM
02
05
19
Invalid Storage Secure RAM
02
05
1A
Invalid Key ID specified in option block
02
05
1B
Unsupported Key ID specified in option block
02
05
1C
Invalid Key ID Relationship
02
05
1D
Protection Key ID not loaded
02
05
1E
Invalid Data Tag MagTek Custom option block
02
05
1F
Invalid Kcv
02
05
20
Invalid Data
02
05
21
Invalid DUKPT key derivation
02
05
22
Invalid Exportability
02
05
23
Invalid Key Class
02
05
24
Invalid DSN
02
05
25
Invalid Challenge
02
05
26
Key Undeletable
02
05
27
Key not present
02
05
28
Unsupported Keyset ID
02
05
29
KPM Error
02
05
2A
Secure RAM Error
02
05
2B
Duplicated Key
02
05
2C
Invalid Key Usage Rule
02
05
2D
Selftest Key Corrupted
02
05
2E
Selftest System Key Bitmap Corrupted
02
05
2F
Selftest System Key Missing
02
05
30
Selftest System Key Not Loaded
02
05
31
Invalid Key Storage Limit
02
05
32
Duplicated Key set
02
05
33
Key Restriction
02
05
34
Key Transported by Weaker key
02
05
35
Repeat Key Agreement
02
05
36
Security not activated
02
05
37
Selftest key relocated
02
05
38
Invalid Selftest Scanned Versus Saved Bitmap
Notification Message
Table - Notification Message Format
-
-
One byte standard Start of Message constant, not TLV. 0xAA = Standard start of message byte.
-
-
-
-
-
One-byte standard API Framework Version, not TLV. Values as in requests/responses.
-
-
-
81
4
Message Information
B
R
/null
(1)
Message Type & Direction: 0x03 = Notification from host to device (Reserved); 0x83 = Notification from device to host.
R
/null
(1)
Reserved, set to 0x00
R
/null
(1)
Notification Source — this byte and Notification Type form the first two bytes of a six-byte Notification ID. Use this byte to look up the Notification Group in 7 Notifications. Example values: 0x01 = Transaction; 0x09 = Firmware Update; 0x10 = Device; 0x18 = User Interface.
R
/null
(1)
Notification Type — append to Notification Source to identify specific notification (e.g., 0x01 = Information Update; 0x02 = Warning; 0x03 = Action Request; 0x04 = Callback; 0x05 = Operation Complete).
R
/null
(var)
Reserved
O
82
(4)
Notification Detail Code — combined with Notification Source and Notification Type to form a unique six-byte Notification ID. See section 7 Notifications for notification-specific detail codes.
B
R
/null
1
Category — e.g., 0x00 = Power/Reset
B
R
/null
1
Reason — e.g., 0x02 = Battery
B
R
/null
1
Reason Detail (Subgroup) — e.g., 0x01 = Power Down Imminent
B
R
/null
1
Reserved, set to 0x00
B
R
83
var
Additional Detail — see notification definition in section 7 Notifications.
O
84
var
Notification Payload — as documented in the notification’s table in section 7 Notifications.
B
O
9E
var
Reserved
B
O
Data File Message
This message type is used exclusively for transferring larger blocks of data treated as files. It is valid only after successful invocation of the appropriate file operation commands (for example, Command 0xD811 - Start Send File to Device (Secured), Command 0xD812 - Start Send File to Device (Unsecured), or Command 0xD821 - Start Get File from Device).
Table - Data File Message Format
-
-
One byte standard Start of Message constant, not TLV. 0xAA = Standard start of message byte.
-
-
-
-
-
One-byte standard API Framework Version, not TLV. Values as in requests/responses.
-
-
-
81
08
Message Information
B
R
/null
(1)
Message Type & Direction: 0x04 = Data file from host to device; 0x84 = Data file from device to host.
B
R
/null
(1)
Message Reference Number — host value to match responses.
B
R
/null
(2)
Command Number that prompted this message (see Command Group 0xD8nn - File Operations).
B
R
/null
(4)
File Type — the file type as defined in Command Group 0xD8nn - File Operations.
B
R
84
var
File Payload — as documented in section 6.7.1 About Files.
B
R
Table - Data File Message Example
Example (Hex)
Last updated