KeyLab MCP

Encode a clear PIN into an ISO 9564-1 PIN block, or decode a PIN block back to the PIN. Formats: 0 (PIN field XOR PAN field; needs pan), 1 (no PAN, random filler), 2 (no PAN, F padding, used for offline/ICC), 3 (like 0 with random A–F filler), 4 (AES: PIN field enciphered with `key`, XORed with the PAN field, enciphered again; needs pan and a 16/24/32-byte AES key). Formats 1, 3 and 4 include random filler, so encoding them twice gives different blocks that decode to the same PIN. Returns the block (formats 0–3: 16 hex chars; format 4: 32 hex chars) or the recovered PIN. Decoding with the wrong PAN or key fails with an explicit error instead of a wrong PIN.

Compute a key check value (KCV) for a DES/3DES or AES key. Methods: DES (3DES-encrypt a zero block, first 3 bytes — what payShield prints for DES keys); CMAC (AES-CMAC over a zero block per X9.24-1, first 3 bytes — what payShield 10K prints for AES keys and AES LMKs; the Thales test LMK gives DB3FB6); CKCV_AES (the same CMAC, 5 bytes, as carried in TR-31 version D key blocks); AES (AES-ECB of a zero block, first 3 bytes — legacy, used by some KMS; NOT the payShield value); plus VISA, ATALLA, SHA256 and CKCV_TDEA. If a KCV from an AES key does not match, try CMAC before assuming the key is wrong. Returns the KCV and the full block it was cut from. A matching KCV proves the key bytes, not their parity or their purpose.

Check the parity of a DES/3DES key (each byte should have odd parity per X9.8/X9.24) or rewrite it to odd or even parity by flipping the low bit of each byte. Enforcing parity does not change the effective key (the low bit is ignored by DES), which is why a KCV survives it — so `check` first when a key "looks wrong" but its KCV matches. AES keys have no parity; do not use this on them.

Split a clear key into random XOR components for a key ceremony (each custodian gets one; no single component reveals the key), or combine components back into the key. Splitting is randomised: the same key gives different components each time, all combining to the same key. Returns each component with its check values, and the combined key with its check values, so custodians can read a KCV per component aloud.

Parse an ANSI TR-31 / X9.143 key block (versions A, B, C, D) or a Thales key block (version 1): header fields with their meanings, optional blocks, encrypted key data and MAC. Pass the key block protection key as `kbpk` to also verify the MAC and unwrap the clear key. Without `kbpk` the header is decoded and nothing is verified. A wrong KBPK is reported as `macVerified: false`, never as a garbage key. Header fields: version (A/B/C/D), key usage (e.g. P0 PIN encryption, B0 BDK, D0 data encryption, K0 KEK), algorithm (T=3DES, A=AES), mode of use (E encrypt, D decrypt, B both, N none…), exportability (E/N/S).

Wrap a clear key into an ANSI TR-31 / X9.143 key block under a key block protection key (KBPK). Version B (3DES KBPK, key derivation binding) and D (AES KBPK, X9.143) are the ones in use; A and C are legacy variant binding; 1 is the Thales AKB. Key usage, algorithm, mode of use and exportability go into the header exactly as given (e.g. P0/T/E/E for a ZPK, B0/T/X/N for a BDK, D0/A/B/E for an AES data key). Random padding makes every block different; verify by parsing it back with keylab_tr31_parse and the same KBPK.

Derive the DUKPT keys for a KSN: 3DES per ANSI X9.24-1 (IPEK, current derived key, and the PIN, MAC request/response and data request/response variants) or AES per X9.24-3:2017 (initial key and the working keys for PIN, MAC, data). For AES, `workingKeyBytes` picks the working-key length (16 = AES-128, 24, 32); the BDK may be AES-128 or AES-256. The KSN is 10 bytes for 3DES (KSI + device ID + 21-bit counter) and 12 bytes for AES (initial key ID + 32-bit counter). Use the result to decrypt a terminal's PIN block or verify its MAC.

Derive an ICC master key (UDK) from an issuer master key (MDK/IMK) and the PAN + PAN sequence number, per EMV Book 2 Annex A1.4: option A (PAN ≤ 16 digits, classic) or option B (any PAN length, SHA-1 decimalisation). Do this once per key family: MK-AC for cryptograms, MK-SMI for script MACs, MK-SMC for script encryption, each from its own issuer master key. Returns the UDK with odd parity applied when `parity` is odd (what a payShield does), and its KCV.

Derive the session key an ICC uses for one transaction from its master key (UDK) and the ATC. `method2` = EMV Common Session Key (Book 2 Annex A1.3: F0/0F branches), the one used by CCD, M/Chip 4+, Visa CVN 18 and most modern profiles. `method1` = the older CSK variant (ATC ⊕ FFFF on the right half). `emv2000` = the EMV 2000 tree derivation (needs iv, branchFactor, height). Returns the session key and its KCV. Wrong method is the usual reason an ARQC does not verify.

Generate an application cryptogram (ARQC/TC/AAC) the way the issuer verifies it: derive the ICC master key from the issuer MK-AC and PAN (option A), derive the session key from the ATC (`method1` or `method2`), then MAC the transaction data (ISO 9797-1 Algorithm 3, padding 80). `transactionData` is the concatenated CDOL1 data in the card profile order (amount, other amount, terminal country, TVR, currency, date, type, UN, AIP, ATC, CVR/IAD…) — the same bytes tag 9F26 was computed over. Returns the cryptogram, the session key and the ICC master key so each step can be compared with an HSM trace.

Generate the ARPC the issuer returns for an ARQC. Method 1 (Book 2 §8.2.1): 3DES of ARQC ⊕ (ARC ‖ 0000…) under the session key, 8 bytes. Method 2 (§8.2.2, CCD/M/Chip): ISO 9797-1 Alg 3 MAC over ARQC ‖ CSU ‖ proprietary data under the session key, 4 bytes, returned as MAC ‖ CSU. Pass the same session key the ARQC was verified with (from keylab_emv_arqc or keylab_emv_session_key).

Parse BER-TLV data (EMV records, GPO/GENERATE AC responses, DOL data, tag 70/77/80 templates) into tags with their EMV names, lengths and values. Constructed tags (E0, 70, 77, A5, 6F, 61…) are expanded into children. Multi-byte tags (9F26, 5F2A, DF8129…) and long-form lengths (81 xx, 82 xx xx) are handled. Malformed input fails at the exact byte offset instead of returning a partial tree.

Parse an ISO 8583 (1987 ASCII) message given as hex: MTI, primary and secondary bitmap, and every present field with its name and value (LLVAR/LLLVAR lengths resolved; binary fields kept as hex). Field definitions follow the 1987 standard layout; a processor's private fields (48, 61–63, 120–127) come back as raw text. Use it to see which field an ARQC (DE 55), PIN block (DE 52) or MAC (DE 64/128) sits in before checking it.

Compute a card verification value under a CVK pair (Visa CVV / Mastercard CVC algorithm): PAN, expiry (YYMM) and service code → 3 digits. CVV (magstripe track) uses the real service code; CVV2 (printed on the card) uses service code 000 and the expiry in YYMM; iCVV (chip track 2 equivalent) uses service code 999. Returns the 3 digits. A mismatch with the card is a CVK, expiry-order (MMYY vs YYMM) or service-code problem in that order of likelihood.

Compute the Visa PVV for a PAN and PIN under a PVK (PIN verification key): the 4 digits an issuer stores to verify a PIN without storing the PIN. PVKI selects which of the issuer's PVK pairs was used (0–9; 1 is the common default). Returns the 4-digit PVV.

Compute a DES-based message authentication code: X9.9 (single DES CBC-MAC, 8 bytes), X9.19 retail MAC (ISO 9797-1 Algorithm 3: single DES CBC then final 3DES, the one payment networks use for DE 64/128 and EMV cryptograms), ISO 9797-1 Algorithm 1 (CBC-MAC) and Algorithm 3, each with padding method 1 (zero pad) or 2 (0x80 then zeros). Returns the full 8-byte MAC; truncate to 4 bytes yourself when the protocol says so.

Encrypt or decrypt with DES / 3DES (single, double or triple-length key) in ECB or CBC mode, with no padding by default — data must then be a multiple of 8 bytes, as it is in every payment use (PIN blocks, key encryption, KCVs). Use padding pkcs7 only for free-form data. Returns hex.

Encrypt or decrypt with AES-128/192/256 in ECB, CBC, CFB, OFB or GCM. Padding is none by default (payment data is block-aligned); pkcs7 for free-form data. GCM returns an authentication tag on encrypt and needs `tag` on decrypt. Returns hex.

Validate a number with the Luhn (mod 10) algorithm, or compute the check digit for a partial number. Returns `isValid` for the number as given and `checkDigit` = the digit that, appended to the number, makes it Luhn-valid. So for a full PAN read `isValid`; for a PAN without its last digit read `checkDigit`.

XOR two or more hex strings (key components, PIN/PAN fields, DUKPT variants, check-value arithmetic). Shorter operands are left-padded with zeros to the longest length. Returns uppercase hex.

List the payShield host commands the simulator implements (key management A0/A6/A8/BW/CA…, PIN CA/DA/JA/JE/JG/BA…, EMV KW/KQ/M0/M2/M6/M8…, diagnostics NC/NO), or describe one: its parameters with lengths and hints, its response code, and a worked example that runs clean against the test LMK — either a raw message or a `params` object for keylab_hsm_run. Call this before keylab_hsm_run when unsure of a command's field layout.

Send one host command to a simulated payShield 10K and get the response, parsed: response code (00 = OK), response command, data and an explanation. Give either `raw` (the whole message: 4-char header + command + fields, e.g. "0000NC" or "0000A00FFFS%00#P0A3N00S00") or `command` + `params` (the field names keylab_hsm_commands lists; the message is composed for you). The simulator starts fresh on every call with the Thales test LMK (type 4 AES key block by default; `lmkType` 1–3 for variant/3DES key block LMKs), so keys imported in one call do not exist in the next — carry key blocks between calls yourself. An HSM error is a normal result with `ok: false` and the error code (e.g. 15 invalid input, 10 wrong key), not a tool error.

Compose a KMIP request and return its exact TTLV bytes (hex) plus an annotated wire view. Start from a template (discover-versions, query, create-aes, get, get-attributes, destroy, register, register-payment) for a protocol version (1.4, 2.0, 2.1, 3.0), or pass the request in the OASIS XML profile form as `xml`. Placeholders: $NOW, $NOW+seconds, $UNIQUE_IDENTIFIER_n (filled from `uids`). register-payment carries the standard payment vocabulary (Key Role Type BDK/CVK/ZPK/MK…, Wrapping Method TR-31). Send the bytes over TLS to port 5696 yourself, then decode the reply with keylab_kmip_read.

Decode a KMIP TTLV dump (hex) into the OASIS XML profile form and read it out: the operation, and for a response the result status, reason and message, and any Unique Identifiers returned. A byte-level fault is reported with its offset (TtlvError), so a truncated capture or a wrong length is named, not guessed at.