HSM Simulator Documentation

Overview

The HSM Simulator in ISO8583Studio emulates a Thales PayShield 10K Hardware Security Module. It allows you to develop and test payment host applications that require HSM integration without needing access to physical HSM hardware.

🔐

Key Management

Generate, import, export, and translate cryptographic keys including ZMK, ZPK, TPK, BDK, ZEK, and more.

🔢

PIN Operations

Translate PIN blocks between keys, verify PINs using IBM 3624 and VISA PVV methods, and generate PIN offsets.

🔒

Encryption / Decryption

Encrypt and decrypt data blocks with DES/3DES in ECB and CBC modes using ZEK, DEK, or BDK keys.

📝

MAC Generation

Generate and verify MACs using ISO 9797 Algorithm 1 and Algorithm 3 with ZAK or TAK keys.

🔑

RSA Support

Generate RSA key pairs, import public keys, and create/validate digital signatures.

💾

LMK Storage

Multiple LMK slots, persistent key storage, and full LMK lifecycle management.

Quick Start Guide

Create an HSM configuration — From the Home screen, create a new HSM Simulator configuration. Set the profile name and device details.
Configure network settings — Set the TCP/IP bind address and port (e.g. 0.0.0.0:9090). Configure the message header length (default: 4 characters).
Launch the simulator — Open the HSM Simulator screen and start the server from the HSM Handler tab.
Connect your application — Point your host application to host:port and send PayShield host commands.
Test with built-in commands — Use the Host Commands tab to send commands interactively and inspect responses.

Tip

Start with the NC (Diagnostic Test) command to verify the simulator is running and LMK is loaded. A response of ND00 confirms everything is healthy.

Message Protocol

The HSM Simulator uses the standard Thales PayShield host command protocol over TCP/IP.

Request Format

[Length Header (2 bytes, optional)][Message Header (4 chars)][Command Code (2 chars)][Data Fields][%LMK_ID][Trailer]

Component	Size	Description
Length Header	2 bytes	Optional. Big-endian message length (excluding the length header itself).
Message Header	4 chars	Configurable header echoed back in response (e.g. `0000`).
Command Code	2 chars	Two-character command identifier (e.g. `NC`, `A0`).
Data Fields	Variable	Command-specific data parameters.
LMK ID	3 chars	Optional `%XX` suffix to select a specific LMK slot.
Trailer	Variable	Optional end-of-message marker (`\u0019` + trailer data).

Response Format

[Length Header (2 bytes, optional)][Message Header][Response Code][Error Code (2 chars)][Response Data]

The response code is the command code incremented by one character (e.g. NC → ND, A0 → A1). An error code of 00 indicates success.

Example Exchange

Request:  0000NC
Response: 0000ND00LMK12345678901234567890123456789012345678

Request:  0000A0001U
Response: 0000A100U1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF

Encoding

All messages use ISO-8859-1 encoding. Keys are represented as hexadecimal strings in the protocol.

Network Settings

TCP/IP Configuration

Setting	Default	Description
Bind Address	`0.0.0.0`	IP address to listen on. Use `0.0.0.0` for all interfaces.
Port	`9090`	TCP port for the HSM server.
Length Header	Optional	Enable 2-byte big-endian length prefix before each message.
Message Header Length	4	Number of characters in the message header (echoed back in response).

Additional Connection Types

Serial — RS232 connection with configurable port, baud rate, data bits, stop bits, and parity.
REST API — HTTP endpoint for HSM commands.
WebSocket — Real-time bidirectional HSM communication.

LMK Storage

The Local Master Key (LMK) is the foundation of HSM security. All working keys are encrypted under LMK pairs.

LMK Structure

40 LMK Pairs — Pairs 00–39, each consisting of a left key and right key. Different key types are encrypted under specific LMK pairs.
Multiple LMK Slots — Slots 00–99 allow independent LMK sets. Select the slot using %XX in commands or via port mapping.
Old / New LMK — Support for LMK migration with the BW (Translate Key) command.

LMK Pair Assignments

LMK Pair	Key Type Encrypted
Pair 02–03	PIN Encryption Keys (PINs under LMK)
Pair 04–05	ZMK (Zone Master Keys)
Pair 06–07	ZPK, TPK (Zone/Terminal PIN Keys)
Pair 14–15	PVK (PIN Verification Keys)
Pair 16–17	TAK (Terminal Authentication Keys)
Pair 22–23	BDK (Base Derivation Keys)
Pair 26–27	ZEK, DEK (Data Encryption Keys)
Pair 28–29	ZAK (Zone Authentication Keys)

Persistence

LMK data is stored in payShield10k_lmkStorage.json and within the simulator configuration JSON. Keys persist across restarts.

Diagnostics & Info Commands

Command	Response	Name	Description
`NC`	`ND`	Diagnostic Test	Health check. Returns `00` if the HSM and LMK are functioning correctly.
`NO`	`NP`	Reserved	Reserved diagnostic command.
`VR`	`VS`	Version Info	Returns firmware version and serial number of the emulated HSM.
`VT`	`VU`	View LMK Table	Displays Key Check Values (KCVs) of all 40 loaded LMK pairs.
`GK`	`GL`	Generate LMK Component	Generates a random LMK component for key loading ceremonies.

Example: Diagnostic Test

Request:  0000NC
Response: 0000ND00

Error code 00 = HSM is healthy, LMK loaded.

Key Management Commands

Command	Response	Name	Description
`A0`	`A1`	Generate Key	Generates a new DES/3DES key encrypted under LMK. Optionally also encrypted under a ZMK for transport.
`A6`	`A7`	Import Key	Imports a key encrypted under ZMK and re-encrypts it under LMK.
`A8`	`A9`	Export Key	Exports a key from LMK encryption to ZMK encryption for transport to another zone.
`BU`	`BV`	Generate KCV	Generates a Key Check Value (KCV) for a given key. Used to verify key integrity.
`BW`	`BX`	Translate Key (LMK)	Translates a key from old LMK encryption to new LMK encryption during LMK migration.
`GC`	`GD`	Generate Components	Generates N random key components. Used in split-knowledge key ceremonies.
`FK`	`FL`	Form Key from Components	XORs 2 or 3 key components together to form a working key under LMK.

Example: Generate a ZPK

Request:  0000A0001U
                ^^^ ^^^
                |   |-- Key scheme: U = double-length
                |------ Key type: 001 = ZPK

Response: 0000A100U<key-under-LMK><key-under-ZMK><KCV>

Example: Generate KCV

Request:  0000BU0U<key-under-LMK>
Response: 0000BV00<6-char-KCV>

PIN Block Operations

Command	Response	Name	Description
`BA`	`BB`	Encrypt PIN Block	Encrypts a clear-text PIN into a PIN block under TPK or ZPK.
`CA`	`CB`	Translate PIN (TPK → ZPK)	Re-encrypts a PIN block from Terminal PIN Key to Zone PIN Key.
`CI`	`CJ`	Translate PIN (ZPK → TPK)	Re-encrypts a PIN block from Zone PIN Key to Terminal PIN Key.
`BC`	`BD`	Translate PIN Block	Translates PIN block between encryption keys.
`G0`	`G1`	Translate PIN (DUKPT → ZPK)	Translates a DUKPT-encrypted PIN block to ZPK encryption.
`JC`	`JD`	Translate PIN (TPK → LMK)	Re-encrypts a TPK-encrypted PIN block under LMK.
`JE`	`JF`	Translate PIN (ZPK → LMK)	Re-encrypts a ZPK-encrypted PIN block under LMK.
`JG`	`JH`	Translate PIN (LMK → ZPK)	Re-encrypts an LMK-encrypted PIN to a ZPK PIN block.
`NG`	`NH`	Generate DUKPT Key	Derives a DUKPT session key from a BDK and Key Serial Number.

Example: Translate PIN (TPK → ZPK)

Request:  0000CA<TPK><ZPK><max-pin-length><pin-block>01<account-number>01<account-number>
Response: 0000CB00<pin-length><translated-pin-block>

Note

The CA command is the most commonly used PIN translation in payment processing. It converts a PIN block received from the terminal (encrypted under TPK) into a block suitable for sending to the card issuer (encrypted under ZPK).

PIN Verification Commands

Command	Response	Name	Description
`DA`	`DB`	Verify PIN (IBM 3624)	Verifies a PIN using the IBM 3624 natural PIN method with offset data.
`DC`	`DD`	Verify PIN (VISA PVV)	Verifies a PIN against a VISA Pin Verification Value (PVV).

Example: VISA PVV Verification

Request:  0000DC<ZPK>01<pin-block><account-number><PVK-pair><PVV>
Response: 0000DD00   (00 = PIN verified successfully)
Response: 0000DD01   (01 = PIN verification failed)

PIN Generation Commands

Command	Response	Name	Description
`DE`	`DF`	Generate IBM PIN Offset	Generates an IBM 3624 PIN offset. Used for PIN issuance.
`DG`	`DH`	Generate VISA PVV	Generates a VISA Pin Verification Value for a given PIN.
`EE`	`EF`	Derive PIN from Offset	Derives the natural PIN from an IBM 3624 offset and validation data.

Data Encryption / Decryption Commands

Command	Response	Name	Description
`M0`	`M1`	Encrypt Data Block	Encrypts a data block using ZEK, DEK, or BDK in ECB or CBC mode.
`M2`	`M3`	Decrypt Data Block	Decrypts a data block using ZEK, DEK, or BDK.
`M4`	`M5`	Translate Data Block	Re-encrypts data from one key to another (e.g. DUKPT to ZEK).

Cipher Modes

ECB (Electronic Codebook) — Each block encrypted independently. Simpler but less secure for repetitive data.
CBC (Cipher Block Chaining) — Each block XORed with the previous ciphertext block. Requires an IV (Initialization Vector).

MAC Operations

Command	Response	Name	Description
`M6`	`M7`	Generate MAC	Generates a MAC using ZAK or TAK with ISO 9797 Algorithm 1 or 3.
`M8`	`M9`	Verify MAC	Verifies a MAC value against the original data and key.
`MY`	`MZ`	MAC Variants	Additional MAC algorithm and format variants.

MAC Algorithms

ISO 9797 Algorithm 1 — Single DES CBC-MAC. Standard for most payment applications.
ISO 9797 Algorithm 3 — Retail MAC (DES CBC-MAC with final 3DES step). Provides stronger security.

Hashing Commands

Command	Response	Name	Description
`GM`	`GN`	Hash Data	Computes a hash digest of the input data.

Supported Algorithms

SHA-1
SHA-256
MD5

RSA / Asymmetric Commands

Command	Response	Name	Description
`EI`	`EJ`	Generate RSA Key Pair	Generates an RSA public/private key pair. Private key encrypted under LMK.
`EO`	`EP`	Import RSA Public Key	Imports a DER-encoded RSA public key into the HSM.
`EW`	`EX`	Generate Signature	Creates an RSA or ECDSA digital signature over input data.
`EY`	`EZ`	Validate Signature	Validates an RSA or ECDSA signature against the original data.

Dynamic CVV/CVC

Command	Response	Name	Description
`PM`	`PN`	Verify Dynamic CVV/CVC	Verifies Visa dCVV or MasterCard CVC3 values for contactless transactions.

User Storage Commands

Store, retrieve, and delete keys or data in indexed user storage slots (000–FFF).

Command	Response	Name	Description
`LA`	`LB`	Load to Storage	Stores a key or data at a specified storage index (000–FFF).
`LE`	`LF`	Read from Storage	Retrieves data from a specified storage index.
`LD`	`LM`	Delete from Storage	Deletes the entry at a specified storage index.

Key Types & Schemes

Key Types

Code	Name	Purpose
`000`	ZMK	Zone Master Key — Key-encrypting key for secure key exchange between zones.
`001`	ZPK	Zone PIN Key — Encrypts PIN blocks for transmission between zones.
`002`	TPK / PVK	Terminal PIN Key / PIN Verification Key — Terminal PIN encryption or PIN verification.
`003`	TAK	Terminal Authentication Key — MAC generation at the terminal.
`008`	ZAK	Zone Authentication Key — MAC generation between zones.
`009`	BDK	Base Derivation Key — Master key for DUKPT key derivation.
`00A`	ZEK	Zone Encryption Key — Data encryption between zones.
`00B`	DEK	Data Encryption Key — General-purpose data encryption.
`302`	IKEY	Intermediate Key — Internal processing key.

Key Schemes

Scheme	Hex Length	Description
`X`	16 characters	Single-length DES key (56 effective bits).
`U`	32 characters	Double-length 3DES key (112 effective bits). Most common for payment.
`T`	48 characters	Triple-length 3DES key (168 effective bits). Maximum DES security.

PIN Block Formats

Code	Format	Description
`01`	ISO 9564-1 Format 0	Standard ISO format. PIN XORed with PAN. Most widely used.
`02`	ISO 9564-1 Format 1	ISO format without PAN dependency.
`03`	Docutel	Legacy Docutel ATM format.
`04`	PLUS	PLUS network PIN block format.
`05`	ISO 9564-1 Format 3	ISO format with random fill.
`06`	Diebold	Legacy Diebold ATM format.
`47`	ISO 9564-1 Format 4	AES-based PIN block format (newer, more secure).
`46`	AS2805	Australian standard PIN block format.

Error Codes

Every HSM response includes a 2-character error code. 00 indicates success.

Code	Meaning
`00`	No error — command executed successfully.
`01`	Verification failure (PIN or MAC mismatch).
`02`	Key Check Value (KCV) failure.
`04`	Cryptographic algorithm not supported.
`10`	PIN block length error.
`15`	Invalid input data.
`17`	Invalid message length.
`23`	PIN length error.
`26`	Invalid LMK identifier.
`27`	LMK check value failure.
`39`	Console authorization required.
`42`	Invalid LMK type code.
`68`	Command is disabled.
`74`	Data parity error in key or data block.
`75`	Invalid message length field.
`80`	Unknown command or invalid format.
`82`	Function not permitted by current configuration.
`A1`	Console not authorized. Grant authorization first.
`A2`	HSM not authorized.
`A3`	Command only available in secure state.
`A4`	Invalid key type for this command.
`B1`	Invalid key scheme code.
`C1`	LMK is not loaded. Load LMK before issuing commands.

UI Tabs Reference

Tab	Description
HSM Handler	Start/stop the HSM server. View live request/response traffic, connection count, and server status.
Key Management	View loaded LMK status, key check values, and manage key components.
Host Commands	Interactive command forms for all ~35 supported commands. Grouped by category with search and filtering. Shows wire-format hints and formatted results.
Secure Commands	Administrative and LMK-related operations requiring console authorization (GC, FK, GK, A0, etc.).
Logs	Full request/response log of all HSM traffic.

Secure Commands

Certain operations require console authorization before they can be executed, simulating the real PayShield security model.

Authorization Flow

Grant Authorization — In the Secure Commands tab, click the authorization button. This simulates inserting a custodian smart card.
Execute Commands — While authorized, you can run secure commands like GC, FK, GK, and LMK management operations.
Authorization Timeout — Authorization expires after a configurable period (default: 8 hours) or when manually revoked.

Secure Command List

The following commands are available in the Secure Commands tab:

Command	Name	Purpose
`NC`	Diagnostic Test	Verify HSM health.
`VR`	Version Info	Check firmware version.
`VT`	View LMK Table	Display all LMK KCVs.
`GK`	Generate LMK Component	Create LMK key component.
`GC`	Generate Key Components	Generate N random components for split knowledge.
`FK`	Form Key from Components	XOR components to form a key.
`A0`	Generate Key	Generate working keys under LMK.
`LA`	Load to Storage	Store data in HSM user storage.
`LE`	Read from Storage	Retrieve from user storage.
`LD`	Delete from Storage	Remove user storage entry.
`BW`	Translate Key	LMK migration — old to new LMK.
`DE`	Generate IBM PIN Offset	PIN issuance with IBM 3624.
`DG`	Generate VISA PVV	PIN issuance with VISA PVV.
`EI`	Generate RSA Key Pair	Asymmetric key generation.

Important

Attempting to run a secure command without authorization will return error code A1 (Console not authorized). Always grant authorization before executing these operations.