PIN/PINBlock tutorial
For clients who don't want a PIN (Personal Identification Number) transmitted as clear text, Pismo can handle it in PINBlock format. PINBlocks are 64-bit strings that encode a PIN ready for encryption and secure transmission in banking networks.
In this tutorial, without a Hardware Security Module (HSM), you are going to decrypt a PINBlock to get a clear text PIN and update a PIN using a PINBlock. The example code is written in Javascript and uses an external library called CryptoJS to support 3DES operations.
This tutorial assumes you have some familiarity with Node.js, Postman (a tool used for making API calls), and running commands at the command-line.
For this tutorial you need:
- Postman
- Node.js
- npm
- A server key and server secret for use in the Pismo sandbox environment in Postman
- One credit program to create a card
PIN/PINBlock endpoints
To test Pismo PINBlock endpoints:
Create a tutorial directory
> mkdir pismo-pin
> cd pismo-pin
Download PCIPINSecResources.zip and extract it to the tutorial directory
Install NPM dependencies
> npm install
Open Postman and import the collection file. Use the Sandbox environment.
Edit the collection variables with values for
server_key
,server_secret
, andprogram_ID
Execute Postman requests until you reach 7 - Get PIN as pinblock
Decrypt the PINBlock to retrieve the clear PIN
For this, use the JavaScript code downloaded in the second step. Run the following command:
> node index.js decryptPinblock "<PINBlock>" "<PAN>" "<Clear ZPK>"
For example:
> node index.js decryptPinblock "D04BCCEE7133CF01" "1234560057855917" "0404F2543B1C6E70AB61586E1304B6A7"
Example output:
see the plain text of the pinblock 0449c39ffa87aa6e see the pinblock part1 044986FFFFFFFFFF Plain PIN 4986 --------make-runnable-output-------- 4986
In a sandbox environment, a fixed ZPK (Zone Pin Key) is used where the value is
0404F2543B1C6E70AB61586E1304B6A7
. In production, the Pismo security team generates this ZPK and sends it to you.Update the card PIN using a PINBlock
Select a new PIN like "1234” and use it to generate a PINBlock using JavaScript:
> node index.js encryptPinblock "<NEW PIN> "<PAN>" "<Clear ZPK>"
For example:
> node index.js encryptPinblock "1234" "1234560057855917" "0404F2543B1C6E70AB61586E1304B6A7"
Example output:
pinblock 577E22088DE3AA1E --------make-runnable-output-------- 577E22088DE3AA1E
Run the Postman request 8 - Update PIN from PINBlock
You can reproduce the last step to retrieve the PIN as PINBlock and decrypt it to verify that the PIN has changed.
The index.js program uses CryptoJS, but you can code your own version of this using libraries that support 3DES in the most popular programming languages such as:
Note: During implementation, remember to always convert the ZPK and PINBlocks to uppercase.
Updated 12 months ago