Message Format
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
See Also
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
Last updated