List Validation List Certificates (QSYLSTVC,QsyListVldlCertificates) API
Required Parameter Group for QSYLSTVC:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Validation list path name | Input | Char(*) |
| 3 | Length of path | Input | Binary(4) |
| 4 | Format name | Input | Char(8) |
| 5 | Selection control | Input | Char(*) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
Syntax for QsyListVldlCertificates:
#include <qsydigid.h>
void QsyListVldlCertificates
(char *Qualified_user_space_name,
char *Validation_list_path_name,
int Length_of_path,
char *Format_name,
char *Selection_control,
void *Error_code);
Service Program: QSYDIGIDDefault Public Authority: *USE
Threadsafe: Yes
The List Validation List Certificates (OPM, QSYLSTVC; ILE, QsyListVldlCertificates) API lists the certificates in the validation list. The generated list replaces any existing list in the user space.
There may be many certificates in a validation list. Because a user space has a defined maximum length, there may be more certificates in a validation list than can be put into the user space. The List Validation List Certificates API allows the caller to specify additional selection processing so that only the certificates in the validation list which have fields matching the caller's selections are to be listed in the user space. The information status field in the generic header is set to indicate if the results are complete or not.
Authorities and Locks
- Validation List Authority
- *USE
- Validation List Library Authority
- *Execute
- User Space Authority
- *CHANGE
- User Space Library Authority
- *USE
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The name of the existing user space used to return the list of validation list certificates. The first 10 characters specify the user space name, and the second 10 characters specify the library.
You can use these special values for the library name:
*CURLIB The current library is used to locate the user space. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the user space.
- Validation list path name
- INPUT; CHAR(*)
The fully qualified path name of the validation list.
- Length of path
- INPUT; BINARY(4)
The length of the validation list path name.
- Format name
- INPUT; CHAR(8)
The content and format of the information that is returned for each certificate in the list data section of the qualified user space name.
The possible formats are:
CERT0100 Certificates in Abstract Syntax Notation 1 (ASN.1) format CERT0200 Certificates in plain text format
- Selection control
- INPUT; CHAR(*)
The structure that contains strings which are used to limit which certificates are returned. For the format of the structure, see Selection Control.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Usage Notes
In the list data section, the Offset to EIM identifier, Length of EIM identifier, Offset to EIM local registry name, Length of EIM local registry name, Offset to user name, and Length of user name fields will be 0.
Format
The certificate list generated in the user space consists of:
- A user area
- A generic header
- An input parameter section
- A list data section
In the generic header, the offset and length of the header section are set to zero because the header section is not used. The list data section has variable length entries, so the size of each entry is set to 0 in the generic header. For details about the user area and generic header, including which field indicates the number of entries returned or the offset to the first entry, see User spaces.
For details about the formats in the list data section, see Certificate Format CERT0100 (ASN.1) and Certificate Format CERT0200 (Plain Text).
For details about the remaining items, see the following sections. For descriptions of each field in the list returned, see Field Descriptions.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | BINARY(4) | Offset to validation list path name |
| 24 | 18 | BINARY(4) | Length of validation list path name |
| 28 | 1C | CHAR(8) | Format name |
| 36 | 24 | BINARY(4) | Offset to selection control |
| CHAR(*) | Validation list path name | ||
| The offset to this selection control is specified in a previous offset variable. | BINARY(4) | Length of selection control | |
| BINARY(4) | Number of selection pairs | ||
| ARRAY(*) of BINARY(4) | Displacements to selection pairs | ||
| These fields repeat for each selection pair specified. | BINARY(4) | Length of selection pair | |
| CHAR(20) | Selection name | ||
| ARRAY(*) of CHAR | Selection value | ||
Field Descriptions
Displacements to selection pairs. An array of displacements to selection pairs from the beginning of the selection control.
Format name. The format of the returned output.
Length of selection control. The total number of bytes for the length itself, for the number of selection pairs, and for the array of displacements. It also includes the sum of the lengths of the selection pairs. The length of the selection control will vary due to the array of displacements and the selection pairs. A length of zero is one of the ways to indicate that no selection control pairs are specified.
Length of selection pair. The total length of the selection name and selection value fields and the bytes for the length itself. The length of the selection pair will vary due to the selection value. Valid values that are used are 24 or larger. A value of 24 corresponds to a selection value that is empty and means that certificates should be returned when the corresponding value in the certificate is also empty or not recognized.
Length of validation list path name. The length of the path name of the validation list that is specified in the call to the API.
Number of selection pairs. The number of separate selection pairs in the generated list of certificates. All of the selection pairs must be satisfied for each certificate that is returned. If the number of selection pairs is 0, then all certificates are returned.
Offset to selection control. The offset to the selection control. The first field of the selection control is the length of selection control.
Offset to validation list path name. The offset to the full path name of the validation list that is specified in the call to the API.
Selection name. The selection that is used to limit which certificates from the validation list are returned. Selections made here indicate which field of the certificate is to be examined for a matching selection value. Selection names cannot be specified more than once. Selection names are defined with length QSY_SELCTRL_NAME_LEN.
Valid selection names are:
| COMMONNAME | Client's common name |
| COUNTRY | Country or region in which the client resides |
| LOCALITY | Locality in which the client resides |
| STATEORPROVINCE | State or province in which the client resides |
| ORGANIZATION | Organization of the client |
| ORGANIZATIONALUNIT | Organizational unit of the client |
| PUBLICKEY | Public key of the certificate. This value is not text. It is the entire public key information as found in the certificate in ASN.1 DER format and it includes the tags and lengths. The actual public key found in the certificate is compared with the specified selection value that corresponds with this selection name. It is not returned in the list data section when the CERT0200 format name is specified. |
| EXPIRATIONDAYS | Certificates that are expired or will expire in the specified number of days. This value will be the number of days in character format (zoned decimal). |
| CERTIFICATEHANDLE | Handle for the certificate. |
Selection value. The array of characters that is used for matching the corresponding field of the certificate. A match in the certificate indicates that the certificate is of interest. If the certificate does not contain matching characters in its corresponding field, the certificate will not be returned as part of the list. The length of the selection value can be determined by subtracting the fixed lengths of the selection name field and the length field from the length of selection pair. The comparison of the fields is done in the CCSID of the job and is case sensitive.
User space library name specified. The library that contains the user space, as specified in the call to the API.
User space name specified. The name of the user space.
Validation list path name. The path name of the validation list.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPFA09C E | Not authorized to object. |
| CPF1F41 E | Severe error occurred while addressing parameter list. |
| CPF227B E | Certificate is not correct for the specified type. |
| CPF227E E | Selection control is not valid. |
| CPF3BFF E | Required option &1 is not available. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9810 E | Library &1 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R2
[ Back to top | Security APIs | APIs by category ]