Retrieve Certificate Information (QYCURTVCI, QycuRetrieveCertificateInfo) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of certificate information | Input | Char(8) |
| 4 | Certificate store name | Input | Char(*) |
| 5 | Length of certificate store name | Input | Binary(4) |
| 6 | Format of certificate store name | Input | Char(8) |
| 7 | Certificate store password | Input | Char(*) |
| 8 | Length of certificate store password | Input | Binary(4) |
| 9 | CCSID of certificate store password | Input | Binary(4) |
| 10 | Selection control | Input | Char(*) |
| 11 | Error code | I/O | Char(*) |
Program: QICSS/QYCURTVCI
Default Public Authority: *USE
Threadsafe: No
|
Syntax for QycuRetrieveCertificateInfo: #include <qycucerti.h>
void QycuRetrieveCertificateInfo
(void *Receiver_variable,
int *Length_receiver_variable,
char *Format_certificate_info,
char *Certificate_store_name,
int *Length_certificate_store_name,
char *Format_certificate_store_name,
char *Certificate_store_password,
int *Length_certificate_store_password,
int *CCSID_certificate_store_password,
char *Selection_control,
void *Error_code);
Service Program: QICSS/QYCUCERTIDefault Public Authority: *USE Threadsafe: No |
The Retrieve Certificate Information (OPM, QYCURTVCI; ILE, QycuRetrieveCertificateInfo) API retrieves information from server or CA certificates. For example, you can retrieve information about certificates that are expiring within a given date range.
Authorities and Locks
- Authority Required
-
The caller of this API must provide the password for the certificate store. In addition, the caller must have *ALLOBJ and *SECADM special authorities.
- Locks
- Object will be locked shared read.
Required Parameter Group
Note: Do not use quotation marks in the input parameters.- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the certificate information.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length specified is larger than the actual size of the receiver variable, the results will not be predictable. The minimum length is 8 bytes.
- Format of certificate information
- INPUT; CHAR(8)
The content and format of the information that is returned for each certificate is specified here.
The possible format names are:
RTCI0100 Certificate labels RTCI0200 Certificate labels and expiration information RTCI0300 All certificate information
- Certificate store name
- INPUT; CHAR(*)
The certificate store from which you want to retrieve the list of certificates. The following values can be used for the certificate store name:
*SYSTEM The *SYSTEM certificate store. *OBJECTSIGNING The *OBJECTSIGNING certificate store. *SIGNATUREVERIFICATION The *SIGNATUREVERIFICATION certificate store. Directory path and file name The fully qualified Integrated File System (IFS) directory path and file name of the certificate store. The directory path must start with a leading forward slash (/), for example, /mydirectory/mystore.kdb. If you are using format OBJN0100, the path and file name are assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, the path and file name are assumed to be represented in the default CCSID of the job. - Length of certificate store name
- INPUT; Binary(4)
The length of the certificate store name. If the format specified is OBJN0200 (see below), this field must include the QLG path name structure length in addition to the length of the path name itself. If the format specified is OBJN0100 (see below), only the length of the path name itself is included.
- Format of certificate store name
- INPUT; CHAR(8)
The format of the certificate store path and file name parameter.
OBJN0100 The certificate store path and file name is a simple path name. If you are specifying *SYSTEM, *OBJECTSIGNING, or *SIGNATUREVERIFICATION for the certificate store name, use this format. OBJN0200 The certificate path and file name is an LG-type path name.
- Certificate store password
- INPUT; CHAR(*)
The password for the certificate store.
- Length of certificate store password
- INPUT; Binary(4)
The length of the password of the certificate store.
- CCSID of certificate store password
- INPUT; Binary(4)
This parameter is the CCSID of the certificate store password. If the value is 0, the default CCSID of the job will be used.
- Selection control
- INPUT; CHAR(*)
The control information used to limit which certificates are returned. For the format of this structure, see Selection Control.
- Error code
- OUTPUT; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Receiver Formats
The following tables describe the order and format of the data returned in a receiver variable. For detailed descriptions of each field, see Receiver Field Descriptions.
RTCI0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first certificate entry |
| 12 | C | BINARY(4) | Number of certificate entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Certificate entry information. These fields are repeated for each certificate entry returned. | |||
| BINARY(4) | Displacement to next certificate entry | ||
| BINARY(4) | Displacement to certificate label | ||
| BINARY(4) | Length of certificate label | ||
| CHAR(*) | Certificate label | ||
RTCI0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first certificate entry |
| 12 | C | BINARY(4) | Number of certificate entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Certificate entry information. These fields are repeated for each certificate entry returned. | |||
| BINARY(4) | Displacement to next certificate entry | ||
| CHAR(14) | Validity period end | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Displacement to certificate label | ||
| BINARY(4) | Length of certificate label | ||
| BINARY(4) | Displacement to subject's common name | ||
| BINARY(4) | Length of subject's common name | ||
| ARRAY(*) of CHAR | Certificate information fields | ||
RTCI0300 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first certificate entry |
| 12 | C | BINARY(4) | Number of certificate entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Certificate entry information. These fields are repeated for each certificate entry returned. | |||
| BINARY(4) | Displacement to next certificate entry | ||
| CHAR(1) | Trusted status | ||
| CHAR(1) | Private key indicator | ||
| CHAR(1) | Key storage location | ||
| CHAR(14) | Validity period start | ||
| CHAR(14) | Validity period end | ||
| CHAR(16) | Key usage extensions | ||
| CHAR(11) | Reserved | ||
| BINARY(4) | Key size | ||
| BINARY(4) | Displacement to certificate label | ||
| BINARY(4) | Length of certificate label | ||
| BINARY(4) | Displacement to serial number | ||
| BINARY(4) | Length of serial number | ||
| BINARY(4) | Displacement to subject's common name | ||
| BINARY(4) | Length of subject's common name | ||
| BINARY(4) | Displacement to subject's country or region | ||
| BINARY(4) | Length of subject's country or region | ||
| BINARY(4) | Displacement to subject's state or province | ||
| BINARY(4) | Length of subject's state or province | ||
| BINARY(4) | Displacement to subject's locality | ||
| BINARY(4) | Length of subject's locality | ||
| BINARY(4) | Displacement to subject's organization | ||
| BINARY(4) | Length of subject's organization | ||
| BINARY(4) | Displacement to subject's organizational unit | ||
| BINARY(4) | Length of subject's organizational unit | ||
| BINARY(4) | Displacement to subject's postal code | ||
| BINARY(4) | Length of subject's postal code | ||
| BINARY(4) | Displacement to issuer's common name | ||
| BINARY(4) | Length of issuer's common name | ||
| BINARY(4) | Displacement to issuer's country or region | ||
| BINARY(4) | Length of issuer's country or region | ||
| BINARY(4) | Displacement to issuer's state or province | ||
| BINARY(4) | Length of issuer's state or province | ||
| BINARY(4) | Displacement to issuer's locality | ||
| BINARY(4) | Length of issuer's locality | ||
| BINARY(4) | Displacement to issuer's organization | ||
| BINARY(4) | Length of issuer's organization | ||
| BINARY(4) | Displacement to issuer's organizational unit | ||
| BINARY(4) | Length of issuer's organizational unit | ||
| BINARY(4) | Displacement to issuer's postal code | ||
| BINARY(4) | Length of issuer's postal code | ||
| BINARY(4) | Displacement to CRL location | ||
| BINARY(4) | Length of CRL location | ||
| BINARY(4) | Displacement to LDAP server name | ||
| BINARY(4) | Length of LDAP server name | ||
| BINARY(4) | Displacement to private key label | ||
| BINARY(4) | Length of private key label | ||
| BINARY(4) | Displacement to IP address | ||
| BINARY(4) | Length of IP address | ||
| BINARY(4) | Displacement to domain name | ||
| BINARY(4) | Length of domain name | ||
| BINARY(4) | Displacement to email address | ||
| BINARY(4) | Length of email address | ||
| BINARY(4) | Displacement to first cryptographic device | ||
| BINARY(4) | Number of cryptographic devices | ||
| BINARY(4) | Number of cryptographic devices returned | ||
| ARRAY(*) of CHAR | Certificate information fields | ||
| Cryptographic device information. These fields are repeated for each cryptographic device returned. | |||
| BINARY(4) | Displacement to next cryptographic device | ||
| BINARY(4) | Displacement to cryptographic device name | ||
| BINARY(4) | Length of cryptographic device name | ||
| ARRAY(*) of CHAR | Cryptographic device information fields (names) | ||
Receiver Field Descriptions
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Certificate label. The label for the certificate. The label is returned in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, the label is returned in the default CCSID of the job. The certificate label is a null terminated string.
Displacement to certificate label. The displacement from the beginning of the entry to the field that indicates the certificate label.
Displacement to CRL location. The displacement from the beginning of the entry to the field that indicates the CRL location.
Displacement to cryptographic device name. The displacement from the beginning of the entry to the field that indicates the cryptographic device name.
Displacement to domain name. The displacement from the beginning of the entry to the field that indicates the domain name.
Displacement to email address. The displacement from the beginning of the entry to the field that indicates the email address.
Displacement to first cryptographic device. The displacement from the beginning of the entry to the field that indicates the first cryptographic device.
Displacement to IP address. The displacement from the beginning of the entry to the field that indicates the IP address.
Displacement to issuer's common name. The displacement from the beginning of the entry to the field that indicates the issuer's common name.
Displacement to issuer's country or region. The displacement from the beginning of the entry to the field that indicates the issuer's country or region.
Displacement to issuer's locality. The displacement from the beginning of the entry to the field that indicates the issuer's locality.
Displacement to issuer's organization. The displacement from the beginning of the entry to the field that indicates the issuer's organization.
Displacement to issuer's organizational unit. The displacement from the beginning of the entry to the field that indicates the issuer's organizational unit.
Displacement to issuer's postal code. The displacement from the beginning of the entry to the field that indicates the issuer's postal code.
Displacement to issuer's state or province. The displacement from the beginning of the entry to the field that indicates the issuer's state or province.
Displacement to LDAP server name. The displacement from the beginning of the entry to the field that indicates the LDAP server name.
Displacement to next certificate entry. The displacement from the beginning of this entry to the next entry.
Displacement to next cryptographic device. The displacement from the beginning of the current cryptographic device entry to the next entry.
Displacement to private key label. The displacement from the beginning of the entry to the field that indicates the private key label.
Displacement to serial number. The displacement from the beginning of the entry to the field that indicates the serial number.
Displacement to subject's common name. The displacement from the beginning of the entry to the field that indicates the subject's common name.
Displacement to subject's country or region. The displacement from the beginning of the entry to the field that indicates the subject's country or region.
Displacement to subject's locality. The displacement from the beginning of the entry to the field that indicates the subject's locality.
Displacement to subject's organization. The displacement from the beginning of the entry to the field that indicates the subject's organization.
Displacement to subject's organizational unit. The displacement from the beginning of the entry to the field that indicates the subject's organizational unit.
Displacement to subject's postal code. The displacement from the beginning of the entry to the field that indicates the subject's postal code.
Displacement to subject's state or province. The displacement from the beginning of the entry to the field that indicates the subject's state or province.
Key size. The size of the key in bytes.
Key storage location A single character that indicates where the key is stored.
Possible values:
| 0 | The key is stored is software |
| 1 | The key is stored in hardware |
| 2 | The key is stored in hardware encryption |
Key usage extensions The key usage extension values for the certificate. If the certificate has the key usage extension, the field is 1. If not, the field is 0.
This field contains the following fields:
| DigitalSignature | CHAR(1)
Whether the certificate has the digital signature extension. |
| NonRepudiation | CHAR(1)
Whether the certificate has the nonrepudiation extension. |
| KeyEncipherment | CHAR(1)
Whether the certificate has the key encipherment extension. |
| DataEncipherment | CHAR(1)
Whether the certificate has the data encipherment extension. |
| KeyAgreement | CHAR(1)
Whether the certificate has the key agreement extension. |
| KeyCertSign | CHAR(1)
Whether the certificate has the key certificate signature extension. |
| CRLSign | CHAR(1)
Whether the certificate has the CRL signature extension. |
| EncipherOnly | CHAR(1)
Whether the certificate has the encipher only extension. |
| DecipherOnly | CHAR(1)
Whether the certificate has the decipher only extension. |
| Reserved | CHAR(7)
An ignored field. |
Length of certificate label. The length of the field that contains the certificate label.
Length of CRL location. The length of the field that indicates the CRL location.
Length of cryptographic device name. The length of the field that indicates the cryptographic device name.
Length of domain name. The length of the field that indicates the domain name.
Length of email address. The length of the field that indicates the email address.
Length of IP address. The length of the field that indicates the IP address.
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 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 LDAP server name. The length of the field that indicates the LDAP server name.
Length of private key label. The length of the field that indicates the private key label. Will be 0 if the key storage location is 0.
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 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 state or province. The length of the field that indicates the subject's state or province.
Number of certificate entries returned. The number of certificate entries returned. If the receiver variable is not large enough to hold all of the information, this number contains only the number of certificate entries actually returned.
Number of cryptographic devices. The number of cryptographic devices returned.
Offset to first certificate entry. The offset to the first certificate entry returned. The offset is from the beginning of the structure. If no entries are returned, the offset is set to zero.
Private key indicator One character indicator that indicates if the certificate has a private key.
Possible values:
| 0 | The certificate does not have a private key. |
| 1 | The certificate does have a private key. |
Trusted status One character indicator that indicates if the certificate is trusted.
Possible values:
| 0 | The certificate is not trusted. |
| 1 | The certificate is trusted. |
Reserved. An ignored field.
Validity period start. 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.
Validity period end. 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.
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 Selection Control 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) | Offsets 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 | ||
Selection Control Field Descriptions
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.
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 QYCU_MAX_SEL_NAMES.
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.
Offsets to selection pairs. An array of offsets to selection pairs from the beginning of the selection control.
Selection name. The selection that is used to limit which certificates 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.
Valid selection names are:
| EXPIRATIONDAYS | CHAR(4) | 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). The valid range is from 1 to 365 days. | ||||
| CERTIFICATETYPE | CHAR(1) | This may be server or CA.
Possible values:
|
||||
| CERTIFICATELABEL | CHAR (*) | Certificate whose label match the label specified. When choosing this selection criteria, the other selection criteria are not allowed. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0AA E | Error occurred while attemption to obtain space. |
| CPFA0C1 E | CCSID &1 not valid. |
| CPFA049 E | Certificate store does not exist. |
| CPFA09C E | User not authorized to certificate store. |
| CPFB001 E | One or more input parameters is NULL or missing. |
| CPFB003 E | Certificate store password is not valid. |
| CPFB006 E | An error occurred. The error code is &1. |
| CPF222E E | &1 special authority is required. |
| CPF227E E | Selection control is not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
API introduced: V6R1
[ Back to top | Security APIs | APIs by category ]