Before reading this information, review the information in Cryptographic Services Master Keys.
Cryptographic services keystore is a set of database files used for storing cryptographic keys. A keystore file is created using the Create Keystore (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 keystore file. Keys stored in a cryptographic services keystore file can be used with the cryptographic services APIs in operations on data or keys.
Keys are added to a keystore file using the Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKey Record) or Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API. Each record in a keystore file holds a key or key pair. When the keystore 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 keystore 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 keystore file is changed, the keys in that file must be re-encrypted. The Translate Keystore (OPM, QC3TRNKS; ILE, Qc3TranslateKeyStore) API can be used to translate keystore keys to another master key, or if the same master key is specified, to the current version of the master key.
When a keystore 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 keystore 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 Keystore API to re-encrypt the keystore file. If the KVV matches neither, an error is returned indicating the keystore key is outdated. It cannot be recovered unless the master key under which it is encrypted is restored.
After a keystore file is changed by adding keys or translating the key values, make a backup of the keystore file (e.g by using SAVOBJ).
To export keystore 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 keystore file.
[ Back to top | Cryptographic Services APIs | APIs by category ]