Retrieve Key Record Attributes (QC3RTVKA, Qc3RetrieveKeyRecordAtr) API
Required Parameter Group:
| 1 | Qualified keystore file name | Input | Char(20) |
| 2 | Record label | Input | Char(32) |
| 3 | Key type | Output | Binary(4) |
| 4 | Key size | Output | Binary(4) |
| 5 | Master key ID | Output | Binary(4) |
| 6 | Master key verification value | Output | Char(20) |
| 7 | Disallowed function | Output | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Service Program Name: QC3KARTV
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Key Record Attributes (OPM, QC3RTVKA; ILE, Qc3RetrieveKeyRecordAtr) API returns the key type and key size of a key stored in a keystore file. It also identifies the master key under which the stored key is encrypted and the master key's KVV.
For more information about cryptographic services keystore, see Cryptographic services key management.
Authorities and Locks
- Required file authority
- *OBJOPR, *READ
Required Parameter Group
- Qualified keystore file name
- INPUT; CHAR(20)
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 key store 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
- INPUT; CHAR(32)
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).
- Key type
- OUTPUT; BINARY(4)
The type of key.
The output values have the following meanings.1 MD5
2 SHA-1
3 SHA-256
4 SHA-384
5 SHA-512
7 SHA-224
20 DES
21 Triple DES
22 AES
23 RC2
30 RC4-compatible
50 RSA public
51 RSA public and private
56 ECC public
57 ECC public and private
- Key size
- OUTPUT; BINARY(4)
Key size in bits.
- Master key ID
- OUTPUT; BINARY(4)
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 verification value
- OUTPUT; CHAR(20)
The KVV for the master key at the time the key was encrypted. This can be compared with the current master key KVV to determine if the key must be re-encrypted.
- Disallowed function
- OUTPUT; BINARY(4)
The functions that cannot be used with this key. The values listed below can be added together to disallow multiple functions. For example, a key that disallows everything but MACing would have a value of 11.
0 No functions are disallowed. 1 Encryption is disallowed. 2 Decryption is disallowed. 4 MACing is disallowed. 8 Signing is disallowed.
- 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. |
| CPF9D9F E | Not authorized to keystore file. |
| CPF9DA0 E | Error occured opening keystore file. |
| CPF9DA1 E | Key record not found. |
| CPF9DA5 E | Keystore file not found. |
| CPF9DA6 E | The keystore file is not available. |
| CPF9DA7 E | File is corrupt or not a valid keystore file. |
| CPF9DB3 E | Qualified keystore file name not valid. |
| CPF9DB6 E | Record label not valid. |
| CPF9DB8 E | Error occured retrieving key record from keystore. |
API introduced: V5R4
[ Back to top | Cryptographic Services APIs | APIs by category ]