Register Application for Certificate Use (QSYRGAP, QsyRegisterAppForCertUse) API

 #include <qsyrgap1.h>

 void QsyRegisterAppForCertUse
        (char                *Application_ID,
         int                 *Length_of_application_ID,
         Qsy_App_Controls_T  *Application_controls,
         void                *Error_code);

The 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.

Authorities and Locks

API Public Authority

*EXCLUDE

Registration Lock

*EXCL

Required Parameter Group

Application ID

INPUT; CHAR(*)

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

Length of application ID

INPUT; BINARY(4)

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.

Application controls

INPUT; CHAR(*)

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Format for Variable Length Record

The following table shows the layout of the variable length record. For a detailed description of each field, see Field Descriptions.

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.

Field Descriptions

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.

Application Control Keys

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

Field Descriptions

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:

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:

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:

If you do use the threadsafe value to determine the value for the multithreaded job action, consider the following recommendations:

1. If the threadsafe value is 0, the multithreaded job action should be set to 3.
   
   
2. If the threadsafe value is 1, the multithreaded job action should be set to 0.
   
   
3. If the threadsafe value is 2, the multithreaded job action should be set to 1.

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.

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:

• OCSP URL is set to the URL of the OCSP responder. OCSP will be used for revocation status checking regardless of whether the certificate has an AIA extension or not, so it will work with existing certificates.
• Perform Online Certificate Status Protocol (OCSP) checking is set to "Enable AIA OCSP". OCSP will be used if the certificate being validated has an AIA extension with a PKIK_AD_OCSP access method containing a URI of the location of the OCSP responder.

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.

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.
9C	RSA_AES_128_GCM_SHA256. Use the Rivest Shamir Adleman (RSA) public key algorithm with the Advanced Encryption Standard (AES) cipher with Galois/Counter Mode (GCM) and 128 bit keys. Use the Secure Hash Algorithm 256 (SHA256) for generating the message authentication code (MAC).
9D	RSA_AES_256_GCM_SHA384. Use the RSA public key algorithm with the AES cipher with GCM and 256 bit keys. Use the Secure Hash Algorithm 384 (SHA384) for generating the MAC.
Y1	ECDHE_ECDSA_NULL_SHA. Use the Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange algorithm with the Elliptic Curve Digital Signature Algorithm (ECDSA) signature algorithm but do not use any cipher. Use the Secure Hash Algorithm 1 (SHA-1) for generating the MAC.
Y2	ECDHE_ECDSA_RC4_128_SHA. Use the ECDHE key exchange algorithm with the ECDSA signature algorithm with the Rivest Cipher 4 (RC4) cipher and 128 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 signature algorithm with the Triple Data Encryption Standard (3DES) cipher with the encrypt/decrypt/encrypt (EDE) and cipher block chaining (CBC) modes and 168 bit keys. Use 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.
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.
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.
Y7	ECDHE_ECDSA_AES_128_CBC_SHA256. Use the ECDHE key exchange algorithm with the ECDSA signature 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 signature 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.
YB	ECDHE_ECDSA_AES_128_GCM_SHA256. Use the ECDHE key exchange algorithm with the ECDSA signature algorithm 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 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.
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.
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.
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.
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
7	ECDSA with SHA1
8	ECDSA with SHA224
9	ECDSA with SHA256
A	ECDSA with SHA384
B	ECDSA 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:

Qualified Message File Format

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.

Field Descriptions

Message file library name. The library name in which the message file resides. The special value *CURLIB is not supported. The possible values are:

Message file name. The name of the message file that contains the application description.

Message identifier. The message identifier for the application description.

Error Messages

[ Back to top | Security APIs | APIs by category ]