Scenario: Key Management and File Encryption Using the Cryptographic Services APIs

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

Before reading this topic, you might want to review the information in the following topics:

• Cryptography concepts
• Cryptographic services key management

Briana is writing an application that handles customer data and accounts receivable. Because of recent privacy legislation, she needs to store the customer data encrypted.

Briana will store customer data encrypted in a database file. Each record will represent a different customer. Each record includes a customer unique number which is used as the database key field, an initialization vector which is used in the encrypt/decrypt operations, the accounts receivable balance, and the encrypted customer data.

The following is Briana's DDS for the customer file, which she names CUSDTA.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A* CUSTOMER FILE
     A*
     A          R CUSDTAREC                 TEXT('Customer record')
     A            CUSNUM         8  0       TEXT('Customer number')
     A            IV            16          TEXT('Initialization vector')
     A                                      CCSID(65535)
     A            ARBAL         10  2       TEXT('Accounts receivable balance')
     A            CUSDTA        80          TEXT('Encrypted customer data')
     A                                      CCSID(65535)
     A*                                            20    Name
     A*                                            20    Address
     A*                                            20    City
     A*                                             2    State
     A*                                             5    Zip Code 
     A*                                            10    Phone number
     A*                                             3    Pad 
     A          K CUSNUM
     A*

Briana has several choices for an encryption key (which we will call the file key).

• A clear key
• A keystore key
• A key encrypted under a clear key
• A key encrypted under a master key
• A key encrypted under a keystore key
• A key encrypted under a certificate store key
• A key derived from PKCS5 parameters
• Combinations of the above

Briana carefully thinks through the requirements of her application and the security implications. Her decision is to use a key encrypted under a keystore key. She will store the encrypted file key in a separate file called CUSPI. Although the file key is encrypted, Briana is still careful to restrict authority to CUSPI.

In addition to the encrypted file key, Briana needs to store the last used customer number. Following is Briana's DDS for the customer processing information file, CUSPI.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A* CUSTOMER PROCESSING INFORMATION
     A*
     A          R CUSPIREC                  TEXT('Customer processing info')
     A            KEY           16          TEXT('Encryption key')
     A                                      CCSID(65535)
     A            LASTCUS        8  0       TEXT('Last customer number')
     A*

Briana's application includes a program to setup and intialize the files and keys, a program that writes customer data to the CUSDTA file, and a program that bills customers. These programs are described below. Code examples for these programs are also provided. The scenarios below contain many references to Cryptographic Services APIs. Note that in V6R1 all the key management functions can be accomplished not only through the Cryptographic Services APIs, but also through the Cryptographic Services set of CL commands, and through the Cryptographic Services Key Management function in IBM^® Systems Director Navigator for IBM i.

Setup_Cus

The Setup_Cus program performs the following steps:

1. Create CUSDTA and CUSPI files.
2. Create keystore file CUSKEYFILE using the Create Keystore API.
3. Generate a KEK in CUSKEYFILE with a label of CUSDTAKEK using the Generate Key Record API.
4. Create a key context for CUSDTAKEK using the Create Key Context API.
5. Create an AES algorithm context for CUSDTAKEK using the Create Algorithm Context API.
6. Generate a file key encrypted under CUSDTAKEK using the Generate Symmetric Key API.
7. Write a record containing the encrypted file key and last customer number (set to 0) to file CUSPI.
8. Erase the encrypted file key value from program storage.
9. Destroy key context using the Destroy Key Context API.
10. Destroy algorithm context using the Destroy Algorithm Context API.

Examples

Here are example programs for Setup_Cus.

• Example in ILE C: Setting up keys
• Example in ILE RPG: Setting up keys

Write_Cus

The Write_Cus program performs the following steps:

1. Create an AES algorithm context for CUSDTAKEK using the Create Algorithm Context API.
2. Create a key context for CUSDTAKEK using the Create Key Context API.
3. Open the customer processing information file, CUSPI. (Return an error if the file does not exist.)
4. Read the first (and only) record from CUSPI to retrieve the encrypted file key and last customer number. (Return an error if record not found.)
5. Create a key context for the file key using the Create Key Context API.
6. Open the customer data file, CUSDTA, for update. (Return an error if the file does not exist.)
7. Call Get_Customer_Info to retrieve customer information and customer number. (If customer number = 0, it is a new customer. If customer number = 99999999, end the application.)
8. While customer number != 99999999.
9. Generate an IV using the Generate Pseudorandom Numbers API.
10. Encrypt the customer data using the Encrypt Data API.
    • If customer number = 0 (new customer)
      • Add one to last customer number.
      • Set customer number to last customer number.
      • Write the new record to CUSDTA file.
      Else
      • Read CUSDTA record using customer number as the database key. (Return error if record not found.)
      • Update record.
    • Call Get_Customer_Info.
11. Update last customer number in CUSPI.
12. Erase any customer plaintext data still in program storage.
13. Destroy key contexts using the Destroy Key Context API.
14. Destroy the algorithm context using the Destroy Algorithm Context API.
15. Close CUSDTA and CUSPI files.

Examples

Here are example programs for Write_Cus.

• Example in ILE C: Writing encrypted data to a file
• Example in ILE RPG: Writing encrypted data to a file

Bill_Cus

The Bill_Cus program performs the following steps:

1. Create an AES algorithm context for CUSDTAKEK using the Create Algorithm Context API.
2. Create a key context for CUSDTAKEK using the Create Key Context API.
3. Open the customer processing information file, CUSPI. (Return an error if the file does not exist.)
4. Read the first (and only) record from CUSPI to retrieve the encrypted file key. (Return an error if record not found.)
5. Create a key context for the file key using the Create Key Context API.
6. Erase the encrypted file key value from program storage.
7. Close CUSPI file.
8. Open the customer data file, CUSDTA, for sequential read.
9. Setup the algorithm description.
10. While not EOF
    • Read next record.
    • If accounts receivable balance > 0
      • Decrypt customer data using the Decrypt Data API.
      • Call Create_Bill, passing in the decrypted customer data and balance.
11. Erase any customer plaintext data still in program storage.
12. Destroy the key contexts using the Destroy Key Context API.
13. Destroy the algorithm context using the Destroy Algorithm Context API.
14. Close CUSDTA file.

Examples

Here are example programs for Bill_Cus.

• Example in ILE C: Reading encrypted data from a file
• Example in ILE RPG: Reading encrypted data from a file

Other Considerations

To backup file CUSDTA, you must backup files CUSPI and CUSKEYFILE as well. A perpetrator should not be able to use these files on another system because CUSDTAKEK is encrypted under a master key, and master keys should never be shared between systems. However, if the perpetrator has the ability to restore these files onto the orignal system and has access to the Decrypt Data API, he will be able to hack the customer data.

It is a good idea to periodically change the value of the master key. Whenever the master key is changed, CUSDTAKEK must be re-encrypted under the new master key value. You can do this with the Translate Keystore API. Remember to backup a keystore file whenever you re-encrypt the key values under a new master key.

---

[ Back to top | Cryptographic Services APIs | APIs by category ]