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

• Get PIN as PINBlock

• Update PIN from PINBlock

To test Pismo PINBlock endpoints:

1. Create a tutorial directory

   > mkdir pismo-pin
> cd pismo-pin

2. Download PCIPINSecResources.zip and extract it to the tutorial directory
   

3. Install NPM dependencies

   > npm install

4. Open Postman and import the collection file. Use the Sandbox environment.

5. Edit the collection variables with values for server_key, server_secret, and program_ID

6. Execute Postman requests until you reach 7 - Get PIN as pinblock

7. 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.

8. 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

9. 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:

• Java
• C#
• Golang
• Javascript
• Python

Note: During implementation, remember to always convert the ZPK and PINBlocks to uppercase.