Payshield Codec

Scope

Encode/decode Payshield messages to/from buffer

Public API

The module exposes PayshieldCodec class.

decode

(buff, $meta, context, log)

Decodes data buffer to JSON object

params

• buff (buffer) - data buffer to be decoded
• $meta (object) - $meta object as defined in ut-port
• context (object) - context object as defined in ut-port-tcp
• log (object) - contains log functions; for more information, please refer to ut-log documentation

result

• (object) - decoded buff

encode

(data, $meta, context, log)

Encodes JSON object data to buffer

params

• data (object) - data object to be encoded; NOTE: all strings will be converted toUpperCase before encoding, unless otherwise specified in nonCorrectableFields object (see Configuration below)
• $meta (object) - $meta object as defined in ut-port
• context (object) - context object as defined in ut-port-tcp
• log (object) - contains log functions; for more information, please refer to ut-log documentation

result

• (buffer) - encoded data

Defining new commands

Each command should be described in messages.json in the following way:

• commandName (object) - name of the method which will be exposed in payshield namespace
  • requestCode (string) - Command Code for this command as defined in Payshield Host Command Reference Manual
  • responseCode (string) - Response Code for this command as defined in Payshield Host Command Reference Manual
  • requestPattern (string) - request pattern definition for PayshieldCodec encode method; NOTE: for more information of pattern definitions, please refer to ut-bitsyntax documentation
  • responsePattern (string) - response pattern definition for PayshieldCodec decode method; NOTE: for more information of pattern definitions, please refer to ut-bitsyntax documentation
  • warnings (array) - array with error codes to be processed as warnings instead of errors for this command only; NOTE: for list of error codes, please refer to Available Payshield commands, command specific error codes, command specific warnings below
    • (string) - error code to be processed as warning
  • customResponseError (object) - key: value pairs object to define new error codes, or to overwrite existing standard error codes for this command only
    • key - error code
    • value - error description

Available Payshield commands, command specific error codes, command specific warnings

A0 (A1)

Generate a Key

• error codes
  • 10: ZMK or TMK Parity error

A4 (A5)

Form a Key from Encrypted Components

• error codes
  • 03: Invalid number of components
  • 10: Component parity error

A6 (A7)

Import a Key

• error codes

  • 10: ZMK Parity error

• warnings

  • 01: Key parity error, advice only

A8 (A9)

Export a Key

• error codes
  • 10: ZMK or TMK Parity error
  • 11: Key parity error

B2 (B3)

Echo Command

BG (BH)

Translate a PIN and PIN Length

BK (BL)

Generate an IBM PIN Offset (of a customer selected PIN)

• error codes

  • 03: Excluded PIN count incorrect
  • 10: TPK or ZPK parity error
  • 11: PVK parity error
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

• warnings

  • 02: Warning PVK not single length

BS (BT)

Erase the Key Change Storage

BU (BV)

Generate a Key Check Value

• error codes
  • 10: Key parity error

BW (BX)

Translate Keys from Old LMK to New LMK and Migrate to New Key Type

• error codes
  • 04: Invalid key type code
  • 05: Invalid key length flag
  • 10: Key parity error
  • 44: Migration not allowed: 'Enforce key type 002 separation for PCI HSM compliance' not set
  • 45: Invalid key migration destination key type

CA (CB)

Translate a PIN from TPK to ZPK/BDK (3DES DUKPT) Encryption

• error codes
  • 10: Source TPK parity error
  • 11: Destination ZPK parity error

CC (CD)

Translate a PIN from one ZPK to another

• error codes
  • 10: Source ZPK parity error
  • 11: Destination ZPK parity error

CU (CV)

Verify a PIN & Generate an ABA PVV (of a customer selected PIN)

• error codes
  • 01: PIN Verification failure
  • 10: PIN Block Key parity error
  • 11: PVK parity error
  • 27: PVK not double length
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

CW (CX)

Generate a Card Verification Code/Value

• error codes
  • 10: CVK A or CVK B parity error
  • 27: CVK not double length

CY (CZ)

Verify a Card Verification Code/Value

• error codes
  • 01: CVV failed verification
  • 10: CVK A or B parity error
  • 27: CVK not double length

DA (DB)

Verify a Terminal PIN Using the IBM Offset Method

• error codes

  • 01: PIN Verification failure
  • 10: TPK parity error
  • 11: PVK parity error

• warnings

  • 02: Warning PVK not single length

DC (DD)

Verify a Terminal PIN Using the ABA PVV Method

• error codes
  • 01: PIN verification failure
  • 10: TPK parity error
  • 11: PVK parity error
  • 27: PVK not double length

DE (DF)

Generate an IBM PIN Offset (of an LMK encrypted PIN)

• error codes

  • 10: PVK parity error
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

• warnings

  • 02: Warning PVK not single length

DG (DH)

Generate an ABA PVV (of an LMK encrypted PIN)

• error codes
  • 10: PVK parity error
  • 27: PVK not double length
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

DU (DV)

Verify a PIN & Generate an IBM PIN Offset (of customer selected new PIN)

• error codes

  • 01: PIN verification failure
  • 10: PIN Block Key parity error
  • 11: PVK parity error
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

• warnings

  • 02: Warning PVK not single length

EA (EB)

Verify an Interchange PIN Using the IBM Offset Method

• error codes

  • 01: PIN verification failure
  • 10: ZPK parity error
  • 11: PVK parity error

• warnings

  • 02: Warning PVK not single length

EC (ED)

Verify an Interchange PIN Using the ABA PVV Method

• error codes
  • 01: PIN verification failure
  • 10: ZPK parity error
  • 11: PVK parity error
  • 27: PVK not double length

EE (EF)

Derive a PIN Using the IBM Offset Method

• error codes

  • 10: PVK parity error
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

• warnings

  • 02: Warning PVK not single length

EI (EJ)

Generate a public/private key pair.

• error codes
  • 03: Invalid public key encoding type
  • 04: Key Length error
  • 05: Invalid key type
  • 06: Public exponent length error
  • 08: Supplied public exponent is even
  • 47: Algorithm not licensed
  • 48: Stronger LMK required to protect this size RSA key
  • 68: Command disabled

EW (EX)

Generate a public/private key pair.

• error codes
  • 03: Invalid private key type
  • 04: Invalid private key flag
  • 05: Invalid hash identifier
  • 06: Invalid signature identifier
  • 07: Invalid pad mode identifier
  • 47: Algorithm not licensed
  • 68: Command disabled
  • 74: Invalid digest info syntax (no-hash mode only)
  • 76: Hash length error
  • 78: Private key length error
  • 80: Message length error or a standard error code.

FM (FN)

Translate a ZEK/ZAK from LMK to ZMK Encryption

FW (FX)

Generate an ABA PVV (of a customer selected PIN)

• error codes
  • 10: PVK parity error
  • 27: PVK not double length
  • 81: PIN length mismatch
  • 86: PIN exists in either global or local Excluded PIN Table

G0 (G1)

Translate a PIN from BDK to BDK or ZPK Encryption (3DES DUKPT)

• error codes
  • 10: BDK parity error
  • 11: Interchange key parity error
  • 27: BDK not double or triple length

GM (GN)

Hash a Block of Data

• error codes
  • 05: Invalid hash identifier

GO (GP)

Verify a PIN Using the IBM Offset Method (3DES DUKPT)

• error codes

  • 01: PIN Verification failure
  • 10: BDK parity error
  • 11: PVK error
  • 27: BDK not double length
  • 68: Command disabled

• warnings

  • 02: Warning PVK not single length

GQ (GR)

Verify a PIN Using the ABA PVV Method (3DES DUKPT)

• error codes
  • 01: PIN Verification failure
  • 10: BDK parity error
  • 11: PVK error
  • 27: BDK not double or triple length

GW (GX)

Generate/Verify a MAC (3DES DUKPT)

• error codes
  • 01: MAC Verification Failure

JA (JB)

Generate a Random PIN

• error codes
  • 81: PIN length mismatch

JC (JD)

Translate a PIN from TPK to LMK Encryption

• error codes
  • 10: TPK parity error

JE (JF)

Translate a PIN from ZPK to LMK Encryption

• error codes
  • 10: ZPK parity error

JG (JH)

Translate a PIN from LMK to ZPK Encryption

• error codes
  • 10: ZPK parity error

KQ (KR)

ARQC Verification and/or ARPC Generation (Using Static or MasterCard Proprietary SKD Method)

• error codes
  • 01: ARQC/TC/AAC verification failed
  • 03: Mode = 3 or 4 but Scheme ID ≠ 0
  • 04: Invalid Mode value
  • 05: Unrecognized Scheme ID
  • 06: Discretionary MAC verification failed
  • 10: MK-AC parity error
  • 11: MK-SMI parity error
  • 80: Transaction Data length error
  • 81: Zero length Transaction Data
  • 82: Invalid Discretionary MAC Data length

KW (KX)

ARQC Verification and/or ARPC Generation (Using EMV or Cloud-Based SKD Methods)

• error codes
  • 01: ARQC/TC/AAC/MPVV verification failure
  • 04: Unrecognized Mode Flag
  • 05: Unrecognized Scheme ID
  • 06: Invalid YHHHHCC value
  • 10: MK parity error
  • 52: Invalid Branch/Height

LO (LP)

Translate Decimalisation Table from Old to New LMK

M0 (M1)

Encrypt Data Block

• error codes
  • 02: Invalid Mode Flag field
  • 03: Invalid Input Format Flag field
  • 04: Invalid Output Format Flag field
  • 05: Invalid Key Type field
  • 06: Invalid Message Length field
  • 10: Encryption Key Parity Error
  • 35: Illegal Message Format

M2 (M3)

Decrypt Data Block

• error codes
  • 02: Invalid Mode Flag field
  • 03: Invalid Input Format Flag field
  • 04: Invalid Output Format Flag field
  • 05: Invalid Key Type field
  • 06: Invalid Message Length field
  • 10: Decryption Key Parity Error
  • 35: Illegal Message Format

M4 (M5)

Translate Data Block

• error codes
  • 02: Invalid Mode Flag field
  • 03: Invalid Input Format Flag field
  • 04: Invalid Output Format Flag field
  • 05: Invalid Key Type field
  • 06: Actual Message Length is too Short
  • 07: Invalid Destination Mode Flag Field
  • 08: Invalid destination Key Type Field
  • 10: Decryption Key Parity Error
  • 11: Encryption Key Parity Error
  • 15: Actual Message Length is too Long
  • 35: Illegal Message Format

M6 (M7)

Generate MAC

• error codes
  • 02: Invalid Mode Flag field
  • 03: Invalid Input Format Flag field
  • 04: Invalid MAC Algorithm field
  • 05: Invalid Key Type field
  • 06: Invalid Message Length field
  • 09: Invalid Padding Method field
  • 10: MAC Key Parity Error

M8 (M9)

Verify MAC

• error codes
  • 01: MAC verification failed
  • 02: Invalid Mode Flag field
  • 03: Invalid Input Format Flag field
  • 04: Invalid MAC Algorithm field
  • 05: Invalid Key Type field
  • 06: Invalid Message Length field
  • 09: Invalid Padding Method field
  • 10: MAC Key Parity Error

PA (PB)

Load Formatting Data to HSM

PC (PD)

Load Additional Formatting Data to HSM

PE (PF, PZ)

Print PIN/PIN and Solicitation Data

• error codes (PZ)
  • 16: Printer not ready/disconnected
  • 41: Internal hardware/software error

QK (QL)

Translate Account Number for LMK-encrypted PIN

TA (TB, TZ)

Print TMK Mailer

• error codes (TB)

  • 10: TMK parity error

• error codes (TZ)

  • 16: Printer time out

Standard error codes

• 10: Source key parity error
• 11: Destination key parity error or key all zeros
• 12: Contents of user storage not available. Reset, power-down or overwrite
• 13: Invalid LMK Identifier
• 14: PIN encrypted under LMK pair 02-03 is invalid
• 15: Invalid input data (invalid format, invalid characters, or not enough data provided)
• 16: Console or printer not ready or not connected
• 17: HSM not in the Authorised state, or not enabled for clear PIN output, or both
• 18: Document format definition not loaded
• 19: Specified Diebold Table is invalid
• 20: PIN block does not contain valid values
• 21: Invalid index value, or index/block count would cause an overflow condition
• 22: Invalid account number
• 23: Invalid PIN block format code
• 24: PIN is fewer than 4 or more than 12 digits in length
• 25: Decimalisation Table error
• 26: Invalid key scheme
• 27: Incompatible key length
• 28: Invalid key type
• 29: Key function not permitted
• 30: Invalid reference number
• 31: Insufficient solicitation entries for batch
• 33: LMK key change storage is corrupted
• 39: Fraud detection
• 40: Invalid checksum
• 41: Internal hardware/software error: bad RAM, invalid error codes, etc.
• 42: DES failure
• 47: Algorithm not licensed
• 49: Private key error, report to supervisor
• 51: Invalid message header
• 65: Transaction Key Scheme set to None
• 67: Command not licensed
• 68: Command has been disabled
• 69: PIN block format has been disabled
• 74: Invalid digest info syntax (no hash mode only)
• 75: Single length key masquerading as double or triple length key
• 76: Public key length error
• 77: Clear data block error
• 78: Private key length error
• 79: Hash algorithm object identifier error
• 80: Data length error. The amount of MAC data (or other data) is greater than or less than the expected amount.
• 81: Invalid certificate header
• 82: Invalid check value length
• 83: Key block format error
• 84: Key block check value error
• 85: Invalid OAEP Mask Generation Function
• AB: Invalid number of optional blocks
• AC: Optional header block error
• AD: Key status optional block error
• AE: Invalid start date/time
• AF: Invalid end date/time
• B0: Invalid encryption mode
• B1: Invalid authentication mode
• B2: Miscellaneous keyblock error
• B3: Invalid number of optional blocks
• B4: Optional block data error
• B5: Incompatible components
• B6: Incompatible key status optional blocks
• B7: Invalid change field
• B8: Invalid old value
• B9: Invalid new value
• BA: No key status block in the keyblock
• BB: Invalid wrapping key
• BC: Repeated optional block
• BD: Incompatible key types

Configuration

• headerFormat (string) - defines the length and data type of the message header in format length/data type; NOTE: for more information of the format definitions, please refer to ut-bitsyntax documentation
• messageFormat (object) - may contain new command definitions, or definitions of existing commands to be overwritten, or parts of existing commands to be overwritten; NOTE: for more information of command definitions, please refer to Defining new commands above
• maskedKeys (array) - request/response keys for which the values to be masked in the log records
  • (string) - key for which the value will be masked in log records
• nonCorrectableFields (object) - each key: value pair contains the following:
  • key - field name
  • value (bool) - flags if key in requests should be left as it is (true) or converted toUpperCase (false, undefined/not present) before encoding