List User Certificates (QSYLSTUC, QsyListUserCertificates) API
Required Parameter Group for QSYLSTUC:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | User name | Input | Char(*) |
| 3 | Format name | Input | Char(8) |
| 4 | Selection control | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
Syntax for QsyListUserCertificates:
#include <qsydigid.h>
void QsyListUserCertificates
(char *Qualified_user_space_name,
void *User_name,
char *Format_name,
char *Selection_control,
void *Error_code);
Service Program: QSYDIGIDDefault Public Authority: *USE
Threadsafe: Yes
The List User Certificates (OPM, QSYLSTUC; ILE, QsyListUserCertificates) API lists the certificates that are associated with the user profile. The generated list replaces any existing list in the user space.
A common scenario is that only one certificate is associated with an IBM i user profile at any given time, but more than one certificate may be associated with the same IBM i user profile if each certificate is unique. The same certificate is not allowed to be associated with more than one IBM i user profile.
Because certificates vary in length, the actual number of certificates that can be returned using the List User Certificates API will also vary. The total length of all of the certificates that have been added and the size of the user space determine the actual number that can be returned. In general, if more than a few hundred certificates are associated with an IBM i user profile partial results may be returned when attempting to use the List User Certificates API to list the certificates. In addition to this maximum that varies due to certificate lengths, the List User Certificates API will not list more than 1000 certificates per user profile, no matter how small the certificates are for the user profile.
Selection control pairs that the caller may specify to do additional processing of the list may be useful for a user space that is smaller than the maximum size of a user space when the caller does not have authority to change the size of the user space. If more certificates are associated with an IBM i user profile than can be returned by the List User Certificates API, the information status field in the generic header is set to indicate that the results are partial or incomplete.
Authorities and Locks
- User Profile Authority
- *USE
- If *ALL is specified for the user profile name, the caller of this API must have *ALLOBJ special authority
- If an EIM identifier is specified for the user profile name, the caller of this API must have *ALLOBJ special authority
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The name of the existing user space used to return the list of user 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.
- User name
- INPUT; CHAR(*)
The name of the user profile or the Enterprise Identity Mapping (EIM) identifier.
The following are valid selections:
*CURRENT The user profile that is currently running. The value must be 10 characters, blank padded. *ALL All user profiles on this system. The value must be 10 characters, blank padded. user profile The name of the user profile. The value must be 10 characters, blank padded. EIM identifier To specify an EIM identifier for this parameter, the data must have the following format: char(8) The special value *EIMID. binary(4) The hex length of the EIM identifier. char(*) The EIM identifier.
- 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 format names are:
CERT0100 Certificates in ASN.1 format CERT0200 Certificates in plain text format
- Selection control
- INPUT; CHAR(*)
The structure that contains strings of interest and is used to limit which certificates are returned. For the format of this 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.
Format
The certificate list generated in the user space consists of the following:
- 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 | BINARY(4) | Bytes returned in the returned records feedback information |
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(10) | User name |
| 30 | 1E | CHAR(8) | Format name |
| 38 | 26 | CHAR(2) | Reserved |
| 40 | 28 | BINARY(4) | Offset to selection control |
| 44 | 2C | BINARY(4) | Offset to EIM identifier |
| 48 | 30 | BINARY(4) | Length of EIM identifier |
| 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 | ||
| CHAR(*) | EIM identifier | ||
List Data Section
The list data section consists of certificates that are all set to one of the following formats as specified in the call to the API. The generic header has the number of list entries field.
Certificate Format CERT0100 (ASN.1)
The CERT0100 format consists of a certificate handle and the entire certificate encoded in ASN.1 DER (Abstract Syntax Notation 1 Distinguished Encoding Rules) format. The fields specified by the offsets and lengths in this format are not text fields.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Returned length of this certificate and format information |
| 4 | 4 | BINARY(4) | Available length of this certificate and format information |
| 8 | 8 | BINARY(4) | Offset to certificate handle |
| 12 | C | BINARY(4) | Length of certificate handle |
| 16 | 10 | BINARY(4) | Offset to ASN.1 format certificate |
| 20 | 14 | BINARY(4) | Length of ASN.1 format certificate |
| 24 | 18 | BINARY(4) | Offset to EIM identifier |
| 28 | 1C | BINARY(4) | Length of EIM identifier |
| 32 | 20 | BINARY(4) | Offset to EIM local registry name |
| 36 | 24 | BINARY(4) | Length of EIM local registry name |
| 40 | 28 | BINARY(4) | Offset to user name |
| 44 | 2C | BINARY(4) | Length of user name |
| ARRAY(*) of CHAR | Fields specified by their offsets and lengths above | ||
Certificate Format CERT0200 (Plain Text)
The CERT0200 format consists of a certificate handle and some of the sections of the certificate parsed into a more readable format. A field with a offset of 0 indicates that the field does not have a corresponding set of characters for the field value. A field length of 0 indicates that the field is empty, that it is not used in the certificate, or that it is not recognized. The fields specified by the offsets and lengths in this format are not all text fields.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Returned length of this certificate and format information |
| 4 | 4 | BINARY(4) | Available length of this certificate and format information |
| 8 | 8 | BINARY(4) | Offset to certificate handle |
| 12 | C | BINARY(4) | Length of certificate handle |
| 16 | 10 | BINARY(4) | Offset to version |
| 20 | 14 | BINARY(4) | Length of version |
| 24 | 18 | BINARY(4) | Offset to serial number |
| 28 | 1C | BINARY(4) | Length of serial number |
| 32 | 20 | BINARY(4) | Offset to issuer's common name |
| 36 | 24 | BINARY(4) | Length of issuer's common name |
| 40 | 28 | BINARY(4) | Offset to issuer's country or region |
| 44 | 2C | BINARY(4) | Length of issuer's country or region |
| 48 | 30 | BINARY(4) | Offset to issuer's state or province |
| 52 | 34 | BINARY(4) | Length of issuer's state or province |
| 56 | 38 | BINARY(4) | Offset to issuer's locality |
| 60 | 3C | BINARY(4) | Length of issuer's locality |
| 64 | 40 | BINARY(4) | Offset to issuer's organization |
| 68 | 44 | BINARY(4) | Length of issuer's organization |
| 72 | 48 | BINARY(4) | Offset to issuer's organizational unit |
| 76 | 4C | BINARY(4) | Length of issuer's organizational unit |
| 80 | 50 | BINARY(4) | Offset to issuer's postal code |
| 84 | 54 | BINARY(4) | Length of issuer's postal code |
| 88 | 58 | BINARY(4) | Offset to validity period start |
| 92 | 5C | BINARY(4) | Length of validity period start |
| 96 | 60 | BINARY(4) | Offset to validity period end |
| 100 | 64 | BINARY(4) | Length of validity period end |
| 104 | 68 | BINARY(4) | Offset to subject's common name |
| 108 | 6C | BINARY(4) | Length of subject's common name |
| 112 | 70 | BINARY(4) | Offset to subject's country or region |
| 116 | 74 | BINARY(4) | Length of subject's country or region |
| 120 | 78 | BINARY(4) | Offset to subject's state or province |
| 124 | 7C | BINARY(4) | Length of subject's state or province |
| 128 | 80 | BINARY(4) | Offset to subject's locality |
| 132 | 84 | BINARY(4) | Length of subject's locality |
| 136 | 88 | BINARY(4) | Offset to subject's organization |
| 140 | 8C | BINARY(4) | Length of subject's organization |
| 144 | 90 | BINARY(4) | Offset to subject's organizational unit |
| 148 | 94 | BINARY(4) | Length of subject's organizational unit |
| 152 | 98 | BINARY(4) | Offset to subject's postal code |
| 156 | 9C | BINARY(4) | Length of subject's postal code |
| 160 | A0 | BINARY(4) | Offset to subject's public key algorithm |
| 164 | A4 | BINARY(4) | Length of subject's public key algorithm |
| 168 | A8 | BINARY(4) | Offset to issuer's unique ID (Version 2) |
| 172 | AC | BINARY(4) | Length of issuer's unique ID (Version 2) |
| 176 | B0 | BINARY(4) | Offset to subject's unique ID (Version 2) |
| 180 | B4 | BINARY(4) | Length of subject's unique ID (Version 2) |
| 184 | B8 | BINARY(4) | Offset to issuer's e-mail address |
| 188 | BC | BINARY(4) | Length of issuer's e-mail address |
| 192 | C0 | BINARY(4) | Offset to subject's e-mail address |
| 196 | C4 | BINARY(4) | Length of subject's e-mail address |
| 200 | C8 | BINARY(4) | Offset to EIM identifier |
| 204 | CC | BINARY(4) | Length of EIM identifier |
| 208 | D0 | BINARY(4) | Offset to EIM local registry name |
| 212 | D4 | BINARY(4) | Length of EIM local registry name |
| 216 | D8 | BINARY(4) | Offset to user name |
| 220 | DC | BINARY(4) | Length of user name |
| ARRAY(*) of CHAR | Certificate information fields | ||
Selection Control
The criteria is used to select or match certificates based on specified information.
This parameter is useful to reduce the total number of certificates that are returned in the list. The list of certificates is generated with only the specific selections that are of interest.
The following shows the format of the selection control parameter. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of selection control |
| 4 | 4 | BINARY(4) | Number of selection pairs |
| 8 | 8 | 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
Available length of this certificate and format information. The available length of this certificate and format information. If this length is more than the returned length of this certificate and format information field, then not all of the fields were returned.
Certificate information fields. The actual data in the certificate. Specific fields can be accessed by using the offset to that specific field.
Displacements to selection pairs. An array of displacements to selection pairs from the beginning of the selection control.
EIM identifier. The EIM identifier that was specified on the call to the API.
Format name. The format of the returned output.
Length of ASN.1 format certificate. The length of the ASN.1 DER format certificate. This length refers to a field of hexadecimal bytes.
Length of certificate handle. The length of the certificate handle. This length refers to a field of hexadecimal bytes.
Length of EIM identifier. The length of the EIM identifier that was specified on the call to the API or to which the certificate is associated.
Length of EIM local registry name. The length of the EIM local registry name. This registry would be the target registry for the user name's association to the EIM identifier.
Length of issuer's common name. The length of the field that indicates the issuer's common name.
Length of issuer's country or region. The length of the field that indicates the issuer's country or region.
Length of issuer's e-mail address. The length of the field that indicates the issuer's e-mail address.
Length of issuer's locality. The length of the field that indicates the issuer's locality.
Length of issuer's organization. The length of the field that indicates the issuer's organization.
Length of issuer's organizational unit. The length of the field that indicates the issuer's organizational unit.
Length of issuer's postal code. The length of the field that indicates the issuer's postal code.
Length of issuer's state or province. The length of the field that indicates the issuer's state or province.
Length of issuer's unique ID (Version 2). The length of the field that indicates the issuer's unique ID (Version 2). This length refers to a field of hexadecimal bytes.
Length of selection control. The total number of bytes for the length itself, the bytes for the number of selection pairs, and the bytes 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 indicates that no selection control pairs are specified.
Length of selection pair. The 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 bytes 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 serial number. The length of the field that indicates the serial number.
Length of subject's common name. The length of the field that indicates the subject's common name.
Length of subject's country or region. The length of the field that indicates the subject's country or region.
Length of subject's e-mail address. The length of the field that indicates the subject's e-mail address.
Length of subject's locality. The length of the field that indicates the subject's locality.
Length of subject's organization. The length of the field that indicates the subject's organization.
Length of subject's organizational unit. The length of the field that indicates the subject's organizational unit.
Length of subject's postal code. The length of the field that indicates the subject's postal code.
Length of subject's public key algorithm. The length of the field that indicates the subject's public key algorithm.
Length of subject's state or province. The length of the field that indicates the subject's state or province.
Length of subject's unique ID (Version 2). The length of the field that indicates the subject's unique ID (Version 2). This length refers to a field of hexadecimal bytes.
Length of user name. The length of the field that indicates the user name to which the certificate is associated.
Length of validity period start. The length of the field that indicates the beginning date of the validity period. The first 8 characters consist of 4 characters for the year, 2 characters for the month, and 2 characters for the day. The last 6 characters consist of 2 characters for the hours, 2 characters for the minutes, and 2 characters for the seconds.
Length of validity period end. The length of the field that indicates the ending date of the validity period. The first 8 characters consist of 4 characters for the year, 2 characters for the month, and 2 characters for the day. The last 6 characters consist of 2 characters for the hours, 2 characters for the minutes, and 2 characters for the seconds.
Length of version. The length of the field that indicates the version. This length refers to a field of hexadecimal bytes.
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. The maximum allowed number of selection pairs is defined as QSY_MAX_SEL_NAMES.
Offset to ASN.1 format certificate. The offset to the ASN.1 DER format certificate. This offset refers to a field of hexadecimal bytes.
Offset to certificate handle. The offset to the certificate handle. This offset refers to a field of hexadecimal bytes.
Offset to EIM identifier. The offset to the EIM identifier that was specified on the call to the API or to which the certificate is associated.
Offset to EIM local registry name. The offset to the EIM local registry name.
Offset to issuer's common name. The offset to the field that indicates the issuer's common name.
Offset to issuer's country or region. The offset to the field that indicates the issuer's country or region.
Offset to issuer's e-mail address. The offset to the field that indicates the issuer's e-mail address.
Offset to issuer's locality. The offset to the field that indicates the issuer's locality.
Offset to issuer's organization. The offset to the field that indicates the issuer's organization.
Offset to issuer's organizational unit. The offset to the field that indicates the issuer's organizational unit.
Offset to issuer's postal code. The offset to the field that indicates the issuer's postal code.
Offset to issuer's state or province. The offset to the field that indicates the issuer's state or province.
Offset to issuer's unique ID (Version 2). The offset to the field that indicates the issuer's unique ID (Version 2). This offset refers to a field of hexadecimal bytes.
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 serial number. The offset to the field that indicates the serial number.
Offset to subject's common name. The offset to the field that indicates the subject's common name.
Offset to subject's country or region. The offset to the field that indicates the subject's country or region.
Offset to subject's e-mail address. The offset to the field that indicates the subject's e-mail address.
Offset to subject's locality. The offset to the field that indicates the subject's locality.
Offset to subject's organization. The offset to the field that indicates the subject's organization.
Offset to subject's organizational unit. The offset to the field that indicates the subject's organizational unit.
Offset to subject's postal code. The offset to the field that indicates the subject's postal code.
Offset to subject's public key algorithm. The offset to the field that indicates the subject's public key algorithm.
Offset to subject's state or province. The offset to the field that indicates the subject's state or province.
Offset to subject's unique ID (Version 2). The offset to the field that indicates the subject's unique ID (Version 2). This offset refers to a field of hexadecimal bytes.
Offset to user name. The offset to the user name to which the certificate is associated.
Offset to validity period start. The offset to the field that indicates the beginning date of the validity period.
Offset to validity period end. The offset to the field that indicates the ending date of the validity period.
Offset to version. The offset to the field that indicates the version. This offset refers to a field of hexadecimal bytes.
Reserved. An ignored field.
Returned length of this certificate and format information. The total length of this certificate and format information that was returned. This length is for one certificate.
Selection name. The selection that is used to limit which certificates from the validation list are returned. Selections indicate which fields of the certificate are to be examined for matching selection values. 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.
Example values:
| John Smith | |
| US | |
| NY | |
| XYZ Data Security, Inc. | |
| Secure Server Certification Authority |
For example, to limit the certificates that are returned to only certificates that have US for the country or region, use the available definitions such as the 20-character name field defined by QSY_COUNTRY to indicate the following values in the selection control:
| Length of selection control: 38 | |
| Number of selection pairs: 1 | |
| Displacement to selection pair: 12 |
The corresponding selection pair for this example would use the following values:
| Length of selection pair: 26 | |
| Selection name: COUNTRY | |
| Selection value: US |
For another example, to indicate that all certificates that are found are to be returned, the selection control could indicate that there are no selection pairs to be used either by specifying that the length of the selection control is 0, and no selection pairs value will be checked, or by specifying that the number of selection pairs is 0 as follows:
| Length of selection control: 8 | |
| Number of selection pairs: 0 |
User name. The name of the user profile that is specified on the call to the API. If this field contains *EIMID, then the Offset to EIM identifier and Length of EIM identifier fields can be used to determine the EIM identifier value that was specified on the call to the API.
User space library name. The library that contains the user space, as specified in the call to the API.
User space name. The name of the user space.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPF1F41 E | Severe error occurred while addressing parameter list. |
| CPF2204 E | User profile &1 not found. |
| CPF2213 E | Not able to allocate user profile &1. |
| CPF2217 E | Not authorized to user profile &1. |
| CPF222E E | &1 special authority is required. |
| CPF2222 E | Storage limit is greater than specified for user profile &1. |
| 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. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF4AB9 E | User certificate function not successful. |
| 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. |
| 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 ]