| 1 | Key string | Input | Char(*) |
| 2 | Length of key string | Input | Binary(4) |
| 3 | Key string format | Input | Char(1) |
| 4 | Key-encrypting key context token | Input | Char(8) |
| 5 | Key-encrypting algorithm context token | Input | Char(8) |
| 6 | Exported key | Output | Char(*) |
| 7 | Length of area provided for exported key | Input | Binary(4) |
| 8 | Length of exported key returned | Output | Binary(4) |
| 9 | Error code | I/O | Char(*) |
The Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey) API decrypts a key encrypted under a master key and re-encrypts it under the specified key-encrypting key.
Because this API could be used to recover the clear values of keys stored in keystore files, care should be taken to restrict access to this API.
A formatted structure identifying a key encrypted under a master key. The exact format of the key string is specified in the key string format parameter.
Length of the key string specified in the key string parameter.
Format of the key string parameter.
Following are the valid values.
| 3 | The key string parameter specifies a key value encrypted under a master key. The key string parameter should contain the following structure: |
Offset Type Field Dec Hex 0 0 BINARY(4) Master key ID 4 4 CHAR(4) Reserved 8 8 BINARY(4) Disallowed function 12 C CHAR(20) Master key KVV 32 20 CHAR(*) Encrypted key
Disallowed function- INPUT; BINARY(4)
This parameter specifies the functions that were not allowed to be used with this key. This value was XOR'd into the master key when the key was encrypted and therefore must be used in exporting the key. The values listed below can be added together to disallow multiple functions. For example, if the key only allowed MACing, this value would be 11.
0 No functions are disallowed. 1 Encryption is disallowed. 2 Decryption is disallowed. 4 MACing is disallowed. 8 Signing is disallowed.
- Encrypted key
- The encrypted key may be a symmetric key or a BER encoded PKCS #8 private key string encrypted under the specified master key.
- Master key ID
- The master key IDs are
1 Master key 1 2 Master key 2 3 Master key 3 4 Master key 4 5 Master key 5 6 Master key 6 7 Master key 7 8 Master key 8
- Master key KVV
- The 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 null, the current version of the master key will be used.
- Reserved
- Must be null (binary 0s).
| 4 | The key string parameter identifies a key in keystore. To create a key in keystore, use the Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API or the Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord) API. The key string parameter should contain the following structure: |
Offset Type Field Dec Hex 0 0 CHAR(20) Qualified keystore file name 20 14 CHAR(32) Record label 52 34 CHAR(4) Reserved
Qualified keystore file name- The keystore file where the key is stored. The first 10 characters contain the file name. The second 10 characters contain the name of the library where the keystore file is located. You can use the following special values for the library name.
*CURLIB The job's current library is used to locate the keystore file. If no library is specified as the current library for the job, the QGPL library is used. *LIBL The job's library list is searched for the first occurence of the specified file name.
- Record label
- The label of the key record. The label will be converted from the job CCSID, or if 65535, the job default CCSID (DFTCCSID) job attribute to CCSID 1200 (Unicode UTF-16).
- Reserved
- Must be null (binary 0s).
The token for the key context to use for encrypting the key.
The key context is created by using the Create Key Context
(OPM, QC3CRTKX; ILE, Qc3CreateKeyContext) API.
The token for the algorithm context to use for encrypting the key.
The algorithm context is created by using the Create
Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
The area to store the exported key. This parameter will contain the exported symmetric key or the exported PKCS #8 private key string.
The length of the exported key parameter.
Be sure to add any space necessary for padding.
If the encrypt mode of operation is CFB 1-bit, this length must be specified in
bits, otherwise it must be specified in bytes.
The length of the exported key returned in the exported key parameter.
If the length of area provided for the exported key is too small, an error will
be generated and no data will be returned in the exported key parameter.
If the encrypt mode of operation is CFB 1-bit, the length will be returned in
bits, otherwise it is returned in bytes.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Message ID | Error Message Text |
|---|---|
| CPF222E E | &1 special authority is required. |
| 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. |
| CPF9D98 D | Operation not valid for this key type. |
| CPF9D9F D | Not authorized to keystore file. |
| CPF9DA0 D | Error occured opening keystore file. |
| CPF9DA5 D | Keystore file not found. |
| CPF9DA6 D | The keystore file is not available. |
| CPF9DA7 D | File is corrupt or not a valid keystore file. |
| CPF9DAA D | A key requires translation. |
| CPF9DAB E | A key can not be decrypted. |
| CPF9DAC D | Disallowed function value not valid. |
| CPF9DAD E | The master key ID is not valid. |
| CPF9DB3 E | Qualified keystore file name not valid. |
| CPF9DB6 E | Record label not valid. |
| CPF9DB8 E | Error occured retrieving key record from keystore. |
| CPF9DC2 E | Key-encrypting algorithm context not compatible with key-encrypting key context. |
| CPF9DC3 E | Unable to decrypt data or key. |
| CPF9DD6 E | Length of area provided for output data is too small. |
| CPF9DDB E | The key string or Diffie-Hellman parameter string is not valid. |
| CPF9DDD E | The key string length is not valid. |
| CPF9DE9 E | Key format not valid. |
| CPF9DEE E | Reserved field not null. |
| CPF9DF1 E | The algorithm context token does not reference a valid algorithm context. |
| CPF9DF2 E | The algorithm context is not found or was previously destroyed. |
| CPF9DF3 E | Algorithm in algorithm context not valid for requested operation. |
| CPF9DF4 E | The key context token does not reference a valid key context. |
| CPF9DF5 E | The key context is not found or was previously destroyed. |
[ Back to top | Cryptographic Services APIs | APIs by category ]