/ut-codec-payshield

Payshield codec

Primary LanguageJavaScriptOtherNOASSERTION

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