QlgSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name)

 #include <qsossl.h>

 int QlgSSL_Init(QlgSSLInit* init)

The QlgSSL_Init() function is used to establish the SSL security information to be used for all SSL sessions for the current job. The QlgSSL_Init() API establishes a certificate and private key for use by the handshake protocol processing when acting as a server. The QlgSSL_Init() API establishes a certificate for use by the handshake protocol processing when acting as a client that is connected to a server performing client authentication.

Parameters

QlgSSLInit * init  (input) 

The pointer to a QlgSSLInit structure. QlgSSLInit is a typedef for a buffer of type struct QlgSSLInitStr. In <qsossl.h>, struct QlgSSLInitStr is defined as the following:

struct QlgSSLInitStr {                /* QlgSSLInitStr               */

   Qlg_Path_Name* keyringFileName;    /* Key ring file name          */
   char*          keyringPassword;    /* Key ring file password      */
   unsigned short int* cipherSuiteList; /* List of cipher suites     */
   unsigned int        cipherSuiteListLen; /* number of entries in
                                              the cipher suites list */
};

The fields within the QlgSSLInit structure as pointed to by init are defined as follows:

Qlg_Path_Name_T *keyringFileName  (input) 

A pointer to a structure defining the path to the key ring file. This structure defines the coded character set identifier (CCSID) and the path to the key ring file to be used for this job's SSL processing. The path must be a fully qualified integrated file system file name.

char *keyringPassword  (input) 

A pointer to the password for the key ring file named in the keyringFileName field.

If this parameter's value is equal to NULL, then the QlgSSL_Init() support will attempt to extract a password from a key-ring password file.

This parameter is assumed to be represented in the same CCSID (coded character set identifier) as the keyringFileName.

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 QlgSSL_Init() API or the system default cipher specification list if the previous QlgSSL_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 QlgSSL_Init() API
• Use the system default cipher specification list if a previous QlgSSL_Init() API was not done

The caller specifies the preferred order of the cipher specifications. The cipher specification values 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_EXPORT_WITH_DES40_CBC_SHA  0x0008
      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.

Authorities

Authorization of *R (allow access to the object) to the key ring file and its associated files is required.

Return Value

The QlgSSL_Init() 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_IO]

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

[SSL_ERROR_KEYPASSWORD_EXPIRED]

The specified key ring password has expired.

[SSL_ERROR_NO_KEYRING]

No key ring file was specified.

[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 QlgSSL_Init() API fails with return code [SSL_ERROR_IO], errno can be set to:

[EINVAL]

Parameter not valid.

This error code indicates that the Qlg_Path_Name_T structure was not valid:

• The path type was less than 0 or greater than 3.
• A reserved field was not initialized to zeros.

[ECONVERT]

Conversion error.

This error code indicates one of the following:

• The CCSID specified in the keyringFileName cannot be converted to the current default CCSID for integrated file system path names.
• There was an incomplete character or shift state sequence at the end of the keyringFileName path or keyringPassword.

[EACCES]

Permission denied.

This error code indicates one of the following:

• The keyringFileName field contains a file name to which the user is not authorized.
• The keyringPassword value is not valid for the specified keyringFileName.

[EBADF]

Descriptor not valid.

This error code indicates one of the following:

• The keyringFileName value does not specify a valid key ring file name.

[EFAULT]

Bad address.

The system detected an address that was not valid while attempting to access the init parameter or one of the address fields in the init 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. A successful SSL_Init(), QlgSSL_Init (using NLS-enabled path name), or SSL_Init_Application() API must be used to enable a job for SSL processing before attempting to use any other SSL API.
2. If multiple SSL_Init_Application(), QlgSSL_Init (using NLS-enabled path name), or SSL_Init() APIs are performed in a job, then only the values associated with the last SSL_Init_Application(), QlgSSL_Init (using NLS-enabled path name), or SSL_Init() performed are used.
3. If the keyringPassword parameter pointer value is equal to NULL, then QlgSSL_Init will attempt to extract the password value from the key-ring password file associated with the keyringFileName parameter's value. The existence of the associated key-ring password file is based on a configuration selection made during the creation of the key ring file.

Related Information

• SSL_Create()--Enable SSL Support for the Specified Socket Descriptor
  
  
• SSL_Destroy()--End SSL Support for the Specified SSL Session
  
  
• SSL_Handshake()--Initiate the SSL Handshake Protocol
  
  
• SSL_Init()--Initialize the Current Job for SSL
  
  
• SSL_Init_Application()--Initialize the Current Job for SSL Processing Based on the Application Identifier
  
  
• SSL_Read()--Receive Data from an SSL-Enabled SocketDescriptor
  
  
• SSL_Write()--Write Data to an SSL-Enabled Socket Descriptor