> 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.md). # Key import *** {% columns %} {% column %}
{% endcolumn %} {% column %} {% endcolumn %} {% column %} **Version:**\ **Date:** {% endcolumn %} {% column %} 1.0.0\ Feb 2026 {% endcolumn %} {% endcolumns %} ## Important Notes * Key import through files on USB **must** be done correctly, and it's left to the teams to prepare the data correctly, possibly through automated scripts. * Importing duplicate data is a **security issue** since the same key may be sent to 2 or more different terminals if there are duplicates. * **Read** the document thoroughly and the Error Handling section below. * **Prevent** any duplicate keys anywhere in the data while preparing the data on the USB. Use automation scripts as much as possible to prevent manual errors. * Be even more careful when you want to refill the existing data set on the KLD. * The reason is newly created data set on the KLD can be deleted and re-imported without any issues. If refilling the existing dataset on the KLD goes wrong, you may have to lose the existing dataset on the KLD. * When importing large data, set the log level to `INFO`. `DEBUG/VERBOSE` will slowdown the import. *** ## How to Import Key Files through USB * Please read the "Key Lists, and Difference between Keys and Key Lists" sections under "Key Concepts" section in the User Guide * Please do not forget or ignore the "Handling Key Import Error" section below. It's very important. * Importing Keys Files follows a specific file structure and file names on the USB * Below is a sample of the Directory and File structure on the USB. * The Folder names "BDK", "FIXED", "MS/KEK", "MS/KBPK", and "IK" are fixed. They cannot be any other names. These are optional if there are no keys under these Folders. * The file names "fixed-key.txt" and "dukpt-bdk.txt" are fixed, cannot be changed. The File Names under MS and IK folders are not fixed, they can be any names. See "File Naming Concept" below * Under MS and IK Folders, the number of files is not fixed, but the directory names and directory structure is fixed. You can have many files under these directories. See File Naming concept section below for more details.
*** ## File Formats ### Attached Key Sample Files (see [Key import files from USB - sample files+](/kld/key-information/key-import-files-from-usb-sample-files+.md)) Attached Key sample files use the following 3TDEA KEK: **{0x02, 0x25, 0x48, 0x67, 0x89, 0xAB, 0xCD, 0x01,0x01, 0xDC, 0xBA, 0x98, 0x78, 0x53, 0x34, 0x17, 0x12, 0x23, 0x34, 0x41, 0x32, 0x45, 0x67, 0x78}** ### Common to All Files * Files are plain text. * Comment lines start with `#` and are ignored. * Empty lines are ignored. * Each line contains exactly one key entry. * Files can be prepared in Windows or Linux. Each line ends with a newline. * For cryptograms: * If the KEK is AES, then KEY cannot be 3TDEA (padding scheme is unknown). * IV is zero (ASCII zero). Example for TDEA: `"\x30\x30\x30\x30\x30\x30\x30\x30"`. * CBC mode. * KCV: * Legacy for TDEA: 3 bytes (6 HEX chars). * CBC-MAC for AES: 5 bytes (10 HEX chars). *** ## 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) ``` * 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 the KEK created on the UI), and this in-file KEK encrypts the Key block. * Key Block is mandatory. * KCV for the Key Block is optional since TR-31 format does MAC check of the key. * KSI is mandatory. Exactly 10 HEX Bytes (it's 5 bytes in binary during computations) * EKSI is optional. If we don't want the KSI modified(security), provide an encrypted KSI with KEK. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data. ### FIXED (TR-31) Line format: ``` Key Name, KEK (optional), KEK-KCV(optional), Key Block, KCV (optional) ``` * 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 the KEK created on the UI), and this in-file KEK encrypts the Key block. * Key Block is mandatory. * KCV for the Key Block is optional since TR-31 format does MAC check of the key. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data ### 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 the KEK created on the UI), and this in-file KEK encrypts the Key block. * Key Block is mandatory. * KCV for the Key Block is optional since TR-31 format does MAC check of the key. * KRD-S/N is optional. This is the terminal S/N (Serial Number). If you choose to send a specific key from this file to a specific terminal, specify the S/N. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data. * **File naming concept:** * See the USB file structure picture above for the "MS" folder * The Master Session keys are separated into 2 types. KEK and KBPK keys. * The 'K0' usage key (also known as KEK key) files go under "MS/KEK" folder * The 'K1' usage key (also known as KBPK key) files go under "MS/KBPK" folder * Each file can have many keys (maybe even 2500 keys). One key per line. * Why multiple files in each folder? * For example, if you want to send 2 KEK keys and 2 KBPK keys to the same terminal, each of the 2 keys goes into 2 separate files. * Example. Two KEK keys (each one) will go into MS/KEK/file1 and MS/KEK/file2. Same for KBPK folders * When sending keys, the KLD will pick one key from each file (from the top of the file), send them to the terminal and delete that key. * This means, for the above example, two keys each from KEK and KBPK data will be sent for a total of 4 keys (sent to terminal and will be deleted). * All Master session key files must start with a numeric value followed by a hyphen as in "1-" or "2-" or "3-" etc. (no quotes) * The rest of the file name can be anything. Examples "1-mytestkek.txt" OR "2-nfkeye.ndfknflk.jsdjhfds" OR "3-xxxxxx". Obviously, we recommend meaningful names. * Why start with specific numeric prefix format? * The product allows refilling of the key lists on KLD. In the above example, where there are 2 PIN, DATA and MAC keys, the user can refill these key inventory. * How does it work? * Example: Take just Master KEK keys * First time you import , let's say your file names are "MS/KEK/1-kek.txt" and "MS/KEK/2-kek.txt". Each file can have any number of keys inside. * Now you are running out of keys in these 2 files and want to refill these files. * If you have the following files on the USB, "MS/KEK/1-kek-refil.txt" and "MS/KEK/2-kek-refil.txt", then all the keys from 1-kek-refil.txt will be appended (or added) to the file "1-kek.txt" and the keys from "2-kek-refil.txt will be appended (or added) to the file "2-kek.txt". * If you want to just refill one file, then you will have "MS/KEK/1-kek-refil.txt" OR "MS/KEK/2-kek-refil.txt" on the USB. * Suppose you want to add a 3rd key list to this MS-KEK above * You will have just "MS/KEK/3-kek.txt" on the USB. This file now becomes the 3rd KEK key to be sent to the terminal. * Suppose you want to refill the first file and add a 3rd list at the same time * You will have "MS/KEK/1-xxxxx" and "MS/KEK/3-xxxxxx" on the USB. The "1-xxxxx" will be appended to "MS/KEK/1-kek.txt" and the ""MS/KEK/3-xxxxxx" will be the new 3rd key list. * As you can see, essentially files are in Numeric sequential ascending order (with the numeric prefix) and can be re-filled anytime using the same numeric prefix number and/or new files can be added just by incrementing the numeric file number with respect to the existing list. * How do you know what's currently on the KLD? Use "Keys" menu item and click on any of the "Key List" item, it will display all the existing file names and the number of keys available in that file. * Why not allow the user to pick the file to refill through UI. * KLD UI space is too small to show all the existing files from KLD and New ones from the USB for the user to correctly match/refill. It is very error-prone. * By using this file format on the USB drive, teams can simply write automated scripts that follow the Directory and File structure and thus less error-prone.\
### 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) ``` * Key Name, KEK (optional), KEK-KCV (optional), Key Block, KCV, 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 the KEK created on the UI), and this in-file KEK encrypts the Key block. * Key Block is mandatory * KCV for the Key Block is optional since TR-31 format does MAC check of the key * IKSN is mandatory. Exactly 20 HEX Bytes (it's 10 bytes in binary during computations) * EIKSN is optional. If we don't want the IKSN modified(security), provide an encrypted IKSN with KEK * KRD-S/N is optional. This is the terminal S/N (Serial Number). If you choose to send a specific key from this file to a specific terminal, specify the S/N. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data * See the attached sample folder "IK" in the attached "[TR-31-Key-Sample-Files.zip](https://tr-31-key-sample-files.zip)" * File naming concept * See the USB file structure picture above for the "IK" folder * Refer to the File Naming Concept under Master Session Key * It's the same concept. The exception is, there is only one folder for IK key files. Master session has 2 folders (KEK, KBPK). See the attached sample files. * For each DUKPT-IK to be sent, create a separate file starting with the number in increasing order as in "1-xxxxx", "2-xxxxx", "3-xxxxxx" etc. *** ## Cryptogram File Formats ### DUKPT-BDK (Cryptogram) Line format: ``` Key Name, KEK Algorithm(optional), KEK (optional), KEK-KCV (optional), Key Algorithm, Cryptogram, KCV, KSI, EKSI (optional) ``` * Key Name, KEK Algorithm(optional), KEK (optional), KEK-KCV (optional), Key Algorithm, Cryptogram, KCV, KSI, EKSI (optional) * Key Name is mandatory. * KEK Algorithm, KEK and KEK-KCV are optional. If present, KEK is encrypted with ZMK (or the KEK created on the UI) and this in-file KEK encrypts the Cryptogram. * Key Algorithm names are "2TDEA", "3TDEA", "AES-128", "AES-192", "AES-256". * Key Algorithm is mandatory. * Key Block is mandatory. * KCV for the Key Block is mandatory. * KSI is mandatory. Exactly 10 HEX Bytes (it's 5 bytes in binary during computations) * EKSI is optional. If we don't want the KSI modified(security), provide an encrypted KSI with KEK. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data. ### FIXED (Cryptogram) Line format: ``` Key Name, KEK Algorithm(optional), KEK (optional), KEK-KCV (optional), Key Algorithm, Cryptogram, KCV ``` * Key Name, KEK Algorithm(optional), KEK (optional), KEK-KCV (optional), Key Algorithm, Cryptogram, KCV * Key Name is mandatory. * KEK Algorithm, KEK and KEK-KCV are optional. If present, KEK is encrypted with ZMK (or the KEK created on the UI), and this in-file KEK encrypts the Cryptogram. * Key Algorithm is mandatory. * Key Block is mandatory. * KCV for the Key Block is mandatory. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data. ### Master Session (MS) (Cryptogram) Line format: ``` Key Name, KEK-Algorithm(optional), KEK (optional), KEK-KCV (optional), Key Algorithm, Cryptogram, KCV, KRD-S/N(optional) ``` * Key Name, KEK-Algorithm(optional), KEK (optional), KEK-KCV (optional), Key Algorithm, Cryptogram, KCV, KRD-S/N(optional) * Key Name is mandatory. * KEK Algorithm, KEK and KEK-KCV are optional. If present, KEK is encrypted with ZMK (or the KEK created on the UI), and this in-file KEK encrypts the Cryptogram. * Key Algorithm is mandatory. * Key Block is mandatory. * KCV for the Key Block is mandatory. * KRD-S/N is optional. This is the terminal S/N (Serial Number). If you choose to send a specific key from this file to a specific terminal, specify the S/N. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data. * See the attached sample folder "MS" in the attached "[Cryptogram-Key-Sample-Files.zip](https://cryptogram-key-sample-files.zip)" * Refer to the File Naming concept under TR-31 Master Session Keys ### DUKPT-Initial Keys (IK) (Cryptogram) Line format: ``` Key Name, KEK algorithm (optional), KEK (optional), KEK-KCV (optional), Cryptogram, KCV, IKSN, EIKSN (optional), KRD-S/N (optional) ``` * Key Name, KEK algorithm (optional) KEK (optional), KEK-KCV (optional), Cryptogram, KCV, IKSN), EIKSN (optional), KRD-S/N (optional) * Key Name is mandatory. * KEK Algorithm, KEK and KEK-KCV are optional. If present, KEK is encrypted with ZMK (or the KEK created on the UI), and this in-file KEK encrypts the Cryptogram. * Key Algorithm is mandatory. * Key Block is mandatory. * KCV for the Key Block is mandatory. * IKSN is mandatory. Exactly 20 HEX Bytes (it's 10 bytes in binary during computations) * EIKSN is optional. If we don't want the IKSN modified(security), provide an encrypted IKSN with KEK. * KRD-S/N is optional. This is the terminal S/N (Serial Number). If you choose to send a specific key from this file to a specific terminal, specify the S/N. * Each line is one key * Missing optional field data must have a comma in place unless the optional fields are at the end mandatory data. * See the attached sample folder "IK" in the attached "[Cryptogram-Key-Sample-Files.zip](https://cryptogram-key-sample-files.zip)" * Refer to the File Naming concept under TR-31 IK Keys *** ## Key Import UI (Files)
* When importing large volumes set the log level to `INFO`. * The above dialogs are in sequential order. 1. First dialog: pick which key type to import. 2. In case of Master Session and IK key lists, second dialog allows the user to create a new key list or add keys (refill) to an existing key list. When trying to re-fill or add keys to an existing list, user will be shown the list of existing key list names in a drop down. Select the list name you wish to refill the keys 3. The third dialog allows the user to select the KEK and the file format. 4. After keys are imported, the Import results are shown in the dialog below. * For each key list file imported, the result dialog shows, how many lines (keys) are read from the file and how many lines (keys) resulted in Error. * **User should check both the "Total Lines" and "Lines with Error".** * Total Lines is the number of key lines read from the file (This excludes, blank and commented lines) * Lines With Error shows the number of Keys failed to import * **If there are Error lines, user must take action as needed.** * Refer to the "Handling Key Import Error" section below
*** ## Import DUKPT-BDK Keys * We mostly expect BDK keys are imported through UI (through components). User can import the BDK keys also through this file method. * The Folder name is "BDK" on the USB Root. * The File name must be "dukpt-bdk.txt" * The file format can be TR-31 or Cryptogram. The entire file must be TR-31 or Cryptogram. Cannot mix the format inside the file. * Only 2TDEA algorithm is supported. * See the File format section above. *** ## Import FIXED Keys * We mostly expect FIXED keys are imported through UI (through components). User can import the FIXED keys also through this file method. * The Folder name is "FIXED" on the USB Root. * The File name must be "fixed-key.txt" * The file format can be TR-31 or Cryptogram. The entire file must be TR-31 or Cryptogram. Cannot mix the format inside the file. * Each key line can have any key algorithm (2TDEA, 3TDEA, AES-128, AES-192, AES-256) and the corresponding keys. * See the File format section above *** ## Import DUKPT-IK (Initial Keys) * The Folder name is "IK" on the USB Root. * The file format can be TR-31 or Cryptogram. * See the File format section above. * For each IK to be sent, create a separate file. If you want to send Two IK keys to the same terminal, create two files. For 3 IK keys, 3 files and so on. *** ## How to Import MS (Master Session) Keys * Folder names on USB: * KEK (K0 usage) keys: `MS/KEK` * KBPK (K1 usage) keys: `MS/KBPK` * File format: TR-31 or Cryptogram (entire file must be one format). * For each Master Key List to send, create a separate file: * Example: If two KEK keys should be sent to a terminal, create two files under `MS/KEK`. * Same concept for `MS/KBPK`. * The KLD will pick one key from each file (top of file), send them to the terminal and delete that key. * See the File naming concept under TR-31 Master Session Keys above. *** ## Handling Key Import Error
* After Keys are imported, as mentioned above, there will be a Import stats dialog that will show if any failure as indicated by "Lines With Error" * User should check both the "Total Lines" and "Lines with Error". * Total Lines is the number of key lines read from the file (This excludes, blank and commented lines) * Lines With Error shows the number of Keys failed to import * If There are Error lines, user must take action as needed. * To find the error line, user must export the App log and look for errors. The log will list the "line number" and the Error reason. * Why we are not showing this on the UI. * A key List can contain many keys, even 2500 keys. We cannot show all the errors on the very small UI space. It is error-prone. * Example for Master Session import error: * Let’s say in the above USB file structure, the "2-xxxxx.txt" under file "MS/KBPK" folder had 100 key lines. * Line number 33 and 76 resulted in error. * What to do? * First export the App log using the "Log/Export Log" menu item and look for the error and line number. * There are two use cases to recover for this failure. * FIRST - When creating NEW KEY LIST * In this case there is no existing data set on KLD for this Key List since we are creating as new key list. * TWO Solutions: * ONE: * Delete the imported (partial) key List through UI menu. * Fix the 2 error lines in the "2-xxxxx.txt" file. (or delete the 2 lines if you don't want them) * Do the Key import again using "Create New List" option. * TWO (Be careful with this approach) * Leave the Partially imported Key List on the KLD. * From the "2-xxxx.txt" file delete all the lines except the two error lines (33 and 76). * Fix the 2 error lines. * Remove all the other files under the "MS" folder on the USB. * Copy only the new "2-xxxx.txt" with just the 2 corrected lines (now line numbers are 1 and 2 since we have deleted all the other lines) to the USB under "MS/KBPK" folder. * This must be the only file on the USB under MS/KBPK folder * Do the key import again, this time using the "Existing Key List" option and select the Key list you just partially imported. * This will add the 2 corrected keys in file new "2-xxxx.txt" to the original "2-xxxxx" file on the KLD. * TWO - When Refilling an Existing Key List * There is the same as the solution number 2 in the First use case above. * Essentially and very importantly the only data that can be on the USB is the fixed line(s) in the respective files. * If there are errors in two files, only those 2 files and only with the corrected line(s) can be on the USB. * All successfully imported lines and files cannot be on the USB. * In this case (refill case), when fixing the error lines, if you keep other files or lines that have been successfully imported, will duplicate the data on KLD which can be security issues since same key(s) will be sent to different terminals. * Possible solution to the above issue: * We can make the key import "all or nothing". Meaning, the product will only import the keys if there are no errors in the input data (everything must be correct). * Even with this approach, the user can still make a mistake if they re-import the same file during the next refill process by having old file(s) on the USB. {% content-ref url="/spaces/dijxZlL1xtgpr7dUOWO8/pages/edrAnh6CnfRxPzKuyzhM" %} [Copyright](/terms-and-conditions/copyright-and-warranty/copyright-liability-warranty-etc/copyright.md) {% endcontent-ref %} --- # 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.md?ask=&goal= ``` `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.