13
14151617181920| 1 | Application ID | Input | Char(*) |
| 2 | Length of application ID | Input | Binary(4) |
| 3 | Application controls | Input | Char(*) |
| 4 | Error Code | I/O | Char(*) |
#include <qsyrgap1.h>
void QsyRegisterAppForCertUse
(char *Application_ID,
int *Length_of_application_ID,
Qsy_App_Controls_T *Application_controls,
void *Error_code);
Service Program: QSYRGAP1The Register Application For Certificate Use (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API registers an application with the registration facility. The application controls provide additional information needed to define the application.
You can update an application entry by reregistering the application (using the replace control key) with new values for the application control keys.
The application type control key is set the first time the application is registered and cannot be changed.
When an application is registered, the registration information is stored using the Registration Facility.
The application ID to register. IBM-supplied IBM i applications are named QIBM_ccc_name, where ccc is the component identifier. User-supplied application IDs should not preface their application ID with QIBM. User-supplied application IDs should start with the company name to eliminate most problems that involve unique names. Application IDs should use an underscore (_) to separate parts of the name (for example, QIBM_I5OS_HOSTSERVER). Also, IDs for related applications should start with the same name (for example, QIBM_DIRSRV_SERVER and QIBM_DIRSRV_REPLICATION).
The first character of the application ID must be one of the following:
| A-Z | Uppercase A-Z |
The remaining characters in the application ID must be made up of the following characters:
| A-Z | Uppercase A-Z |
| 0-9 | Digits 0-9 |
| . | Period |
| _ | Underscore |
The length of the specified application ID. The length must be a value from 1 to 100. If the application type is 4 (object signing application), then the length must be a value from 1 to 30.
The application control fields for defining the application. Any field not specified will be given the default value. The information must be in the following format:
| Number of variable length records | BINARY(4) The total number of all of the variable length records. |
| Variable length records | The fields of the application controls to set. Refer to Format for Variable Length Record for more information. |
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table shows the layout of the variable length record. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of variable length record |
| 4 | 4 | BINARY(4) | Application control key |
| 8 | 8 | BINARY(4) | Length of data |
| 12 | C | CHAR(*) | Data |
If the length of the data is longer than the key field's data length, the data is truncated at the right. No message is issued.
If the length of the data is shorter than the key field's data length and the key contains binary data, an error message is issued. If the key does not contain binary data, the field is padded with blanks.
It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.
Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.
Refer to Application Control Keys for more information about the valid values for these fields.
Data. The value to which a specific application control is to be set.
Length of data. The length of the application control value.
Length of variable length record. The length of the record, including this field.
The following table shows the valid application control keys for the application control key field of the variable length record. For a detailed description of each field, see Field Descriptions.
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(20) | Qualified exit program name |
| 2 | CHAR(50) | Application description |
| 3 | CHAR(27) | Qualified message file name and message identifier for application description |
| 4 | CHAR(1) | Limit CA certificates trusted |
| 5 | CHAR(1) | Replace |
| 6 | CHAR(1) | Threadsafe |
| 7 | CHAR(1) | Multithreaded job action |
| 8 | CHAR(1) | Application type |
| 9 | CHAR(10) | Application user profile |
| 10 | CHAR(1) | Client authentication supported |
| 11 | CHAR(1) | Client authentication required |
| 12 | CHAR(1) | Perform certificate revocation processing |
| 13 |
Array(10) of CHAR(1) | Secure sockets layer (SSL) protocols |
| 14 |
Array(64) of CHAR(2) | Secure sockets layer (SSL) cipher specifications list |
| 15 |
Array(32) of CHAR(1) | Secure sockets layer (SSL) signature algorithms |
| 16 |
CHAR(1) | Perform Online Certificate Status Protocol (OCSP) checking |
| 17 |
CHAR(128) | Online Certificate Status Protocol (OCSP) URL |
| 18 |
CHAR(1) | Extended renegotiation critical mode |
| 19 |
CHAR(128) | Server Name Indication (SNI) |
| 20 |
CHAR(16) | Special indicators |
Application type. The type of application. This control is set when the application is registered and cannot be changed. The default value is 1. Valid values for this key are:
| 1 | Server application. A server application provides a service for another process on the system, host, or network. |
| 2 | Client application. A client application requests a service from another process on the system, host, or network. |
| 4 | Object signing application. This application is used when signing objects. The application ID for this application can be specified on the Sign Object (QYDOSGNO) API. When an object signing application is registered, a corresponding function is registered with the same ID (see Register Function (QSYRGFN, QsyRegisterFunction) API). A user must have access to the corresponding function to sign objects using this application ID. By default, only users with *ALLOBJ special authority will have access to the corresponding function. |
Application user profile. The user profile associated with the application. This is the user profile under which the application runs. If a user profile name is specified, then the specified user profile is given access to the QIBM_QSY_SYSTEM_CERT_STORE function (see Register Function (QSYRGFN, QsyRegisterFunction) API). This function gives the specified user profile access to the *SYSTEM certificate store without having to be authorized to the actual object, but only when using the certificate associated with the application to establish a secure session. The default value is *NONE. The following special value may be specified:
| *NONE | No user profile will be associated with the application. This value must be specified if the application type is 4 (object signing application). |
Client authentication required. Whether client
authentication is required. The value of this field augments the existing client authentication support configured internally in the program. The default value is 0.
| 0 | No client authentication is
done. This setting will not disable internally configured optional or required client authentication. |
| 1 | Client authentication is required. The
client is authenticated as part of the SSL handshake protocol processing.
During the SSL handshake processing, the server requests a certificate
from the client. The certificate must be valid and must be signed by a
Certificate Authority (CA) that the server recognizes and trusts. If the
client does not have a valid certificate, then the server ends the SSL
handshake and does not establish an SSL session between the client and
server. If the program is internally configured for optional client authentication then optional client authentication will be used instead of required. |
Client authentication supported. This field has been deprecated. Its value has no meaning to the application.
Extended renegotiation critical mode. RFC 5746 renegotiation indication requirement level. The default value is 0. Valid values for this key are:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 1 | Enable RFC 5746 critical mode. The peer must provide RFC 5746 renegotiation indication during the initial handshake in order for the handshake to be successful. Warning - This application will no longer be able to handshake with peers that have not or cannot be updated to support RFC 5746. |
| 2 | Disable RFC 5746 critical mode. RFC 5746 renegotiation indication from the peer is not required on initial handshake. RFC 5746 renegotiation indication will still be required for all renegotiated handshakes. |
Limit CA certificates trusted. Whether the application trusts all of the CA certificates that are trusted in the *SYSTEM certificate store or a subset of the CA certificates. A client application uses the list of trusted CA certificates to validate the peer certificate that is sent to the application. A server application that supports client authentication uses the list of trusted CA certificates to validate the certificate that is sent from the client. The default value is 1.
| 0 | The application trusts all the CA certificates that are trusted in the *SYSTEM certificate store. This value must be specified if the application type is 4 (object signing application). This value is recommended for server applications that do not support client authentication. |
| 1 | The application trusts a subset of the list
of CA certificates that are trusted in the *SYSTEM certificate store. If
this value is specified, the system administrator must specify which of
the CA certificates that are trusted in the *SYSTEM certificate store also
are trusted by the application. Otherwise, the application will trust
all of the CA certificates. Using Digital Certificate Manager (DCM),
the system administrator can add and remove CA certificates from the list of
trusted CA certificates for the application. |
Multithreaded job action. The action to take in a multithreaded job. This key has no direct relationship with the threadsafe key; however, the value for the threadsafe key can be used to determine the multithreaded job action. The default value is 0. Valid values for this key are:
| 0 | Use the QMLTTHDACN system value to determine the action to take. |
| 1 | Run the exit program in a multithreaded job. |
| 2 | Run the exit program in a multithreaded job and send informational message CPI3C80. |
| 3 | Do not run the exit program in a multithreaded job and send informational message CPI3C80. |
If you do use the threadsafe value to determine the value for the multithreaded job action, consider the following recommendations:
Online Certificate Status Protocol (OCSP) URL. The URL of the Online Certificate Status Protocol (OCSP) responder to query during certificate validation. This attribute has precedence over Authority Information Access (AIA) OCSP.
See description of Perform Online Certificate Status Protocol (OCSP) checking to see how this field interoperates with that field.
The url-value is case insensitive and cannot contain imbedded blanks. The default value is *PGM. The length specified for the length of data can be from 4 to 128 bytes. Valid values for this key are:
| *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 | Specify the URL to use. HTTP is the only supported protocol; therefore this value must begin with "http://". |
Perform certificate revocation processing. Whether certificate revocation processing is performed when the certificate associated with the application is validated. The default value is 0.
| 0 | Certificate revocation processing is not performed when the certificate associated with the application is validated. If the certificate has been revoked, it will still be considered valid. |
| 1 | Certificate revocation processing is performed when the certificate associated with the application is validated. If the certificate has been revoked, it will not be valid. |
Perform Online Certificate Status Protocol (OCSP) checking. Perform OCSP certificate revocation checking using Authority Information Access (AIA) certificate extension information. If the certificate being validated has an AIA extension, the first OCSP responder identified in the AIA extension will be queried for revocation status. The default value is 0.
There are two ways to enable OCSP that can be used either separately or together:
When both attributes are set the Perform Online Certificate Status Protocol (OCSP) checking functionality will only be used if OCSP URL functionality results in an undetermined revocation status. The definition of undetermined revocation status is located in the Secure Sockets Layer topic.
Note: Using OCSP results in a performance impact to System SSL.
Valid values for this key are:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. |
| 1 | Enable AIA OCSP checking. |
| 2 | Disable AIA OCSP checking. |
Qualified exit program name. The exit program name and library for the application. The first 10 characters contain the exit program name; the next 10 characters contain the library name in which the exit program resides. The exit program does not need to exist at registration time. A specific library name must be specified. The special values *LIBL and *CURLIB are not supported. The default value is program QSY_NOPGM in library QSY_NOLIB.
This exit program is called when a certificate is assigned to the application, an assigned certificate is changed, or an assigned certificate is removed. It is called when a Certificate Authority (CA) certificate is added to or removed from the list of trusted CA certificates for the application. It also is called when an attempt is made to deregister the application. The exit program can determine whether or not the application can be deregistered. This exit program also is called when the information for a registered application is updated. See Digital Certificate Management Exit Programs for detailed information about the information that is passed to the exit program for each of the possible calls to the program.If the exit program is the default value, then it will not be called.
Qualified message file name and message identifier for application description. A message file and message identifier that contains the application description. When this key is specified, the application description key must not be specified. The message file and message identifier do not have to exist at the time of registration. The default value is blanks. See Qualified Message File Format for the format of this field.
Replace. Whether to replace an existing registered application. The default value is 0.
| 0 | Do not replace an existing registered application. If this value is specified and the application is already registered, the request will fail. |
| 1 | Replace an existing registered application. If this value is specified and the application is not already registered, the application will be registered. If the application is already registered, only the application control keys that are specified on this call are replaced. Any other application control keys that were previously specified will keep their values. |
| 2 | Replace an existing registered application, but do not
replace application control keys that are controlled by a system administrator. If this
value is specified and the application is not already registered, the application
will be registered. If the application is already registered, only the application
control keys that are specified on this call are replaced. Any other application
control keys that were previously specified will keep their values. Application
control keys that are controlled by a system administrator are not replaced, even
if they are specified on this call. These application control keys include:
This value should be used by install exit programs to ensure that values set by the system administrator are not replaced by the install exit program. |
Secure sockets layer (SSL) cipher specifications list. The list of cipher suites that are supported by this application. Multiple values may be specified with a maximum of 64 values. The order of use is determined by the order of specification within the array. The first value in the array is the first cipher specification used, the second value in the array is the second cipher specification used, etc. The length specified for the length of data should include only the elements in the array containing data. If '3C2F35' is specified for the data, the length of data should be 6. Cipher suites that are specified in the array but not enabled by the QSSLCSL system value are ignored when at least one cipher suite specified in the array is enabled in QSSLCSL.
Use extreme caution when considering specifying a list. A change from the default could weaken security due to positioning a relatively weak encryption algorithm before a relatively strong encryption algorithm. The flexibility of the user defined list allows for a weaker security configuration than may be possible with the default value.
The default value is 00. Valid values for this key are:
| 00 | Use the runtime value that was set by the underlying application and its configuration, do not override. If this value is specified, no other values can be specified. |
| 3C | RSA_AES_128_CBC_SHA256. Use the Rivest Shamir Adleman (RSA) public key algorithm with the Advanced Encryption Standard (AES) cipher with cipher block chaining (CBC) and 128 bit keys. Use the Secure Hash Algorithm 256 (SHA256) for generating message authentication codes (MAC). |
| 2F | RSA_AES_128_CBC_SHA. Use the RSA public key algorithm with the AES cipher with CBC and 128 bit keys. Use Secure Hash Algorithm 1 (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. |
| 05 | RSA_RC4_128_SHA. Use the RSA public key algorithm with the Rivest Cipher 4 (RC4) cipher and 128 bit keys. Use SHA-1 for generating the MAC. |
| 0A | RSA_3DES_EDE_CBC_SHA. Use the RSA 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| X3 | RSA_RC2_CBC_128_MD5. Use the RSA public key algorithm with the RC2 cipher with CBC mode and 128 bit keys. Use MD5 for generating the MAC. Note: This cipher is only valid for use with SSLv2. |
| X7 | RSA_3DES_EDE_CBC_MD5. Use the RSA public key algorithm with the 3DES cipher with the EDE and CBC modes and 168 bit keys. Use MD5 for generating the MAC. Note: This cipher is only valid for use with SSLv2. |
| X6 | RSA_DES_CBC_MD5. Use the RSA public key algorithm with the DES cipher with the CBC mode and 56 bit keys. Use MD5 for the MAC. Note: This cipher is only valid for use with SSLv2. |
Secure sockets layer (SSL) protocols. The SSL protocol versions supported by this application. Multiple values may be specified with a maximum of 10 values. The length specified for the length of data should include only the elements in the array containing data. If '234' is specified for the data, the length of data should be 3. The default value is 0. Valid values for this key are:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. If this value is specified, no other values can be specified. |
| 1 | SSLV2. Secure Sockets Layer version 2.0 will be supported. If this value is specified then TLSV1.2 cannot be specified. |
| 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. If this value is specified then SSLV2 cannot be specified. |
Secure sockets layer (SSL) signature algorithms. The SSL signature algorithms supported by this application. This list only has meaning when the TLS version 1.2 protocol is negotiated. Multiple values may be specified with a maximum of 32 values. The order of use is determined by the order of specification within the array. The first value in the array is the first signature algorithm used, the second value in the array is the second signature algorithm used, etc. The length specified for the length of data should include only the elements in the array containing data. If '234' is specified for the data, the length of data should be 3. The default value is 0. Valid values for this key are:
| 0 | Use the runtime value that was set by the underlying application and its configuration, do not override. If this value is specified, no other values can be specified. |
| 1 | RSA with MD5 |
| 2 | RSA with SHA1 |
| 3 | RSA with SHA224 |
| 4 | RSA with SHA256 |
| 5 | RSA with SHA384 |
| 6 | RSA with SHA512 |
Server Name Indication (SNI). A fully qualified domain name (FQDN) to be set for the server. If the client TLS SNI request is not matched, the server session will use the configured certificate with no SNI acknowledgement. Robust use of SNI support requires using the GSKit APIs. The SNI is case insensitive and cannot contain imbedded blanks. The default value is hexadecimal zeros. The length specified for the length of data can be from 0 to 128. Specify a length of 0 to remove an existing SNI value.
Special indicators. Text field containing special indicators. Do not use this field unless instructed by IBM. The default value is hexadecimal zeros. The length specified for the length of data can be from 0 to 16. Specify a length of 0 to remove an existing special indicators value.
Threadsafe. Whether the exit program entry is threadsafe. This key has no direct relationship with the multithreaded job action key. It is intended for documentation purposes only. The default value is 1. Valid values for this key are:
| 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. |
The following table shows the layout of the qualified message file name and message identifier for the application description field. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Message file name |
| 10 | A | CHAR(10) | Message file library name |
| 20 | 14 | CHAR(7) | Message identifier |
Message file library name. The library name in which the message file resides. The special value *CURLIB is not supported. The possible values are:
| *LIBL | Search the library list for the message file. This value uses the first message file in the library list that contains the message identifier. |
| library name | The name of the message library in which the message file resides. |
Message file name. The name of the message file that contains the application description.
Message identifier. The message identifier for the application description.
| Message ID | Error Message Text |
|---|---|
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPF2225 E | Not able to allocate internal system object. |
| CPF222E E | &1 special authority is required. |
| CPF220E E | Application &1 not registered. |
| CPF220F E | Application &1 already registered. |
| CPF229E E | Application ID &1 not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C83 E | Key &1 not allowed with value specified for key &2. |
| CPF3C84 E | Key &1 required with value specified for key &2. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| 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. |
| 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. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Security APIs | APIs by category ]