Retrieve Certificate Usage Information (QYCDRCUI, QycdRetrieveCertUsageInfo) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Application selection criteria | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Service Program: QICSS/QYCDCUSG
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Certificate Usage Information (QYCDRCUI, QycdRetrieveCertUsageInfo) API retrieves information about one or more registered applications that use certificates and their associated certificate information.
Authorities and Locks
- Exit Registration
- Object locked shared no update.
- QUSRSYS/QYCDCERTI *USRIDX
- Object locked shared no update.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the certificate information for the requested applications.
- 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 may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the certificate information to be returned.
You must use one of the following format names:
RCUI0100 Information about the application that uses certificates RCUI0200 The same information as RCUI0100, plus information about the certificate assigned to the application RCUI0300 The same information as RCUI0200, plus information about the certificates for certificate authorities (CAs) that the application trusts. The label of the CAs will be returned. RCUI0350 The same information as RCUI0200, plus information about the certificates for certificate authorities (CAs) that the application trusts. The distinguished name (DN) of the CAs will be returned. RCUI0400 The same information as RCUI0350, plus additional System TLS application information.
- Application selection criteria
- INPUT; CHAR(*)
The selection criteria to be used when selecting which registered applications are returned. No coded character set ID (CCSID) normalization is performed. It is recommended that you use characters from the invariant character set for the comparison data.
The information must be in the following format:
Number of selection criteria BINARY(4)
The total number of selection criteria. Specify 0 if no selection criteria are specified. If 0 is specified, information for all registered applications will be returned. The maximum value for this field is 1.Selection criteria array CHAR(*)
The selection criteria. Refer to "Format for Application Selection Criteria" for more information.
- Error code
- I/O; 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.
RCUI0100 Format
The following information is returned for the RCUI0100 format. This format provides information on an application that uses certificates. For a detailed description of each field, see "Field Descriptions".
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first application entry |
| 12 | C | BINARY(4) | Number of application entries returned |
| 16 | 10 | BINARY(4) | Length of application entry |
| 20 | 14 | CHAR(*) | Reserved |
| Application entry information. These fields are repeated for each application entry returned. | |||
| CHAR(100) | Application ID | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | QMLTTHDACN system value usage | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | Application description indicator | ||
| CHAR(10) | Application description message file name | ||
| CHAR(10) | Application description message file library name | ||
| CHAR(7) | Application description message ID | ||
| CHAR(50) | Application text description | ||
| CHAR(1) | Limit CA certificates trusted indicator | ||
| CHAR(1) | Certificate assigned indicator | ||
| CHAR(1) | Application type | ||
| CHAR(10) | Application user profile | ||
| CHAR(1) | Reserved | ||
| CHAR(1) | Client authentication required | ||
| CHAR(1) | Perform CRL processing | ||
| CHAR(330) | Application description message text | ||
| CHAR(*) | Reserved | ||
RCUI0200 Format
The following information is returned for the RCUI0200 format. This format provides information on an application that uses certificates, plus information about the certificate assigned to the application. For a detailed description of each field, see "Field Descriptions".
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first application entry |
| 12 | C | BINARY(4) | Number of application entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Application entry information. These fields are repeated for each application entry returned. | |||
| BINARY(4) | Displacement to next application entry | ||
| CHAR(100) | Application ID | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | QMLTTHDACN system value usage | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | Application description indicator | ||
| CHAR(10) | Application description message file name | ||
| CHAR(10) | Application description message file library name | ||
| CHAR(7) | Application description message ID | ||
| CHAR(50) | Application text description | ||
| CHAR(1) | Limit CA certificates trusted indicator | ||
| CHAR(1) | Certificate assigned indicator | ||
| CHAR(1) | Certificate ID type | ||
| CHAR(1) | Certificate ID converted indicator | ||
| CHAR(1) | Certificate store converted indicator | ||
| BINARY(2) | Number of certificates | ||
| BINARY(4) | Displacement to certificate ID | ||
| BINARY(4) | Length of certificate ID | ||
| BINARY(4) | CCSID of certificate ID | ||
| BINARY(4) | Displacement to certificate store | ||
| BINARY(4) | Length of certificate store | ||
| BINARY(4) | CCSID of certificate store | ||
| CHAR(1) | Application type | ||
| CHAR(10) | Application user profile | ||
| CHAR(1) | Reserved | ||
| CHAR(1) | Client authentication required | ||
| CHAR(1) | Perform CRL processing | ||
| CHAR(330) | Application description message text | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Certificate ID | ||
| CHAR(*) | Certificate store | ||
RCUI0300 Format
The following information is returned for the RCUI0300 format. This format provides information on an application, plus information about the certificate assigned to the application and information about the list of CA certificates that the application can trust. For a detailed description of each field, see "Field Descriptions".
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first application entry |
| 12 | C | BINARY(4) | Number of application entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Application entry information. These fields are repeated for each application entry returned. | |||
| BINARY(4) | Displacement to next application entry | ||
| CHAR(100) | Application ID | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | QMLTTHDACN system value usage | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | Application description indicator | ||
| CHAR(10) | Application description message file name | ||
| CHAR(10) | Application description message file library name | ||
| CHAR(7) | Application description message ID | ||
| CHAR(50) | Application text description | ||
| CHAR(1) | Limit CA certificates trusted indicator | ||
| CHAR(1) | Certificate assigned indicator | ||
| CHAR(1) | Certificate ID type | ||
| CHAR(1) | Certificate ID converted indicator | ||
| CHAR(1) | Certificate store converted indicator | ||
| BINARY(2) | Number of certificates | ||
| BINARY(4) | Displacement to certificate ID | ||
| BINARY(4) | Length of certificate ID | ||
| BINARY(4) | CCSID of certificate ID | ||
| BINARY(4) | Displacement to certificate store | ||
| BINARY(4) | Length of certificate store | ||
| BINARY(4) | CCSID of certificate store | ||
| BINARY(4) | Displacement to first trusted CA certificate entry | ||
| BINARY(4) | Number of trusted CA certificate entries | ||
| CHAR(1) | Application type | ||
| CHAR(10) | Application user profile | ||
| CHAR(1) | Reserved | ||
| CHAR(1) | Client authentication required | ||
| CHAR(1) | Perform CRL processing | ||
| CHAR(330) | Application description message text | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Certificate ID | ||
| CHAR(*) | Certificate store | ||
| CHAR(*) | Trusted CA certificate entries | ||
RCUI0350 Format
The following information is returned for the RCUI0350 format. This format provides information on an application, plus information about the certificate assigned to the application and the distinguished name (DN) of the CA certificates that the applications can trust. For a detailed description of each field, see "Field Descriptions".
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first application entry |
| 12 | C | BINARY(4) | Number of application entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Application entry information. These fields are repeated for each application entry returned. | |||
| BINARY(4) | Displacement to next application entry | ||
| CHAR(100) | Application ID | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | QMLTTHDACN system value usage | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | Application description indicator | ||
| CHAR(10) | Application description message file name | ||
| CHAR(10) | Application description message file library name | ||
| CHAR(7) | Application description message ID | ||
| CHAR(50) | Application text description | ||
| CHAR(1) | Limit CA certificates trusted indicator | ||
| CHAR(1) | Certificate assigned indicator | ||
| CHAR(1) | Certificate ID type | ||
| CHAR(1) | Certificate ID converted indicator | ||
| CHAR(1) | Certificate store converted indicator | ||
| BINARY(2) | Number of certificates | ||
| BINARY(4) | Displacement to certificate ID | ||
| BINARY(4) | Length of certificate ID | ||
| BINARY(4) | CCSID of certificate ID | ||
| BINARY(4) | Displacement to certificate store | ||
| BINARY(4) | Length of certificate store | ||
| BINARY(4) | CCSID of certificate store | ||
| BINARY(4) | Displacement to list of trusted CA certificate DNs | ||
| BINARY(4) | Number of trusted CA certificate DNs | ||
| BINARY(4) | Length of list of trusted CA certificate DNs | ||
| CHAR(1) | Application type | ||
| CHAR(10) | Application user profile | ||
| CHAR(1) | Reserved | ||
| CHAR(1) | Client authentication required | ||
| CHAR(1) | Perform CRL processing | ||
| CHAR(330) | Application description message text | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Certificate ID | ||
| CHAR(*) | Certificate store | ||
| CHAR(*) | List of trusted CA certificate DNs | ||
RCUI0400 Format
The following information is returned for the RCUI0400 format. This format provides information on an application including System TLS information, plus information about the certificate assigned to the application and the distinguished name (DN) of the CA certificates that the applications can trust. For a detailed description of each field, see "Field Descriptions".
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first application entry |
| 12 | C | BINARY(4) | Number of application entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Application entry information. These fields are repeated for each application entry returned. | |||
| BINARY(4) | Displacement to next application entry | ||
| CHAR(100) | Application ID | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | QMLTTHDACN system value usage | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | Application description indicator | ||
| CHAR(10) | Application description message file name | ||
| CHAR(10) | Application description message file library name | ||
| CHAR(7) | Application description message ID | ||
| CHAR(50) | Application text description | ||
| CHAR(1) | Limit CA certificates trusted indicator | ||
| CHAR(1) | Certificate assigned indicator | ||
| CHAR(1) | Certificate ID type | ||
| CHAR(1) | Certificate ID converted indicator | ||
| CHAR(1) | Certificate store converted indicator | ||
| BINARY(2) | Number of certificates | ||
| BINARY(4) | Displacement to certificate ID | ||
| BINARY(4) | Length of certificate ID | ||
| BINARY(4) | CCSID of certificate ID | ||
| BINARY(4) | Displacement to certificate store | ||
| BINARY(4) | Length of certificate store | ||
| BINARY(4) | CCSID of certificate store | ||
| BINARY(4) | Displacement to list of trusted CA certificate DNs | ||
| BINARY(4) | Number of trusted CA certificate DNs | ||
| BINARY(4) | Length of list of trusted CA certificate DNs | ||
| CHAR(1) | Application type | ||
| CHAR(10) | Application user profile | ||
| CHAR(1) | Reserved | ||
| CHAR(1) | Client authentication required | ||
| CHAR(1) | Perform CRL processing | ||
| CHAR(330) | Application description message text | ||
| Array(10) of CHAR(1) | Transport Layer Security (TLS) protocols | ||
| Array(64) of CHAR(2) | Transport Layer Security (TLS) cipher specifications list | ||
 |
Array(32) of CHAR(1) | Transport Layer Security (TLS) signature algorithms for certificate |
|
| CHAR(1) | Perform Online Certificate Status Protocol (OCSP) checking | ||
| CHAR(128) | Online Certificate Status Protocol (OCSP) URL | ||
| CHAR(1) | Extended renegotiation critical mode | ||
| CHAR(128) | Server Name Indication (SNI) | ||
| CHAR(16) | Special indicators | ||
| |
Array(32) of CHAR(1) | Transport Layer Security (TLS) signature algorithms for key exchange |
|
| |
BINARY(4) | Transport Layer Security (TLS) session cache time to live
|
|
| CHAR(*) | Reserved | ||
| CHAR(*) | Certificate ID | ||
| CHAR(*) | Certificate store | ||
| CHAR(*) | List of trusted CA certificate DNs | ||
Receiver Field Descriptions
Application description indicator. Whether the application description is contained in a message file or text.
The possible values follow:
| 0 | The application description is contained in a message file. |
| 1 | The application description is text. |
Application description message file name. The name of the message file that contains the application description. This field will contain blanks when a text description is provided for the application description.
Application description message file library name. The name of the library in which the application description message file resides. This field will contain blanks when a text description is provided for the application description.
Application description message ID. The message identifier for the application description. This field will contain blanks when a text description is provided for the application description.
Application description message text. The first level text for the application description message ID. This value is converted to the CCSID of the job. This field will contain blanks when a text description is provided for the application description.
When the message text is retrieved from the message file, the message file library is added to the product portion of the library list, and *LIBL is specified for the library name. If the library cannot be added to the product portion of the library list, then *LIBL is still used to search for the message. If the message is not found, then the message file library is searched for the message.
Application ID. The ID of the application.
Application text description. The text for the application description. This field will contain blanks when a message file and message identifier are provided for the application description.
Application type. The type of application.
The possible values follow:
| 1 | Server application. |
| 2 | Client application. |
| 4 | Object signing application. |
Application user profile. The name of the user profile associated with the application. This field will contain blanks if there is no user profile associated with the application.
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.
CCSID of certificate ID. The CCSID that the certificate ID is returned in. The ID should be returned in the CCSID of the job. If a CCSID conversion error occurs, the ID will be returned in UCS-2 (unicode) CCSID.
CCSID of certificate store. The CCSID that the certificate store is returned in. The path name should be returned in the CCSID of the job. If a CCSID conversion error occurs, the path name will be returned in UCS-2 (unicode) CCSID.
Certificate assigned indicator. Whether a certificate is assigned to the application.
The possible values follow:
| 0 | A certificate is not assigned to the application. |
| 1 | A certificate is assigned to the application. |
Certificate ID. If Certificate ID type is 1 this field contains a certificate label. It is a NULL terminated string. If Certificate ID type is 2 this field contains a list of up to four certificate labels. Each certificate label is preceded by the 2 byte length of that label. The length does not include the length bytes. The CCSID of certificate ID field indicates in what CCSID the ID is returned. The certificate ID is a NULL terminated string.
Certificate ID converted indicator. The indicator as to whether or not a CCSID conversion error occurred for the certificate ID.
The possible values follow:
| 0 | There was no CCSID conversion error for the certificate ID. The ID is returned in the CCSID of the job. |
| 1 | There was a CCSID conversion error for the certificate ID. The CCSID of certificate ID field indicates the CCSID that the ID was returned in. |
Certificate ID type. The type of the certificate ID.
The possible value follows:
| 1 | The certificate ID is the label for the certificate. |
| 2 | The certificate ID is a list of 2 to 4 certificate labels. |
Certificate store. The path name where the certificate is stored. The CCSID of certificate store field indicates what CCSID the path name is returned in. The certificate store is a NULL terminated string.
The following special values may be returned:
| *SYSTEM | The certificate is stored in the system certificate store. |
| *OBJECTSIGNING | The certificate is stored in the object signing certificate store. |
Certificate store converted indicator. The indicator as to whether or not a CCSID conversion error occurred for the certificate store.
The possible values follow:
| 0 | There was no CCSID conversion error for the certificate store. The path name is returned in the CCSID of the job. |
| 1 | There was a CCSID conversion error for the certificate store. The CCSID of certificate store field indicates the CCSID that the path name was returned in. |
Client authentication required. Client authentication required indicator.
The possible values follow:
| 0 | Client authentication is not required. |
| 1 | Client authentication is required. |
Displacement to certificate ID. The displacement in the entry to the start of the certificate ID.
Displacement to certificate store. The displacement in the entry to the start of the certificate store.
Displacement to first trusted CA certificate entry. The displacement in the entry to the first trusted CA certificate entry.
Displacement to list of trusted CA certificate DNs. The displacement in the entry to the list of trusted CA certificate distinguished names (DNs).
Displacement to next application entry. The displacement from the beginning of this entry to the next entry.
Exit program library name. The name of the library in which the exit program resides.
Exit program name. The name of the exit program associated with the application.
Extended renegotiation critical mode.
The current value for the extended renegotiation critical mode indicator.
Note: This field has meaning for TLSv1.2 and prior protocols, it does not apply to TLSv1.3 and newer protocols.
The possible values follow:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 1 | RFC 5746 critical mode enabled. |
| 2 | RFC 5746 critical mode disabled. |
Length of application entry. The length of an application entry that is returned. This value should be used in determining the displacement to the next application entry.
Length of certificate ID. The length of the certificate ID. The length does not include the NULL terminator.
Length of certificate store. The length of the certificate store. The length does not include the NULL terminator.
Length of list of trusted CA certificate DNs. The length of the list of trusted CA certificate distinguished names (DNs).
Limit CA certificates trusted indicator. Whether the application wants the system to manage the list of CA certificates the application trusts.
The possible values follow:
| 0 | The application will manage the list of CA certificates it trusts. |
| 1 | The system will manage the list of CA certificates trusted by the application. The application determines which CA certificates are in the list. |
List of trusted CA certificate DNs. The list of distinguished names (DNs) that identify the trusted CA certificates for the application. A DN is the X.509 distinguished name of the subject of the certificate (ASN.1 DER encoding). The list is a contiguous list of DNs. The list of DNs can be parsed using the information within each DN.
The format of a DN is:
| CHAR(1) | DN identifier. Will contain X'30'. Indicates this is the start of a DN. |
| CHAR(1) | Length of DN information. |
| CHAR(*) | DN information that identifies the certificate. The length of this data can be determined by the length of DN information field. |
Multithreaded job action. The action to take when calling an exit program in a multithreaded job.
The possible values follow:
| 0 | Use the QMLTTHDACN system value to determine the action to take. |
| 1 | Run the exit program in the current multithreaded job. |
| 2 | Run the exit program in the current multithreaded job, but send informational message CPI3C80. |
| 3 | Do not run the exit program in the current multithreaded job, and send informational message CPI3C80. |
Number of application entries returned. The number of application entries returned. If the receiver variable is not large enough to hold all of the information, this number contains only the number of application entries actually returned.
Number of certificates. The number of certificate labels returned in Certificate ID. If Certificate ID type is 1 the number of certificates will be 1. If Certificate ID type is 2 the number of certificates will be 2, 3, or 4.
Number of trusted CA certificate DNs. The number of trusted CA certificate DNs in the list of trusted CA certificates DNs. If the application is managing the CA certificates that it trusts, or the system is managing the CA certificates that the application trusts and there are no trusted CA certificates, then this value will be 0.
Number of trusted CA certificate entries. The number of trusted CA certificate entries. If the application is managing the CA certificates that it trusts, or the system is managing the CA certificates that the application trusts and there are no trusted CA certificates, then this value will be 0.
Offset to first application entry. The offset to the first application entry returned. The offset is from the beginning of the structure. If no entries are returned, the offset is set to zero.
Online Certificate Status Protocol (OCSP) URL. The URL of the OCSP responder to query during certificate validation. This value will be padded with hexadecimal zeros. The possible values follow:
| *PGM | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| *DISABLE | Do not use the runtime URL value that may have been set by the underlying application. No URL value will be used. |
| url-value | The URL to use. |
Perform CRL processing. Perform Certificate Revocation List (CRL) processing indicator.
The possible values follow:
| 0 | CRL processing is not performed when the certificate associated with the application is validated. If the certificate has been added to a CRL, it will still be considered valid. |
| 1 | CRL processing is performed when the certificate associated with the application is validated. If the certificate has been added to a CRL, it will not be valid. |
Perform Online Certificate Status Protocol (OCSP) checking. The current value for the perform OCSP checking indicator. The possible values follow:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 1 | OCSP certificate revocation checking using Authority Information Access (AIA) certificate extension information is enabled. |
| 2 | OCSP certificate revocation checking using AIA certificate extension information is disabled. |
| 3 |
OCSP certificate revocation checking using AIA certificate extension information and OCSP stapling are enabled. The client requests OCSP stapling and the server supports the certificate status_request extension. |
| 4 | OCSP certificate revocation checking using AIA certificate extension information and OCSP stapling are enabled and OCSP stapling is required by the client. If the client does not receive a stapled OCSP response and the server's certificate extensions indicate it must staple, the secure connection fails. On the server, this value has the same meaning as a value of '3'. |
QMLTTHDACN system value usage. A flag that indicates whether the QMLTTHDACN system value was used in determining the multithreaded job action.
The possible values follow:
| 0 | The QMLTTHDACN system value was not used to determine the multithreaded job action. |
| 1 | The QMLTTHDACN system value was used to determine the multithreaded job action. |
Reserved. An ignored field.
Server Name Indication (SNI). Server name indication value. This value will be padded with hexadecimal zeros.
Special indicators. Text field containing special indicators. This value will be padded with hexadecimal zeros.
Threadsafe. The thread safety status of the exit program entry.
The possible values follow:
| 0 | The exit program entry is not threadsafe. |
| 1 | The threadsafe status of the exit program entry is not known. |
| 2 | The exit program entry is threadsafe. |
Transport Layer Security (TLS) cipher specifications list. The list of cipher suites that are supported by this application. Unused array elements will contain hexadecimal zeros. The possible values follow:
| 00 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| YF |
AES_128_GCM_SHA256. Use Advanced Encryption Standard (AES) cipher with Galois/Counter Mode (GCM) and 128 bit keys. Use Secure Hash Algorith 256 (SHA256) for generating the message authentication code (MAC). |
| YG | AES_256_GCM_SHA384. Use AES cipher with GCM and 256 bit keys. Use SHA384 for generating the MAC. |
| YH | CHACHA20_POLY1305_SHA256. Use the ChaCha stream cipher with 20 rounds, 96-bit nonce, and 256 bit keys with Poly1305 authenticator. Use SHA256 for generating the MAC.
|
| YB | ECDHE_ECDSA_AES_128_GCM_SHA256. Use the Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange algorithm with the Elliptic Curve Digital Signature Algorithm (ECDSA) with the AES cipher with GCM and 128 bit keys. Use SHA256 for generating the MAC. |
| YC | ECDHE_ECDSA_AES_256_GCM_SHA384. Use the ECDHE key exchange algorithm with the ECDSA signature algorithm with the AES cipher with GCM and 256 bit keys. Use SHA384 for generating the MAC. |
| YD | ECDHE_RSA_AES_128_GCM_SHA256. Use the ECDHE key exchange algorithm with the Rivest Shamir Adleman (RSA) public key algorithm with the AES cipher with GCM and 128 bit keys. Use SHA256 for generating the MAC. |
| YE | ECDHE_RSA_AES_256_GCM_SHA384. Use the ECDHE key exchange algorithm with the RSA public key algorithm with the AES cipher with GCM and 256 bit keys. Use SHA384 for generating the MAC. |
 YI |
ECDHE_ECDSA_CHACHA20_POLY1305_SHA256. Use the ECDHE key exchange algorithm with the ECDSA public key algorithm with the ChaCha stream cipher with 20 rounds, 96-bit nonce, and 256 bit keys with Poly1305 authenticator. Use SHA256 for generating the MAC. |
| YJ | ECDHE_RSA_CHACHA20_POLY1305_SHA256. Use the ECDHE key exchange algorithm with the RSA public key algorithm with the ChaCha stream cipher with 20 rounds, 96-bit nonce, and 256 bit keys with Poly1305 authenticator. Use SHA256 for generating the MAC.
|
| 9C | RSA_AES_128_GCM_SHA256. Use the RSA public key algorithm with the AES cipher with GCM and 128 bit keys. Use SHA256 for generating the MAC. |
| 9D | RSA_AES_256_GCM_SHA384. Use the RSA public key algorithm with the AES cipher with GCM and 256 bit keys. Use SHA384 for generating the MAC. |
| Y7 | ECDHE_ECDSA_AES_128_CBC_SHA256. Use the ECDHE key exchange algorithm with the ECDSA public key algorithm with the AES cipher with CBC and 128 bit keys. Use SHA256 for generating the MAC. |
| Y8 | ECDHE_ECDSA_AES_256_CBC_SHA384. Use the ECDHE key exchange algorithm with the ECDSA public key algorithm with the AES cipher with CBC and 256 bit keys. Use SHA384 for generating the MAC. |
| Y9 | ECDHE_RSA_AES_128_CBC_SHA256. Use the ECDHE key exchange algorithm with the RSA public key algorithm with the AES cipher with CBC and 128 bit keys. Use SHA256 for generating the MAC. |
| YA | ECDHE_RSA_AES_256_CBC_SHA384. Use the ECDHE key exchange algorithm with the RSA public key algorithm with the AES cipher with CBC and 256 bit keys. Use SHA384 for generating the MAC. |
| 3C | RSA_AES_128_CBC_SHA256. Use the RSA public key algorithm with the AES cipher with CBC and 128 bit keys. Use SHA256 for generating the MAC. |
| 2F | RSA_AES_128_CBC_SHA. Use the RSA public key algorithm with the AES cipher with CBC and 128 bit keys. Use SHA-1 for generating the MAC. |
| 3D | RSA_AES_256_CBC_SHA256. Use the RSA public key algorithm with the AES cipher with CBC and 256 bit keys. Use SHA256 for generating the MAC. |
| 35 | RSA_AES_256_CBC_SHA. Use the RSA public key algorithm with the AES cipher with CBC and 256 bit keys. Use SHA-1 for generating the MAC. |
| Y3 | ECDHE_ECDSA_3DES_EDE_CBC_SHA. Use the ECDHE key exchange algorithm with the ECDSA public key algorithm with the Triple Data Encryption Standard (3DES) cipher with the encrypt/decrypt/encrypt (EDE) and CBC modes and 168 bit keys. Use SHA-1 for generating the MAC. |
| Y6 | ECDHE_RSA_3DES_EDE_CBC_SHA. Use the ECDHE key exchange algorithm with the RSA public key algorithm with the 3DES cipher with the EDE and CBC modes and 168 bit keys. Use SHA-1 for generating the MAC. |
| 0A | RSA_3DES_EDE_CBC_SHA. Use the RSA public key algorithm with the 3DES cipher with the EDE and CBC modes and 168 bit keys. Use SHA-1 for generating the MAC. |
| Y2 | ECDHE_ECDSA_RC4_128_SHA. Use the ECDHE key exchange algorithm with the ECDSA public key algorithm with the Rivest Cipher 4 (RC4) cipher and 128 bit keys. Use SHA-1 for generating the MAC. |
| Y5 | ECDHE_RSA_RC4_128_SHA. Use the ECDHE key exchange algorithm with the RSA public key algorithm with the RC4 cipher and 128 bit keys. Use SHA-1 for generating the MAC. |
| 05 | RSA_RC4_128_SHA. Use the RSA public key algorithm with the RC4 cipher and 128 bit keys. Use SHA-1 for generating the MAC. |
| 04 | RSA_RC4_128_MD5. Use the RSA public key algorithm with the RC4 cipher and 128 bit keys. Use message digest algorithm 5 (MD5) for generating the MAC. |
| 09 | RSA_DES_CBC_SHA. Use the RSA public key algorithm with the Data Encryption Standard (DES) cipher with CBC mode and 56 bit keys. Use SHA-1 for generating the MAC. |
| 06 | RSA_EXPORT_RC2_CBC_40_MD5. Use the RSA public key algorithm with the Rivest Cipher 2 (RC2) cipher with CBC mode and 40 bit keys. Use MD5 for generating the MAC. |
| 03 | RSA_EXPORT_RC4_40_MD5. Use the RSA public key algorithm with the RC4 cipher and 40 bit keys. Use MD5 for generating the MAC. |
| Y1 | ECDHE_ECDSA_NULL_SHA. Use the Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange algorithm with the ECDSA signature algorithm but do not use any cipher. Use the Secure Hash Algorithm 1 (SHA-1) for generating the MAC. |
| Y4 | ECDHE_RSA_NULL_SHA. Use the ECDHE key exchange algorithm with the RSA public key algorithm but do not use any cipher. Use SHA-1 for generating the MAC. |
| 3B | RSA_NULL_SHA256. Use the RSA public key algorithm but do not use any cipher. Use SHA256 for generating the MAC. |
| 02 | RSA_NULL_SHA. Use the RSA public key algorithm but do not use any cipher. Use SHA-1 for generating the MAC. |
| 01 | RSA_NULL_MD5. Use the RSA public key algorithm but do not use any cipher. Use MD5 for generating the MAC. |
Transport Layer Security (TLS) protocols. The TLS protocol versions supported by this application. Unused array elements will contain hexadecimal zeros. The possible values follow:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 2 | SSLV3. Secure Sockets Layer version 3.0 will be supported. |
| 3 | TLSV1.0. Transport Layer Security version 1.0 will be supported. |
| 4 | TLSV1.1. Transport Layer Security version 1.1 will be supported. |
| 5 | TLSV1.2. Transport Layer Security version 1.2 will be supported. |
| 6 |
TLSV1.3. Transport Layer Security version 1.3 will be supported. |
Transport Layer Security (TLS) session cache time to live.
The length of time in seconds previously established TLS handshake session attributes remain valid for use in establishing a new secure connection.
The possible values follow:
| -1 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 0 | No caching done for TLS handshake attributes. |
| 1-86400 | Number of seconds the TLS handshake attributes cache entry will remain valid.
|
Transport Layer Security (TLS) signature algorithms for certificate. The TLS signature algorithms for a certificate supported by this application. This list only has meaning when the TLS version 1.2 or newer protocol is negotiated. Unused array elements will contain hexadecimal zeros. The possible values follow:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 1 | RSA with MD5 |
| 2 | RSA with SHA1 |
| 3 | RSA with SHA224 |
| 4 | RSA with SHA256 |
| 5 | RSA with SHA384 |
| 6 | RSA with SHA512 |
| 7 | ECDSA with SHA1 |
| 8 | ECDSA with SHA224 |
| 9 | ECDSA with SHA256 |
| A | ECDSA with SHA384 |
| B | ECDSA with SHA512 |
| C |
RSA_PSS_SHA256 |
| D | RSA_PSS_SHA384 |
| E | RSA_PSS_SHA512 |
| F | ED25519 |
Transport Layer Security (TLS) signature algorithms for key exchange. The TLS signature algorithms for key exchange supported by this application. This list only has meaning when the TLS version 1.2 or newer protocol is negotiated. Unused array elements will contain hexadecimal zeros.
The possible values follow:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 1 | RSA with SHA1 |
| 2 | RSA with SHA224 |
| 3 | RSA with SHA256 |
| 4 | RSA with SHA384 |
| 5 | RSA with SHA512 |
| 6 | ECDSA with SHA1 |
| 7 | ECDSA with SHA224 |
| 8 | ECDSA with SHA256 |
| 9 | ECDSA with SHA384 |
| A | ECDSA with SHA512 |
| B | RSA_PSS_SHA256 |
| C | RSA_PSS_SHA384 |
| D | RSA_PSS_SHA512 |
| E | ED25519 |
Trusted CA certificate entries. The entries for each of the trusted CA certificates. Refer to "Trusted CA Certificate Entry" for the format of an entry.
Trusted CA Certificate Entry
The following table shows the layout of the trusted CA certificate entry. For a detailed description of each field, see "Field Descriptions".
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next trusted CA certificate entry |
| 4 | 4 | BINARY(4) | Displacement to trusted CA certificate ID |
| 8 | 8 | BINARY(4) | Length of trusted CA certificate ID |
| 12 | C | BINARY(4) | CCSID of trusted CA certificate ID |
| 16 | 10 | CHAR(1) | Trusted CA certificate ID type |
| 17 | 11 | CHAR(1) | Trusted CA certificate ID converted indicator |
| 18 | 12 | CHAR(*) | Reserved |
| CHAR(*) | Trusted CA certificate ID | ||
Field Descriptions
CCSID of trusted CA certificate ID. The CCSID that the trusted CA certificate ID is returned in. The ID should be returned in the CCSID of the job. If a CCSID conversion error occurs, the ID will be returned in UCS-2 (unicode) CCSID.
Displacement to next trusted CA certificate entry. The displacement from the beginning of this entry to the next entry.
Displacement to trusted CA certificate ID. The displacement in the entry to the start of the trusted CA certificate ID.
Length of trusted CA certificate ID. The length of the trusted CA certificate ID. The length does not include the NULL terminator.
Reserved. An ignored field.
Trusted CA certificate ID. The ID for the trusted CA certificate. The CCSID of trusted CA certificate ID field indicates what CCSID the ID is returned in. The trusted CA certificate ID is a NULL terminated string.
Trusted CA certificate ID converted indicator. The indicator as to whether or not a CCSID conversion error occurred for the trusted CA certificate ID.
The possible values follow:
| 0 | There was no CCSID conversion error for the trusted CA certificate ID. The ID is returned in the CCSID of the job. |
| 1 | There was a CCSID conversion error for the trusted CA certificate ID. The CCSID of trusted CA certificate ID field indicates the CCSID that the ID was returned in. |
Trusted CA certificate ID type. The type of the trusted CA certificate ID.
The possible value follows:
| 1 | A trusted CA certificate ID is the label for the certificate. |
Format for Application Selection Criteria
This table shows the format for the application selection criteria parameter. For a detailed description of each field, see "Field Descriptions".
| Type | Field |
|---|---|
| BINARY(4) | Size of criteria entry |
| BINARY(4) | Comparison operator |
| BINARY(4) | Application control key |
| BINARY(4) | Length of comparison data |
| CHAR(*) | Comparison data |
Field Descriptions
Application control key. The application control to be compared. Refer to "Application Control Keys" for more information.
Comparison data. The data to compare to the application information.
Comparison operator. The comparison value to be used when comparing the application information with the comparison data.
The following value can be specified:
| 1 | The comparison data equals the application information. |
Length of comparison data. The length of the data to compare to the application information. The length of the comparison data must be valid for the application control key that is specified.
Size of criteria entry. The size of the selection criteria entry, including this field.
Application Control Keys
The following table shows the valid application control keys for the key field area of the selection control record. For a detailed description of each field, see "Field Descriptions".
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(100) | Application ID |
| 2 | CHAR(1) | Application type |
Field Descriptions
Application ID. The name of the applications to select.
The following can be specified for the application ID.
| generic* | All application IDs that begin with the generic string are selected. |
| Application ID | The specific application ID is selected. |
Application type. The type of applications to select.
The following can be specified for the application type.
| 1 | Server applications. |
| 2 | Client applications. |
| 4 | Object signing applications. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPF2225 E | Not able to allocate internal system object. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CD9 E | Requested function cannot be performed at this time. |
| CPF3CDA E | Registration facility repository not available for use. |
| CPF3CE4 E | Comparison operator &1 not valid for exit program selection criteria. |
| CPF3CE7 E | Number of selection criteria entries not valid. |
| CPF3CE9 E | Length of comparison data not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| 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: IBM® i 7.4
| Top | Security APIs | APIs by category |