Consider a symmetric keystore entry with the following values:Figure 1. Sample symmetric keystore entry
Data is encrypted in the following figure:Figure 2. Data
encryption
Encryption steps:
The application issues the tpf_SHA1_Digest API
to create a message digest of the data to be encrypted.
The application issues the tpf_encrypt_data API
to encrypt data that will be written to file. The encryption key name
(MYKEY) that is hardcoded in the application program is passed as
input to the API.
The secure symmetric key usage user exit is called to verify that
the application program is allowed to use key MYKEY.
The secure key management code searches the symmetric memory keystore
to find (and validate) the active entry that has an encryption key
name of MYKEY.
The secure key management code invokes the CP Assist for Cryptographic Function (CPACF) to encrypt the data using the cipher (TDES) and
key ("KEY1") from the symmetric memory keystore entry.
Control is returned to the application program. The encrypted
data and decryption key name (MYDKEY1) from the symmetric memory keystore
entry are passed back to the application program.
The application program files a record containing the encrypted
data and decryption key name (MYDKEY1) to decrypt this data in the
future, and the message digest to ensure the integrity of the data.
Data from the previous figure is decrypted in the following figure:Figure 3. Data decryption
Decryption steps:
The application program reads a record containing the encrypted
data, decryption key name (MYDKEY1), and the message digest.
The application issues the tpf_decrypt_data API
to decrypt the data. The decryption key name (MYDKEY1) that was saved
in record is passed as input to the API.
The secure symmetric key usage user exit is called to verify that
the application program is allowed to use key MYDKEY1.
The secure key management code searches the symmetric memory keystore
to find (and validate) the entry that has a decryption key name of
MYDKEY1.
The secure key management code invokes the CPACF to decrypt the data using the cipher (TDES) and key
("KEY1") from the symmetric memory keystore entry.
Control is returned to the application program.
The application issues the tpf_SHA1_Digest API
to create a message digest of the data that was just decrypted. The
application compares the message digest just calculated to the saved
message digest and because the digest values match, the data has not
been corrupted and can be processed.
A new key is created and activated that changes the key value used
to encrypt data with encryption key name MYKEY from "KEY1" to "KEY2".
The symmetric keystore now contains two entries:Figure 4. Updated symmetric keystore entry
Data is encrypted using the new key value in the following figure:Figure 5. Data encryption with the new key value
