Cryptographic Services Key Store

Before reading this information, review the information in Cryptographic Services Master Keys.

Cryptographic services key store is a set of database files used for storing cryptographic keys. A key store file is created using the Create Key Store (OPM, QC3CRTKS; ILE, Qc3CreateKeyStore) API. Any type of key supported by cryptographic services (e.g. DES, RC2, RSA, MD5-HMAC) can be stored in a key store file. Keys stored in a cryptographic services key store file can be used with the cryptographic services APIs in operations on data or keys.

Keys are added to a key store file using the Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKey Record) or Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API. Each record in a key store file holds a key or key pair. When the key store file is created, the user specifies the master key under which the key values will be encrypted before storing (except for RSA public key values which are stored in plaintext.) Besides the key value, the record contains the key type (e.g. TDES, AES, RSA), the key size, the key verification value (KVV) of the master key at the time the key value was encrypted, and a label. All fields in the key store record are stored as CCSID 65535 except for the record label. The record label will be converted from the job CCSID or the job default CCSID to Unicode UTF-16 (CCSID 1200).

Use the Retrieve Key Record Attributes (OPM, QC3RTVKA; ILE, Qc3RetrieveKeyRecordAtts) API to retrieve the key type, key size, master key ID, and KVV for a given key record.

If a master key for a key store file is changed, the keys in that file must be re-encrypted. The Translate Key Store (OPM, QC3TRNKS; ILE, Qc3TranslateKeyStore) API can be used to translate key store keys to another master key, or if the same master key is specified, to the current version of the master key.

When a key store key is used, the KVV stored in the record is compared with the KVVs for the master key to determine under which version of the master key the key store key is encrypted. If the KVV matches the current version KVV, the operation proceeds normally. If the KVV matches the old version KVV, the operation proceeds but a warning is issued. The user should use the Translate Key Store API to re-encrypt the key store file. If the KVV matches neither, an error is returned indicating the key store key is outdated. It cannot be recovered unless the master key under which it is encrypted is restored.

After a key store file is changed by adding keys or translating the key values, make a backup of the key store file (e.g by using SAVOBJ).

To export key store keys to another system, use the Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey) API which will return the key value encrypted under another key. Because this API can be used to obtain clear key values, care should be taken to restrict access to this API.

Delete Key Record (OPM, QC3DLTKR; ILE, Qc3DeleteKeyRecord) API deletes a key record from a key store file.