> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/api-and-command-reference/scra-dynafamily-programmers-manual/data-types-and-shared-tlv-data-objects/tr-31-key-block-type.md).

# TR-31 Key Block Type

A ***TR-31***(***X9.143***) key block consists of three parts:

The **Key Block Header**(KBH) which contains attribute information about the key and the key block and is not encrypted. It is always treated as ASCII.

* The first section is 16 bytes with a fixed format defined below.
* The second section is optional within the standard, but required for current products.

The **Confidential Data**, which is encrypted and always binary.

* Two bytes indicating the key length (in bits, AES-128 is 128 bits, so length will be 0080).
* The secret key and/or sensitive data.
* Padding as required (random bytes 0x00 to 0xFF).

The **MAC**, which is of varying length as follows:

* 64 bits if the TDEA key derivation method is used (typically not used for this device).
* 128 bits if the AES key derivation method is used.

<table><thead><tr><th width="96">Header</th><th width="112.6666259765625">Header (optional)</th><th>Key Length</th><th>Key</th><th>Key Padding</th><th>Block Padding</th><th>MAC</th></tr></thead><tbody><tr><td></td><td></td><td>&#x3C;-----------</td><td>Encrypted</td><td>--------------</td><td>------------></td><td></td></tr><tr><td>&#x3C;--------</td><td>------------</td><td>MAC</td><td>--------------</td><td>--------------</td><td>------------></td><td></td></tr></tbody></table>

Symmetric keys are padded with **Block Padding** to the maximum length for the algorithm, 192 bits for TDEA or 256 bits for AES, to hide the true length of short keys.

The data to be encrypted and the MAC are always binary for calculation purposes. The encrypted data and the MAC are converted to ASCII hex as the last step.

Date and time strings specified within the TR-31 block are represented according to the rules described in ***ISO 8601*** and ***TR-31***. Year is 4 digits. Time uses UTC 24 hour clock. Some functions like ‘toISOString()’ will produce a string of format **yyyy-mm-ddThh:mm:ss.fffZ**where fff is a decimal fraction of a second, Z is UTC time zone. The device ignores ‘Z’ and ‘.fff’ if they are present. Seconds ‘:ss’ are optional. Date, hours, and minutes are required. For example, March 23, 2020 4:19PM is encoded as **2020-03-23T16:19**at minimum, but could also be **2020-03-23T16:19:00.000Z**.

## **Table TKB-1 - TR-31 Block Fixed Header**

<table><thead><tr><th width="93.66668701171875">Offset</th><th width="188.6666259765625">Name</th><th width="95">Fixed Value</th><th>Variable</th></tr></thead><tbody><tr><td>0</td><td>Key Block V ID</td><td>‘D’</td><td></td></tr><tr><td>1..4</td><td>Key Block Length</td><td></td><td>Calculated (in decimal, e.g. 138 bytes shown as ‘0138’</td></tr><tr><td>5..6</td><td>Usage</td><td></td><td>Look up the desired <strong>Key Type</strong> in <strong>Table TKB-2  below</strong> and select this value from the <strong>Usage</strong> column.</td></tr><tr><td>7</td><td>Algorithm</td><td></td><td>Look up the desired <strong>Key Type</strong> in <strong>Table TKB-2 below</strong> and select this value from the <strong>Algorithm</strong> column.</td></tr><tr><td>8</td><td>Mode of Use</td><td></td><td>Look up the desired <strong>Key Type</strong>in <strong>Table TKB-2 below</strong> and select this value from the <strong>Mode of Use</strong>column.</td></tr><tr><td>9..10</td><td>Key Version #</td><td>‘00’</td><td>Always ‘00’</td></tr><tr><td>11</td><td>Exportability</td><td>‘N’</td><td>Always no export allowed</td></tr><tr><td>12..13</td><td># option blocks</td><td></td><td>Calculated</td></tr><tr><td>14..15</td><td>Reserved</td><td>‘00’</td><td></td></tr></tbody></table>

## **Table TKB-2 - TR-31 Key Type Table - Usage/Algorithm/Mode**

<table><thead><tr><th>Key Type</th><th width="105">Usage</th><th>Algorithm AES/TDEA</th><th>Mode of Use (Both, To, From)</th></tr></thead><tbody><tr><td>Transport (KBPK)</td><td>‘K1’</td><td>‘A’ / ‘T’</td><td>‘D’</td></tr><tr><td>Initial DUKPT Key</td><td>‘B1’</td><td>‘A’ / ‘T’</td><td>‘X’</td></tr><tr><td>Fixed MAC (CMAC)</td><td>‘M6’</td><td>‘A’ / ‘T’</td><td>(‘C’, ’G’, ’V’)</td></tr><tr><td>Fixed Encrypt</td><td>‘D0’</td><td>‘A’ / ‘T’</td><td>(‘B’, ‘E’, ‘D’)</td></tr></tbody></table>

## **Table TKB-3 - TR-31 Optional Blocks**

<table><thead><tr><th width="88.66668701171875">ID</th><th>Purpose</th></tr></thead><tbody><tr><td>‘IK’</td><td>DUKPT KSID</td></tr><tr><td>‘KS’</td><td>Key Set Identifier (e.g. data used by host to find and/or derive this key).</td></tr><tr><td>‘KC’</td><td>Key Check Value (KCV) (Legacy or CMAC)</td></tr><tr><td>‘PB’</td><td>Padding Field</td></tr><tr><td>‘TS’</td><td>Current Time Stamp (optional) see description in previous section.</td></tr><tr><td>‘KP’</td><td>KCV of KBPK that created this Key Block (optional-preferred)</td></tr><tr><td>‘21’</td><td>MagTek Additional Key Info From <a href="https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/4.0-data-types-and-shared-tlv-data-objects/4.20-tr-31-key-block-type#table-57-magtek-custom-tr-31-small-optional-block"><strong>Table  - MagTek Custom TR-31 Small Optional Block</strong></a></td></tr></tbody></table>

## **Table TKB-4 - MagTek Custom TR-31 Small Optional Block**

<table><thead><tr><th width="88.33331298828125">Offset</th><th width="133.3333740234375">Name</th><th width="106.3333740234375">Value</th><th>Variable</th></tr></thead><tbody><tr><td>0.1</td><td>Block ID</td><td>'21'</td><td>MagTek Added Key Info Block</td></tr><tr><td>2..3</td><td>Block Length</td><td>var</td><td>ASCII Hex (Length 01-FF from offset 0)</td></tr><tr><td>4..7</td><td>Owner Tag</td><td>‘MGTK’</td><td>Avoid collision with others using Block ID ‘21’</td></tr><tr><td>8..9</td><td>Data Tag</td><td>‘10’</td><td>Field ID</td></tr><tr><td>10..11</td><td>Data Len</td><td>‘01’</td><td>Field Length (ASCII Hex 00-FF)</td></tr><tr><td>12</td><td>Data</td><td>‘T’,’P’, or ‘0’</td><td><p>Field Data for Key Environment</p><ul><li>T = Test</li><li>P = Production</li><li>0 = Erase Key</li></ul></td></tr><tr><td>13…</td><td>Added elements</td><td></td><td>More Fields (Tags, Lengths, and Data)</td></tr><tr><td></td><td></td><td></td><td></td></tr></tbody></table>

## **Table TKB-5 - MagTek Custom Key Data Fields**

<table><thead><tr><th width="98.33331298828125">Field ID</th><th width="98">Length</th><th>Purpose</th></tr></thead><tbody><tr><td>‘10’</td><td>‘01’</td><td><p>Key Environment</p><ul><li>T = Test</li><li>P = Production</li><li>0 = Erase Key</li></ul></td></tr><tr><td>‘11’</td><td>‘04’</td><td>Key Slot ID See <strong>Table 59 - Key Slot ID</strong>.</td></tr><tr><td>‘12’</td><td>‘04’</td><td>Key Slot ID of Transport Key</td></tr><tr><td>‘20’</td><td>--</td><td>Reserved</td></tr><tr><td>‘21’</td><td>‘04’</td><td>DUKPT Data Type Restriction Bitmask This is for Transport Keys and DUKPT keys. Default to 0.</td></tr><tr><td>‘31’</td><td>‘07’</td><td>Device Serial Number</td></tr><tr><td>‘32’</td><td>‘10’</td><td>Challenge Token 10h = 16 characters</td></tr><tr><td>‘33’</td><td>‘10’ ..‘18’</td><td>Expiration Date/Time This is in UTC format, use short form if possible. Reserved.</td></tr></tbody></table>

## **Table TKB-6 - Key Slot IDs**

<table><thead><tr><th width="79.66668701171875">ID</th><th width="104.3333740234375">Label</th><th>Description</th><th>Load Transport Key</th><th>TR31-F</th></tr></thead><tbody><tr><td>10xx</td><td></td><td>Transport Keys (KBPK)</td><td></td><td></td></tr><tr><td>1000</td><td>TMPTK</td><td>Temporary KBPK</td><td>Key agreement process from <strong>Command 0xF017 - Establish Ephemeral KBPK</strong></td><td>N/A</td></tr><tr><td>1001</td><td>MTK</td><td>Master Transport Key</td><td>TMPTK</td><td>K1AD</td></tr><tr><td>1002</td><td>DEVTK</td><td>Device Master Transport Key</td><td>MTK</td><td>K1AD</td></tr><tr><td>1003</td><td>FINTK</td><td>Financial Master Transport Key</td><td>MTK</td><td>K1AD</td></tr></tbody></table>

## **Table TKB-7 - Key Slot IDs**

| ID               | Label             | Description                                            | Load Transport Key | TR31-F |
| ---------------- | ----------------- | ------------------------------------------------------ | ------------------ | ------ |
| 1021             | PRODTK            | (MAGTEK INTERNAL ONLY) Production Transport Key        | DEVTK              | K1AD   |
| 1022             | MFGTK             | (MAGTEK INTERNAL ONLY) Manufacturing Transport Key     | DEVTK              | K1AD   |
| 1081             | MKIFTK            | MagTek KIF Financial Transport Keys                    | FINTK              | K1AD   |
| 1101             | FREQMK            | Factory Request MAC Key                                | PRODTK             | M6AV   |
| 1102             | MREQMK            | Manufacturer Device Request MAC Key                    | MFGTK              | M6AV   |
| 1111             | MFRQMK            | Manufacturer Financial Request MAC (Configuration) Key | MKIFTK             | M6AV   |
| 0x2000 to 0x201F | DKPTM0 to DKPTM1F | DUKPT Initial Keys,                                    | MKIFTK             | B1TX   |

### DUKPT Key Mapping

#### Terms and Definitions&#x20;

**DUKPT** – Derived Unique Key Per Transaction **OID**– Object Identifier

**SRED**- Secure Reading and Exchange of Data

There are 7 new OIDs defined for these 7 SRED Data IDs.

Each OID value contains a two-byte DUKPT slot ID and a one-byte transformation ID.

## **Table TKB-8 - SRED Data IDs and OIDs**

<table data-header-hidden><thead><tr><th></th><th width="211"></th><th width="140.6666259765625"></th></tr></thead><tbody><tr><td><strong>SRED Data ID</strong></td><td><strong>OID</strong></td><td><strong>OID Size</strong></td></tr><tr><td>0: Not assigned</td><td>N/A</td><td>N/A</td></tr><tr><td>1: PIN-TDES (supported on PED devices Only)</td><td>0x010102040101</td><td>3</td></tr><tr><td>2: Account Data</td><td>0x010102040102</td><td>3</td></tr><tr><td>3: MAC</td><td>0x010102040103</td><td>3</td></tr><tr><td>4: Magneprint (supported on devices with MSR Only)</td><td>0x010102040104</td><td>3</td></tr><tr><td>5: MagTek Token</td><td>0x010102040105</td><td>3</td></tr><tr><td>6: User Data 1</td><td>0x010102040106</td><td>3</td></tr><tr><td>7: PIN-AES (supported on PED devices Only)</td><td>0x010102040107</td><td>3</td></tr></tbody></table>

#### *DUKPT Slot IDs*

The existing TR31 Module supports 32 MagTek DUKPT Slot IDs, from 0x2000 to 0x201F. The Key Injection Software Tool shall inject DUKPT keys through these DUKPT Slot IDs.

#### *Transformation IDs*

This is the list of DUKPT transformations defined in both the Legacy and AES specifications.

### Restrictions of a DUKPT Slot ID

## **Table TKB-9 - Transformation IDs for DUKPT Legacy and AES**

<table data-header-hidden><thead><tr><th></th><th></th><th width="124.33331298828125"></th><th></th></tr></thead><tbody><tr><td><strong>Transformation ID #</strong></td><td><strong>Usage Name</strong></td><td><strong>Type</strong></td><td><strong>Data for calculation</strong></td></tr><tr><td>0</td><td>Reserved</td><td></td><td></td></tr><tr><td>1</td><td>PIN Encryption</td><td>Legacy</td><td>00 00 00 00 00 00 00 FF</td></tr><tr><td>2</td><td>MAC Generate/Verify</td><td>Legacy</td><td>00 00 00 00 00 00 FF 00</td></tr><tr><td>3</td><td>MAC Verify</td><td>Legacy</td><td>00 00 00 00 FF 00 00 00</td></tr><tr><td>4</td><td>Data Enc/Decryption</td><td>Legacy</td><td>00 00 00 00 00 FF 00 00</td></tr><tr><td>5</td><td>Data Encryption</td><td>Legacy</td><td>00 00 00 FF 00 00 00 00</td></tr><tr><td>6</td><td>Reserved</td><td></td><td></td></tr><tr><td>7</td><td>PIN Encryption</td><td>AES</td><td>0x1000</td></tr><tr><td>8</td><td>MAC Generate</td><td>AES</td><td>0x2000</td></tr><tr><td>9</td><td>MAC Verify</td><td>AES</td><td>0x2001</td></tr><tr><td>A</td><td>MAC Generate/Verify</td><td>AES</td><td>0x2002</td></tr><tr><td>B</td><td>Data Encryption</td><td>AES</td><td>0x3000</td></tr><tr><td>C</td><td>Data Decryption</td><td>AES</td><td>0x3001</td></tr><tr><td>D</td><td>Data Enc/Decryption</td><td>AES</td><td>0x3002</td></tr></tbody></table>

## **Table TKB-10 - The definition of Restriction bit map**

| **Bit #**     | **5**           | **4**       | **3**      | **2** | **1**        | **0** |
| ------------- | --------------- | ----------- | ---------- | ----- | ------------ | ----- |
| **Data Type** | User Data (RFU) | Token (RFU) | Magneprint | MAC   | Account Data | PIN   |

During TR31 Key Injection, each DUKPT Slot ID contains a parameter indicates the purpose of a Key Set.&#x20;

Example 1: The restriction value is 0x3F

This Key Set can be used for all purposes.

Example 2: The restriction value is 0x3E

This Key Set can be used for all purposes, except PIN Encryption.

Example 3: The restriction value is 0x01

This Key Set can be used for PIN Encryption only.

### The Rules of Key Mapping

SRED Data ID map configuration values (Slot ID and Transformation ID) must be checked and rejected if they don’t meet the following conditions.

1. The DUKPT Slot ID must be loaded. [(**Table 63**)](https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/4.0-data-types-and-shared-tlv-data-objects/4.20-tr-31-key-block-type#table-63-settings-of-injected-dukpt-slot-ids)
2. The loaded DUKPT Slot ID must allows this type of SRED Data ID. [**(Table 62)**](https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/4.0-data-types-and-shared-tlv-data-objects/4.20-tr-31-key-block-type#table-62-the-definition-of-restriction-bit-map)
3. The transformation must be allowed by [(**Table 64)**](https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/4.0-data-types-and-shared-tlv-data-objects/4.20-tr-31-key-block-type#table-64-allowed-key-mapping-table).

### The settings of DUKPT Slot IDs injected through TR31

Here is the list of parameters of 4 DUKPT Slot IDs based on the existing Key Injection Tool.

## **Table TKB-11 - Settings of Injected DUKPT Slot IDs**

| DUKPT Slot ID | Key Type | Restrictions |
| ------------- | -------- | ------------ |
| DKPTM0-2000   | TDES     | 0x3E         |
| DKPTM2-2002   | AES-128  | 0x3F         |
| DKPTM3-2003   | AES-256  | 0x3F         |
| DKPTM7-2007   | TDES     | 0x3F         |

### The Allowed Key Mapping Table

## **Table TKB-12 - Allowed Key Mapping Table**

<table><thead><tr><th width="120.3333740234375">SRED Data ID</th><th>Data Type (Working Key Purpose)</th><th>Allowed Legacy DUKPT Transforms</th><th>Allowed AES DUKPT Transforms</th></tr></thead><tbody><tr><td>0</td><td>Not assigned</td><td>-</td><td>-</td></tr><tr><td>1</td><td>PIN-TDES (supported on PED devices Only)</td><td>01</td><td>Not allowed</td></tr><tr><td>2</td><td>Account Data</td><td>01, 04, 05</td><td>0B, 0D</td></tr><tr><td>3</td><td>Transaction MAC</td><td>02</td><td>08, 0A</td></tr><tr><td>4</td><td>MagnePrint (supported on devices with MSR Only)</td><td>01, 04, 05</td><td>0B, 0D</td></tr><tr><td>5</td><td>MagTek Token (RFU)</td><td>RFU</td><td>RFU</td></tr><tr><td>6</td><td>User Data #1 (RFU)</td><td>RFU</td><td>RFU</td></tr><tr><td>7</td><td>PIN-AES (supported on PED devices Only)</td><td>Not allowed</td><td>07</td></tr><tr><td>…</td><td>RFU</td><td>-</td><td>-</td></tr></tbody></table>

Note: If SRED Data ID 2 and 4 are mapped to the same Key Set, then they must have the same Transformation ID. If the Transformation ID of the latest key mapping request is different, then the original OID setting of the other SRED Data ID will be forced to match the latest OID setting. For example, SRED Data ID 2 has been mapped to 0x2007 0x04, user wants to map SRED Data ID 4 to 0x2007 0x05, then the OID setting of SRED Data ID 2 will be forced to 0x2007 0x05.

## Examples of Key Mapping

The following OID Values indicate that:

1. 200701: Map PIN-TDES to DKPTM7-2007 PIN Encryption Variant.
2. 20020B: Map Account Data to DKPTM2-2002 Data Encryption Usage.
3. 200702: Map MAC to DKPTM7-2007 MAC Generate/Verify Variant.
4. 20030B: Map MangePrint to DKPTM3-2003 Data Encryption Usage.
5. 000004: MagTek Token is RFU, 0000 ID does not exist (this is default value).
6. 000004: User Data is RFU, 0000 ID does not exist (this is default value).
7. 200207: Map PIN-AES to DKPTM2-2002 PIN Encryption Usage.

![Graphical user interface, text, application, email Description automatically generated](/files/cd34eea35938efd25b1a091b1914c5d4dbaca342)

<p align="center"><strong>Figure 1 - Configuration Usage Values</strong></p>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.magtek.com/api-and-command-reference/scra-dynafamily-programmers-manual/data-types-and-shared-tlv-data-objects/tr-31-key-block-type.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.