> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/kld/key-information/key-import/tr-31-file-formats-per-folder-key-type.md).

# TR-31 File Formats (per folder / key type)

### DUKPT-BDK (TR-31)

Line format:

```
Key Name, KEK (optional), KEK-KCV(optional), Key Block, KCV(optional), KSI, EKSI (optional)
```

Where:

* Key Name is mandatory.
* KEK and KEK-KCV are optional.
  * If present, KEK is encrypted with ZMK.
  * Or use the KEK created on the UI.
  * This in-file KEK encrypts the key block.
* Key Block is mandatory.
* KCV for the key block is optional.
  * TR-31 provides MAC check.
* KSI is mandatory.
  * Exactly 10 HEX bytes.
  * 5 bytes in binary computations.
* EKSI is optional.
  * Use it to avoid KSI modification.
  * Provide KSI encrypted with KEK.
* Each line is one key.
* Missing optional fields must still keep commas.
  * Unless optional fields are only at the end.

### FIXED (TR-31)

Line format:

```
Key Name, KEK (optional), KEK-KCV(optional), Key Block, KCV (optional)
```

Where:

* Key Name is mandatory.
* KEK and KEK-KCV are optional.
  * If present, KEK is encrypted with ZMK.
  * Or use the KEK created on the UI.
  * This in-file KEK encrypts the key block.
* Key Block is mandatory.
* KCV for the key block is optional.
  * TR-31 provides MAC check.
* Each line is one key.
* Missing optional fields must still keep commas.
  * Unless optional fields are only at the end.

### Master Session (MS) TR-31

Line format:

```
Key Name, KEK (optional), KEK-KCV (optional), Key Block, KCV (optional), KRD-S/N (optional)
```

Where:

* Key Name is mandatory.
* KEK and KEK-KCV are optional.
  * If present, KEK is encrypted with ZMK.
  * Or use the KEK created on the UI.
  * This in-file KEK encrypts the key block.
* Key Block is mandatory.
* KCV for the key block is optional.
  * TR-31 provides MAC check.
* KRD-S/N is optional.
  * Terminal S/N.
  * Use it to target a specific terminal.
* Each line is one key.
* Missing optional fields must still keep commas.
  * Unless optional fields are only at the end.

#### File naming concept

* See the USB structure for the `MS` folder.
* Master Session keys are split by type:
  * PIN
  * DATA
  * MAC
* Put files under:
  * `MS/PIN`
  * `MS/DATA`
  * `MS/MAC`
* Each file can have many keys.
  * One key per line.

Why multiple files:

* If you want to send two PIN keys to one terminal:
  * Put them in two separate files.
  * Example: `MS/PIN/file1` and `MS/PIN/file2`.
* KLD picks one key from each file.
  * It takes from the top.
  * It sends the key.
  * It deletes that key.
* Two files per type means 6 keys total.
  * 2 PIN + 2 DATA + 2 MAC.

File name prefix rules:

* Every Master Session key file must start with a number and `-`.
  * Examples: `1-...`, `2-...`, `3-...`.
* The rest of the name can be anything.

Refill behavior:

* KLD supports refilling key lists.
* Example for PIN files:
  * Existing: `MS/PIN/1-pin.txt` and `MS/PIN/2-pin.txt`.
  * Refill: `MS/PIN/1-*-refil.txt` and `MS/PIN/2-*-refil.txt`.
* Refill file contents get appended by prefix number.
  * `1-*` appends to `1-pin.txt`.
  * `2-*` appends to `2-pin.txt`.
* You can refill one file only.
* You can add a new list by introducing `3-...`.
* Prefix numbers define the order.

How to see what’s on KLD:

* Go to **Keys**.
* Open a **Key List**.
* You’ll see file names and remaining counts.

Why refill is not chosen in UI:

* UI space is limited.
* Matching old vs new files is error-prone.
* The USB naming convention supports automation scripts.

<br>

### DUKPT-Initial Keys (IK) TR-31

Line format:

```
Key Name, KEK (optional), KEK-KCV (optional), Key Block, KCV (optional), IKSN, EIKSN (optional), KRD-S/N (optional)
```

Where:

* Key Name is mandatory.
* KEK and KEK-KCV are optional.
  * If present, KEK is encrypted with ZMK.
  * Or use the KEK created on the UI.
  * This in-file KEK encrypts the key block.
* Key Block is mandatory.
* KCV for the key block is optional.
  * TR-31 provides MAC check.
* IKSN is mandatory.
  * Exactly 20 HEX bytes.
  * 10 bytes in binary computations.
* EIKSN is optional.
  * Use it to avoid IKSN modification.
  * Provide IKSN encrypted with KEK.
* KRD-S/N is optional.
  * Terminal S/N.
  * Use it to target a specific terminal.
* Each line is one key.
* Missing optional fields must still keep commas.
  * Unless optional fields are only at the end.

Samples:

* See the `IK` sample folder in [TR-31-Key-Sample-Files.zip](https://tr-31-key-sample-files.zip).

File naming concept:

* Same concept as Master Session.
* IK has a single folder.
* Create one file per IK to be sent.
* Start with `1-...`, `2-...`, `3-...` in order.


---

# 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://docs.verifone.com/kld/key-information/key-import/tr-31-file-formats-per-folder-key-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.