The eServer™ i5 server is capable of storing eight master keys, which cannot be directly modified or accessed by the user (including the security officer). These master keys are 256-bit AES keys and can be used with the cryptographic services APIs to protect other keys.
Each master key is composed of three 32-byte values, called versions. The versions are new, current, and old. The new master key version contains the value of the master key while it is being loaded. The current master key version contains the active master key value. This is the value that will be used when a master key is specified on a cryptographic operation (unless specifically stated otherwise). The old master key version contains the previous current master key version. It is used to prevent the loss of data and keys when the master key is changed.
The Load Master Key Part (OPM, QC3LDMKP; ILE, Qc3LoadMasterKeyPart) API loads a key part into the new master key version. To ensure no single person has the ability to reproduce a master key, assign different key parts to different individuals.
The Set Master Key (OPM, QC3SETMK; ILE, Qc3SetMasterKey) API copies the current master key version into the old master key version, copies the new master key version into the current master key version, and then clears the new master key version by setting it to binary 0s.
The current and old master key versions each have a 20-byte key verification value (KVV). The KVV is used to determine if the master key has changed. Use the Test Master Key (OPM, QC3TSTMK; ILE, Qc3TestMasterKey) API to retrieve the KVV values. In addition, if a KVV is associated with a key when that key is encrypted under a master key, the KVV can be used later to determine if the master key has changed, and if the encrypted key should be re-encrypted.
The Clear Master Key (OPM, QC3CLRMK; ILE, Qc3ClearMasterKey) API clears a new or old master key version by setting it to binary 0s.
Each of these APIs create a security CY audit record.
The server's master keys are not saved as part of a SAVSYS operation. Therefore, the passphrases used with Load Master Key Part should be saved so that a master key can be restored in the event it is lost. For example, the master keys will be destroyed when the licensed internal code is installed.
Whenever a master key is changed, all keys encrypted under that master key require re-encryption. For keystore files, use the Translate Keystore (OPM, QC3TRNKS; ILE, Qc3TranslateKeyStore) API. For keys stored outside a keystore file, use the Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey) then Import Key (OPM, QC3IMPKY; ILE, Qc3ImportKey) APIs. For more information about keystore files, refer to Cryptographic Services Keystore.
Whenever a key is encrypted under a master key, the KVV for the current version of the master key is returned. Keys encrypted under a master key can be stored in a keystore file, or stored at the discretion of the user. When a key is stored in a keystore file, the KVV of the master key is stored in the key record along with the key value. When a key encrypted under a master key is stored by the user, the user should also save the KVV. When a key encrypted under a master key is used on an API and the master key KVV is supplied, cryptographic services will check the supplied KVV against the master key versions' KVVs. If the supplied KVV matches the current version KVV, the operation will proceed normally. If the supplied KVV matches the old version KVV, the operation will proceed but return a diagnostic to the API and to QSYSOPR informing the user that the key needs retranslation. If the supplied KVV matches neither, the operation will end with an error.
[ Back to top | Cryptographic Services APIs | APIs by category ]