Retrieve Keystore File Attributes (QC3RTVFA, Qc3RetrieveKeyStoreFileAtr) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format | Input | Char(8) |
| 4 | Qualified keystore file name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
Service Program Name: QC3FARTV
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Keystore File Attributes (OPM, QC3RTVFA; ILE, Qc3RetrieveKeyStoreFileAtr) API returns for the specified keystore file the number of key records, the id of the master key used to encrypt the key values, the date and time the keystore file was created or last translated, and the translation status of the keys.
For more information about cryptographic services keystore, see Cryptographic services key management.
Authorities and Locks
- Required file authority
- *OBJOPR, *READ
- Required library authority
- *EXECUTE
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable used to receive the information about the keystore file. 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. The format of the information returned in the receiver variable is defined by the format parameter
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. This value must be at least 8. The length of receiver variable parameter may be specified up to the allocated 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, the results are not predictable.
- Format
- INPUT; CHAR(8)
The format of the data returned in the receiver variable.
The following value is allowed:
KSFA0100 Keystore file attributes
- 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.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Receiver Variable
The following table describes the format of the receiver variable.
For detailed descriptions of the fields in this table, see Field Descriptions.
KSFA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of key records |
| 12 | C | BINARY(4) | Master key |
| 16 | 10 | CHAR(14) | Date and time |
| 30 | 1E | CHAR(1) | Reserved |
| 31 | 1F | CHAR(1) | Translation status |
Field Descriptions
Bytes available. The number of bytes of data available to return in the receiver variable.
If the bytes available field is larger than the bytes returned field, all of the keystore file information will not be included in the receiver variable.
Bytes returned. The number of bytes of data returned in the receiver variable.
Date and time. The date and time the keystore file was last translated, or if never translated, the file creation date and time. The date and time field is in the YYYYMMDDHHMMSS format as follows:
| YYYY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
Master key. The id of the master key that will be used to encrypt any future keys added to the keystore file.
Number of key records. The number of keys currently stored in the keystore file.
Reserved. Must be null (binary 0's).
Translation status. The translation status of the key values.
| 0 | Translation status of the keys
is unknown. This may occur because an error occurred during processing of the file. |
| 1 | All keys in the keystore file are current. |
| 2 | The keystore file contains keys requiring translation. This means the master key was changed since the key values were added or last translated. The keys are useable but will become lost if the master key is again changed. Use the Translate Keystore (QC3TRNKS, Qc3TranslateKeyStore) API to translate the key values under the current version of the master key. |
| 3 | The keystore file contains lost keys. This means the master key was changed at least twice since the key values were added or last translated. A lost key value (and all data encrypted under the key) cannot be recovered until the master key is recovered. First, use the Translate Keystore (QC3TRNKS, Qc3TranslateKeyStore) API to ensure all the other keys are translated under the current version of the master key. Then restore the old master key value by using the Load Master Key Part (QC3LDMKP, Qc3LoadMasterKeyPart) API and the Set Master Key (QC3SETMK, Qc3SetMasterKey) API. Then use the Translate Keystore API again. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| 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. |
| 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. |
| CPF9DB8 E | Error occured retrieving key record from keystore. |
API introduced: V6R1
[ Back to top | Cryptographic Services APIs | APIs by category ]