Scenario: Write an i5/OS application to use the Cryptographic Coprocessor

This scenario could help an i5/OS™ programmer reason through the process of writing a program that calls the Cryptographic Coprocessor to verify user data such as financial personal identification numbers (PINs), which are entered at automatic teller machines (ATMs).

Parent topic: Cryptographic Coprocessor scenarios
Related concepts
Secure access
Configure the Cryptographic Coprocessor

Situation

Suppose you are a system programmer for a large financial Credit Union. You have been assigned the task of getting a Cryptographic Coprocessor PCI card that is installed in the Credit Union system to verify members' financial personal identification numbers (PINs) when they are entered at automatic teller machines (ATMs).

You decide to write an i5/OS application program using the CCA CSP (cryptographic service provider) APIs that are a part of Option 35 to access the cryptographic services in the Cryptographic Coprocessors to verify members' PINs. i5/OS application programs written for the Cryptographic Coprocessor utilize the coprocessor to perform security-sensitive tasks and cryptographic operations.
Note: Multiple Cryptographic Coprocessors can be used via the CCA CSP. The application must control access to individual Coprocessor by using the Cryptographic_Resource_Allocate (CSUACRA) and Cryptographic_Resource_Deallocate (CSUACRD) CCA APIs.

Details

  1. A Credit Union member enters his or her PIN at an ATM.
  2. The PIN is encrypted at the ATM, and then sent along the network to the Credit Union's system.
  3. The system recognizes the transaction request, and calls a program to verify the member's PIN.
  4. The program sends a request containing the encrypted PIN, member's account number, PIN-generating key, and PIN encrypting key to the Cryptographic Coprocessor.
  5. The Cryptographic Coprocessor confirms or denies the validity of the PIN.
  6. The program sends the Cryptographic Coprocessor's results to the ATM.
    1. If the PIN is confirmed, the member can successfully complete a transaction with the Credit Union.
    2. If the PIN is denied, the member is unable to complete a transaction with the Credit Union.

Prerequisites and assumptions

  1. Your company has a system with a properly installed and configured Cryptographic Coprocessor. Refer to the following information:
    1. Plan for the Cryptographic Coprocessor
    2. Configure the Cryptographic Coprocessor
    3. Configure the Cryptographic Coprocessor for use with i5/OS applications
  2. You are familiar with Option 35: The Common Cryptographic Architecture Cryptographic Service Provider (CCA CSP). It is packaged as i5/OS Option 35, and provides a security application programming interface (SAPI) to which you can write applications that allow you to access the cryptographic services of the Cryptographic Coprocessor.
  3. You have access to the CCA Basic Services Guide Link outside Information Center., where you can find Financial Services Support verbs to use in your application.

Configuration steps

One way to accomplish your objective of using the Cryptographic Coprocessor to validate PINs is to write two i5/OS applications:

  1. Write a program that loads the both the PIN verification keys, and PIN encrypting keys, and stores them in a key store file. Assuming that clear key parts are used, you need to use the following APIs:
    • Logon_Control (CSUALCT)
    • Key_Part_Import (CSNBKPI)
    • Key_Token_Build (CSNBKTB)
    • Key_Record_Create (CSNBKRC)
    • Key_Record_Write (CSNBKRW)
    • Optional API: KeyStore_Designate (CSUAKSD)
  2. Write a second program that calls the Encrypted_PIN_Verify (CSNBPVR) API to verify encrypted PINs, and then reports their valid or invalid status back to the ATM.