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: QSYDIGID

  Default 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 i5/OS user profile at any given time, but more than one certificate may be associated with the same i5/OS user profile if each certificate is unique. The same certificate is not allowed to be associated with more than one i5/OS 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 i5/OS 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 i5/OS 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 Space Format for List APIs. 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

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.

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.

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.

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:

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:

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:

The corresponding selection pair for this example would use the following values:

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:

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