Import Key (QC3IMPKY, Qc3ImportKey) API
Required Parameter Group:
| 1 | Key string | Input | Char(*) |
| 2 | Length of key string | Input | Binary(4) |
| 3 | Key form | Input | Char(1) |
| 4 | Key-encrypting key context token | Input | Char(8) |
| 5 | Key-encrypting algorithm context token | Input | Char(8) |
| 6 | Master key ID | Input | Binary(4) |
| 7 | Disallowed function | Input | Binary(4) |
| 8 | Master key KVV | Output | Char(20) |
| 9 | Imported key | Output | Char(*) |
| 10 | Length of area provided for imported key | Input | Binary(4) |
| 11 | Length of imported key returned | Output | Binary(4) |
| 12 | Error code | I/O | Char(*) |
Service Program Name: QC3KYIMP
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Import Key (OPM, QC3IMPKY; ILE, Qc3ImportKey) API encrypts a key under the specified master key.
Authorities and Locks
None.
Required Parameter Group
- Key string
- INPUT; CHAR(*)
The key to be encrypted under a master key. This can be a symmetric key or a PKA private key.
- Length of key string
- INPUT; BINARY(4)
Length of the key string specified in the key string parameter.
- Key form
- INPUT; CHAR(1)
An indicator specifying if the key string parameter is in encrypted form.
0 Clear.
The key string is not encrypted.1 Encrypted.
The key string is encrypted. The key-encrypting key context token and key-encrypting algorithm context token parameters are used to decrypt the key string before encrypting it under the specified master key.
- Key-encrypting key context token
- INPUT; CHAR(8)
The key context token specifying the key for decrypting the key string parameter. If the key string parameter is not encrypted (key form parameter is 0), this parameter must be set to blanks or the pointer to this parameter set to NULL.
- Key-encrypting algorithm context token
- INPUT; CHAR(8)
The algorithm context token specifying the algorithm for decrypting the key string parameter. If the key string parameter is not encrypted (key form parameter is 0), this parameter must be set to blanks or the pointer to this parameter set to NULL.
- Master key ID
- INPUT; BINARY(4)
The master key under which the specified key will be encrypted. For more information about master keys, refer to Cryptographic Services Master Keys. 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
- Disallowed function
- INPUT; BINARY(4)
This parameter specifies the functions that cannot be used with this key. The values listed below can be added together to disallow multiple functions. For example, to disallow everything but MACing, set the value to hex 11. This value should be saved along with the encrypted key value because it will be required when the encrypted key value is used on an API.
0 No functions are disallowed. 1 Encryption is disallowed. 2 Decryption is disallowed. 4 MACing is disallowed. 8 Signing is disallowed.
- Master key KVV
- OUTPUT; CHAR(20)
The key verification value of the master key that was used to encrypt the key. This value should be saved along with the encrypted key value. When the encrypted 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.
- Imported key
- OUTPUT; CHAR(*)
The area to store the imported key.
- Length of area provided for imported key
- INPUT; BINARY(4)
The length of the imported key parameter.
To ensure sufficient space, specify an area as large as the clear key string length plus space for padding. The key string will be encrypted using AES with a 32-byte block size. Therefore, the clear key string length will always be padded out to the next 32-byte boundary before encrypting.
- Length of imported key returned
- OUTPUT; BINARY(4)
The length of the imported key returned in the imported key parameter.
If the length of area provided for the imported key is too small, an error will be generated and no data will be returned in the imported key parameter. - Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Error Messages
| 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. |
| CPF9DAA E | A key requires translation. |
| CPF9DAB E | A key can not be decrypted. |
| CPF9DAC E | Disallowed function value not valid. |
| CPF9DAD E | The master key ID is not valid. |
| CPF9DAF E | &1 version of master key &2 is not set. |
| CPF9DC2 E | Key-encrypting algorithm context not compatible with key-encrypting key context. |
| CPF9DD6 E | Length of area provided for output data is too small. |
| CPF9DD7 E | The key-encrypting key context for the specified key is not valid or was previously destroyed. |
| CPF9DD8 E | The key-encrypting algorithm context for the specified key is not valid or was previously destroyed. |
| CPF9DDA E | Unexpected return code &1. |
| CPF9DDB E | The key string or Diffie-Hellman parameter string is not valid. |
| CPF9DDD E | The key string length is not valid. |
| CPF9DE8 E | Key form not valid. |
| 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. |
| CPF9DF7 E | Algorithm context not compatible with key context. |
| CPF9DFC E | The key-encrypting algorithm or key context token is not valid. |
API introduced: V5R4
[ Back to top | Cryptographic Services APIs | APIs by category ]