Retrieve Keystore Records (QC3RTVKS, Qc3RetrieveKeyStoreRecords) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Returned records feedback information | Output | Char(16) |
| 4 | Format name | Input | Char(8) |
| 5 | Qualified keystore file | Input | Char(20) |
| 6 | Error Code | I/O | Char(*) |
Service Program Name: QC3KSRTV
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Keystore Records (QC3RTVKS, Qc3RetrieveKeyStoreRecords) API provides information about the records stored in a keystore. It returns a list of keystore records and their attributes for a keystore file.
For more information about cryptographic services keystore files, see Cryptographic services key management.
Authorities and Locks
- Required file authority
- *OBJOPR, *READ
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable.
- Returned records feedback information
- OUTPUT; CHAR(16)
Information about the entries that are returned in the receiver variable.
See Format of Returned Records Feedback Information for details.
- Format name
- INPUT; CHAR(8)
The name of the format that is used to return information about the key records.
You can specify these formats:
KSRA0100 Each entry contains the record label, key type, key size, master key ID, master key verification value, the disallow function indicator specifying which functions cannot be used with this key, and the last modified date.
- Qualified keystore file name
- INPUT; CHAR(20)
The keystore file to list. 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.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Receiver Variable Description
The following tables describe the order and format of the data returned in the receiver variable for each record in the keystore file. For detailed descriptions of the fields in the tables, see Field Descriptions.
KSRA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(32) | Record label |
| 32 | 20 | BINARY(4) | Key type |
| 36 | 24 | BINARY(4) | Key size |
| 40 | 28 | BINARY(4) | Master key ID |
| 44 | 4C | BINARY(4) | Disallowed function |
| 48 | 30 | CHAR(14) | Last modified date |
| 62 | 38 | CHAR(20) | Master key verification value |
Format of Returned Records Feedback Information
For a description of the fields in this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of keystore records |
| 12 | C | BINARY(4) | Entry length for each record returned |
Field Descriptions
- Bytes available.
- The number of bytes of data available to be
returned to the user in the receiver variable.
If all data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was not big enough to contain all of the data, this value is estimated based on the total number of key records and the format specified. - Bytes returned.
- The number of bytes of data returned to the user in the receiver variable.
This is the lesser of the number of bytes available to be returned or the length of the receiver variable. - Disallowed function
- 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.
- Entry length for each record returned.
- The entry length, in bytes, of each element in the list of keystore records.
A value of zero is returned if the list is empty. - Key size
- Key size in bits.
- Key type
- 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 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
- Last modified date
- The date this key record was last modified, in YYYYMMDDHHMMSS format.
- 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 verification value
- 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 translated.
- Number of keystore records
- The number of keystore records returned in the reciever variable. If there is not enough room to fill in the whole format for a key record, it will still count as one.
- Record label
- The label of the key record. The label will be converted from CCSID 1200 (Unicode UTF-16) to the job CCSID, or if 65535, the job default CCSID (DFTCCSID) job attribute.
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: V6R1
[ Back to top | Cryptographic Services APIs | APIs by category ]