Register Application for Certificate Use (QSYRGAP, QsyRegisterAppForCertUse) API

  Required Parameter Group for QSYRGAP:

1	Application ID	Input	Char(*)
2	Length of application ID	Input	Binary(4)
3	Application controls	Input	Char(*)
4	Error Code	I/O	Char(*)

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

  Syntax for QsyRegisterAppForCertUse:

 #include <qsyrgap1.h>

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

  Service Program: QSYRGAP1

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

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 iSeries applicationss 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_OS400_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.

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 default value is 0.

Client authentication supported. Whether the application supports client authentication. The default value is 0.

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.

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.

Perform certificate revocation processing. Whether certificate revocation processing is performed when the certificate associated with the application is validated. The default value is 0.

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. Refer to 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. Refer to Qualified Message File Format for the format of this field.

Replace. Whether to replace an existing registered application. The default value is 0.

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