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

 #include <qsossl.h>


 int SSL_Init_Application(SSLInitApp*
  init_app)

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 on 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 on 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:

      TLS_RSA_WITH_NULL_MD5              0x0001
      TLS_RSA_WITH_NULL_SHA              0x0002
      TLS_RSA_EXPORT_WITH_RC4_40_MD5     0x0003
      TLS_RSA_WITH_RC4_128_MD5           0x0004
      TLS_RSA_WITH_RC4_128_SHA           0x0005
      TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 0x0006
      TLS_RSA_WITH_DES_CBC_SHA           0x0009
      TLS_RSA_WITH_3DES_EDE_CBC_SHA      0x000A
      TLS_RSA_WITH_AES_128_CBC_SHA       0x002F
      TLS_RSA_WITH_AES_256_CBC_SHA       0x0035
      TLS_RSA_WITH_RC2_CBC_128_MD5       0xFF01
      TLS_RSA_WITH_DES_CBC_MD5           0xFF02
      TLS_RSA_WITH_3DES_EDE_CBC_MD5      0xFF03

Notes:

1. The SSL_RSA_EXPORT_WITH_DES40_CBC_SHA cipher is not supported by i5/OS.
   
   
2. The default cipher suite list in preference order is as follows:

   TLS_RSA_WITH_RC4_128_MD5
   TLS_RSA_WITH_RC4_128_SHA
   TLS_RSA_WITH_AES_128_CBC_SHA
   TLS_RSA_WITH_AES_256_CBC_SHA
   TLS_RSA_WITH_3DES_EDE_CBC_SHA
   TLS_RSA_WITH_DES_CBC_SHA
   TLS_RSA_WITH_DES_CBC_MD5
   TLS_RSA_WITH_3DES_EDE_CBC_MD5
   TLS_RSA_WITH_RC2_CBC_128_MD5
   TLS_RSA_EXPORT_WITH_RC4_40_MD5
   TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
   

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

      SSL_VERSION_CURRENT  0  (TLS with SSL Version 3.0 and SSL
                               Version 2.0 compatibility)
      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 only)
      TLSV1_SSLV3          5  (TLS Version 1 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_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

Usage Notes

1. 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().
   
   
2. 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.
   
   
3. 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.
   
   
4. 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.
   
   
5. The reserved fields in the SSLInitApp structure must be set to NULLs (0s) before using this API.

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