| 1 | Key string | Input | Char(*) |
| 2 | Length of key string | Input | Binary(4) |
| 3 | From master key ID | Input | Binary(4) |
| 4 | From KVV | Input | Char(20) |
| 5 | Disallowed function | Input | Binary(4) |
| 6 | To master key ID | Input | Binary(4) |
| 7 | Translated key | Output | Char(*) |
| 8 | To KVV | Output | Char(20) |
| 9 | Error code | I/O | Char(*) |
The Translate Key (OPM, QC3TRNKY; ILE, Qc3TranslateKey) API translates the specified key string to another master key, or if the same master key is specified, to the current version of the master key.
None.
A key encrypted under a master key. The encrypted key may be a symmetric key or a BER encoded PKCS #8 private key string encrypted under the From master key.
Length of the key string specified in the key string parameter.
The master key under which the key is currently encrypted. Specify a value in the range of 1-8 corresponding to the master key ID.
The From master key verification value. The master key version with a KVV that matches this value will be used to decrypt the key.
If this value is all blanks or the pointer to this parameter is null, the version used is dependent on the value of the To master key ID. If the To master key ID specifies a different master key than the From master key ID, the current version of the From master key will be used. If the To master key specifies the same master key ID as the From master key ID, the old version of the From master key will be used.
This parameter specifies the functions that were disallowed at the time the key was encrypted under the From master key. If the same value is not specified, the key will not decrypt correctly. The values listed below are added together to disallow multiple functions. For example, a value of 11 disallows everything but MACing.
| 0 | No functions are disallowed. |
| 1 | Encryption is disallowed. |
| 2 | Decryption is disallowed. |
| 4 | MACing is disallowed. |
| 8 | Signing is disallowed. |
The master key under which the key will be re-encrypted. Specify a value in the range of 1-8 corresponding to the master key ID.
The area to store the translated key. The length of the translated key will be the same length as the length of key string.
The To master key verification value. The key verification value of the master key that was used to encrypt the key is returned in this parameter. This value should be saved along with the translated key value. When the translated key value is used on an API and the KVV is supplied, the API will be able to determine which version of the master key should be used to decrypt the key. This field must be null (binary 0s) on input.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9D94 E | A pending value exists for a master key. |
| CPF9DAB E | A key can not be decrypted. |
| CPF9DAC D | Disallowed function value not valid. |
| CPF9DAD D | The master key ID is not valid. |
| CPF9DDA E | Unexpected return code &1. |
| CPF9DDB E | The key string is not valid. |
| CPF9DDD E | The key string length is not valid. |
[ Back to top | Cryptographic Services APIs | APIs by category ]