SSL_Init_Application()--Initialize the Current Job for SSL Processing Based on the Application Identifier

Syntax

 #include <qsossl.h>


 int SSL_Init_Application(SSLInitApp*
  init_app)

  Service Program Name: QSOSSLSR

  Default Public Authority: *USE

  Threadsafe: Yes

The SSL_Init_Application() function is used to establish the SSL security information to be used for all SSL sessions for the current job based on the specified application identifier. The SSL_Init_Application() API uses the application identifier to determine and then establish the certificate and the associated public and private key information for use by the SSL handshake protocol processing when acting as a server or when acting as a client. The certificate and key information is needed by an application that is acting as a client in the situaitons where the client is connecting to a server which has enabled and requires client authentication.

Parameters

SSLInitApp * init_app (input)

The pointer to an SSLInitApp value. SSLInitApp is a typedef for a buffer of type struct SSLInitAppStr. In <qsossl.h>, struct SSLInitAppStr is defined as the following:

struct SSLInitAppStr {               /* SSLInitAppStr                  */
   char*          applicationID;        /* application id value        */
   unsigned int   applicationIDLen;     /* length of application id    */
   char*          localCertificate;     /* local certificate           */
   unsigned int   localCertificateLen;  /* ength of local certificate  */
   unsigned short int* cipherSuiteList; /* List of cipher suites       */
   unsigned int   cipherSuiteListLen;   /* number of entries in
                                           the cipher suites list      */
   unsigned int   sessionType;          /* the type of application as
                                           registered                  */
   unsigned int   reserved1;            /* reserved - must be 0        */
   unsigned int protocol;               /* SSL protocol version        */
   unsigned int timeout;                /* cache timeout (seconds)     */
   char reserved[12];                   /* reserved - must be NULL (0s)*/

};

The fields within the SSLInitApp structure as pointed to by init_app are defined as follows:

char *applicationID (input)

A pointer to a null terminated character string identifying the application identifier value that was used to register the application using the Register Application for Certificate Use, (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API. See the Register Application for Certificate Use API for information about the format and values allowed for the application identifier.

char *applicationIDLen (input)

The number of characters in the application identifier string as specified by the applicationID parameter.

char *localCertificate (input)

On input, the localCertificate pointer must be set to point to storage that has been allocated by the calling application that will be used on output to contain the application's registered local certificate. If a certificate is not to be returned then set this pointer's value to NULL and the localCertificateLen value to zero (0). The storage should be large enough to accomodate the size of the certificate. Most certificates are less than 2K in length. On output, the localCertificate pointer will not be changed, though the storage it points to will contain the registered application's certificate. The certificate will be the one registered for that application by the Register Application for Certificate Use (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API. See the Register Application for Certificate Use API for information about the format and values allowed for the application identifier.

unsigned int localCertificateLen (input)

On input, this value must equal the number of characters available in the storage pointed to by the localCertificate pointer. Set this value to 0 if you do not want a certificate returned by this API. On output, this value is equal to the length of the certificate. If the certificate will not fit into the storage provided, then this value will be set to the length required to contain the certificate.

unsigned short int* cipherSuiteList (input)

A pointer to the cipher specification list to be used during the SSL handshake protocol for this job. This list is a string of concatenated cipher specification values. A cipher specification value is an unsigned short integer. Any value provided will override any values provided by a previous SSL_Init_Application() API or SSL_Init() API or the system default cipher specification list if the previous SSL_Init_Application() API or SSL_Init() API did not provide a cipher specification list. A value of NULL for this parameter indicates one of the following:

Use the cipher specification list provided by a previous SSL_Init_Application() API or SSL_Init() API
Use the system default cipher specification list if a previous SSL_Init_Application() API or SSL_Init() API was not done

The caller specifies the preferred order of the cipher specifications. The cipher specification values, shown here not in preferred or strength order, are defined in <qsossl.h> as the following:

C Constant	Hex	System Value
TLS_RSA_WITH_NULL_MD5	0x0001	*RSA_NULL_MD5
TLS_RSA_WITH_NULL_SHA	0x0002	*RSA_NULL_SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5	0x0003	*RSA_EXPORT_RC4_40_MD5
TLS_RSA_WITH_RC4_128_MD5	0x0004	*RSA_RC4_128_MD5
TLS_RSA_WITH_RC4_128_SHA	0x0005	*RSA_RC4_128_SHA
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5	0x0006	*RSA_EXPORT_RC2_CBC_40_MD5
TLS_RSA_WITH_DES_CBC_SHA	0x0009	*RSA_DES_CBC_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA	0x000A	*RSA_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA	0x002F	*RSA_AES_128_CBC_SHA	(TLS Version 1.x only)
TLS_RSA_WITH_AES_256_CBC_SHA	0x0035	*RSA_AES_256_CBC_SHA	(TLS Version 1.x only)
TLS_RSA_WITH_NULL_SHA256	0x003B	*RSA_NULL_SHA256	(TLS Version 1.2 only)
TLS_RSA_WITH_AES_128_CBC_SHA256	0x003C	*RSA_AES_128_CBC_SHA256	(TLS Version 1.2 only)
TLS_RSA_WITH_AES_256_CBC_SHA256	0x003D	*RSA_AES_128_CBC_SHA256	(TLS Version 1.2 only)
TLS_RSA_WITH_RC2_CBC_128_MD5	0xFF01	*RSA_RC2_CBC_128_MD5	(SSL Version 2 only)
TLS_RSA_WITH_DES_CBC_MD5	0xFF02	*RSA_DES_CBC_MD5	(SSL Version 2 only)
TLS_RSA_WITH_3DES_EDE_CBC_MD5	0xFF03	*RSA_3DES_EDE_CBC_MD5	(SSL Version 2 only)

Notes:

The SSL_RSA_EXPORT_WITH_DES40_CBC_SHA cipher is not supported by IBM^® i.

The default cipher suite list in preference order when the operating system is installed is as follows:
Start of change

      C Constant                    System Value
TLS_RSA_WITH_AES_128_CBC_SHA256   *RSA_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA      *RSA_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA256   *RSA_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA      *RSA_AES_256_CBC_SHA

The current default cipher suite list can be different from the install time list due to changes made to the QSSLCSL (SSL cipher specification list) system value via the Change System Value (CHGSYSVAL) command. A cipher suite removed from the SSL cipher specification list will also be removed from the default cipher suite list shown here. A cipher suite removed from the eligible default cipher specification list using System Service Tools (SST) Advanced Analysis Command SSLCONFIG will also be removed from the default cipher suite list shown here. For additional information see the help text for SSLCONFIG. The order of the cipher suites in QSSLCSL will be used to order the cipher suites in the default list.
The Display System Value (DSPSYSVAL) command or the Retrieve System Values (QWCRSVAL) API can be used to determine the current setting of the supported ciphers (QSSLCSL) for system SSL.

unsigned int cipherSuiteListLen (input)

The number of cipher suite entries specified in the list pointed to by the cipherSuiteList parameter.

unsigned int sessionType (output)

The type registered for the application. The following values are returned in sessionType and are defined in <qsossl.h>.

      SSL_REGISTERED_AS_CLIENT                            0
      SSL_REGISTERED_AS_SERVER                            1
      SSL_REGISTERED_AS_SERVER_WITH_CLIENT_AUTH           2
      SSL_REGISTERED_AS_SERVER_WITH_OPTIONAL_CLIENT_AUTH  3
      SSL_REGISTERED_AS_NOT_SPECIFIED                     99

unsigned int reserved1 (input)

This reserved field must be set to 0.

unsigned int protocol (input)

The protocol(s) that are acceptable as the handshake protocol for this job. The following values may be specified for protocol and are defined in <qsossl.h>.

Start of change

      SSL_VERSION_CURRENT          0  (Uses the default protocols as determined by
                                       the intersection of Security system value
                                       QSSLPCL and the eligible default protocols
                                       from the SSLCONFIG macro)
      SSL_VERSION_2                2  (SSL Version 2.0 only)
      SSL_VERSION_3                3  (SSL Version 3.0 only)
      TLS_VERSION_1                4  (TLS Version 1.0 only)
      TLSV1_SSLV3                  5  (TLS Version 1.0 with SSL Version 3.0 compatibility)
      TLS_VERSION_1_0              6  (TLS Version 1.0 only)
      TLS_VERSION_1_1              7  (TLS Version 1.1 only)
      TLS_VERSION_1_2              8  (TLS Version 1.2 only)
      TLSV12_TLSV11_TLSV10         9  (TLS Version 1.x only)
      TLSV12_TLSV11_TLSV10_SSLV3   10 (TLS Version 1.x with SSL Version 3.0 compatibility)

unsigned int timeout (input)

The time period (in seconds) for which TLS Version 1.0 and SSL Version 3.0 session parameters are cached for use with abbreviated SSL handshakes. The valid range for timeout is from 1 to 86,400 seconds (24 hours). Not specifying a value (0) will default to the maximum timeout, and specifying a value of 0xffffffff will disable caching. The following values are defined in <qsossl.h>.

      SSL_TIMEOUT_DEFAULT  0          (Use default timeout, 24 hours)
      SSL_TIMEOUT_MAX      86400      (Use maximum timeout, 24 hours)
      SSL_TIMEOUT_DISABLE  0xffffffff (Disable caching of session parameters
                                       for abbreviated handshakes)

char reserved[12] (input)

This reserved field must be set to NULL (0s).

Authorities

Authorization of *R (allow access to the object) to the key database file and its associated files is required. The certificate is stored in a key database file.

Return Value

The SSL_Init_Application() API returns an integer. Possible values are:

[0]

Successful return

[SSL_ERROR_BAD_CIPHER_SUITE]

A cipher suite that is not valid was specified.

[SSL_ERROR_CERT_EXPIRED]

The validity time period of the certificate is expired.

[SSL_ERROR_KEYPASSWORD_EXPIRED]

The specified key ring password has expired.

[SSL_ERROR_NO_KEYRING]

No key ring file was found.

[SSL_ERROR_NOT_REGISTERED]

The application identifier is not registered with the certificate registry facility.

[SSL_ERROR_NOT_TRUSTED_ROOT]

The certificate is not signed by a trusted certificate authority.

[SSL_ERROR_NO_CERTIFICATE]

No certificate is available for SSL processing.

[SSL_ERROR_IO]

An error occurred in SSL processing; check the errno value.

[SSL_ERROR_SSL_NOT_AVAILABLE]

SSL is not available for use.

[SSL_ERROR_UNSUPPORTED]

Operation is not supported by SSL.

None of the specified protocol or cipher values are supported by System SSL.

[SSL_ERROR_UNKNOWN]

An unknown or unexpected error occurred during SSL processing.

Error Conditions

When the SSL_Init_Application() API fails with return code [SSL_ERROR_IO], errno can be set to:

[EINVAL]

Parameter not valid.

[EACCES]

Permission denied.

This error code indicates one of the following:

The applicationID field contains a registered application identifier to which the user is not authorized.
The user profile, which the application is operating under, is not authorized to the key database file or its associated files.

[EFAULT]

Bad address.

The system detected an address that was not valid while attempting to access the init_app parameter or one of the address fields in the init_app parameter.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EUNKNOWN]

Unknown system state.

Error Messages

Message ID	Error Message Text
CPE3418 E	Possible APAR condition or hardware failure.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA081 E	Unable to set return value or error code.

Usage Notes

Before the SSL_Init_Application() API can be used, the user must have registered the application using the Register Application for Certificate Use (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API. The Register Application For Certificate Use API registers an application with the registry facility, allowing an application to be associated with a specific certificate. The Register Application for Certificate Use is described in the System Programming Interface Reference. If the applicaiton is not registered with the registry facility, then an error of SSL_ERROR_NOT_REGISTERED will be returned by SSL_Init_Application().
A successful SSL_Init(), SSL_Init (using NLS-enabled path name), or an SSL_Init_Application() API must be used to enable a job for SSL processing before attempting to use any other SSL API.
If multiple SSL_Init_Application(), SSL_Init (using NLS-enabled path name), or multiple SSL_Init() APIs are performed in a job, then only the values associated with the last SSL_Init_Application(), SSL_Init (using NLS-enabled path name), or SSL_Init() performed are used.
If the SSL_Init_Application() API or SSL_Init() API are both performed in the same job, then only the values associated with the last API performed are used.
The reserved fields in the SSLInitApp structure must be set to NULLs (0s) before using this API.
The Change System Value (CHGSYSVAL) command allows an administrator to disable protocols or ciphers from being used by the SSL_ APIs. For backwards compatibility, SSL_ support will silently ignore attempts by applications to use disabled protocols or ciphers unless only disabled values are used. SSL_ERROR_UNSUPPORTED will be returned when no enabled values are specified.
The Application ID definition configured using Digital Certificate Manager (DCM) can be used to override what this function has set for the SSL security information. The SSL_ interface has no way for a programmer to determine if DCM over rode information. Beginning with the 7.1 TR6 release, there are SSL security information attributes configurable in DCM that the SSL_ API interface is unaware of existing. Those attributes will be used to the best of System SSL's ability on behalf of SSL_ applications. To make full use of this new support, an application must be coded to the GSK API family.

Related Information

QlgSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name)
SSL_Create()--Enable SSL Support for the Specified Socket Descriptor
SSL_Destroy()--End SSL Support for the Specified SSL Session
SSL_Init()--Initialize the Current Job for SSL
SSL_Handshake()--Initiate the SSL Handshake Protocol
SSL_Read()--Receive Data from an SSL-Enabled Socket Descriptor
SSL_Write()--Write Data to an SSL-Enabled Socket Descriptor
The SSLCONFIG macro--The SSLCONFIG macro allows viewing or altering system-wide System SSL default properties.
Security system values: Secure Sockets Layer protocols--The Secure Sockets Layer protocols system value is also known as QSSLPCL. You can use this system value to specify the Secure Sockets Layer (SSL) protocols supported by the System SSL.

API introduced: V4R4

Top | UNIX-Type APIs | APIs by category