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

 #include <qsossl.h>

 int QlgSSL_Init(QlgSSLInit* init)

The QlgSSL_Init() function is used to establish the TLS security information to be used for all TLS 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 TLS 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 TLS 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, shown here not in preferred or strength order, are defined in <qsossl.h> as the following:

Notes:

1. The default cipher suite list in preference order when the operating system is installed is as follows:
   

   C Constant                                     System Value
   TLS_AES_128_GCM_SHA256                        *AES_128_GCM_SHA256 
   TLS_AES_256_GCM_SHA384                        *AES_256_GCM_SHA384
   TLS_CHACHA20_POLY1305_SHA256                  *CHACHA20_POLY1305_SHA256
   TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	      *ECDHE_ECDSA_AES_128_GCM_SHA256
   TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	      *ECDHE_ECDSA_AES_256_GCM_SHA384
   TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	      *ECDHE_RSA_AES_128_GCM_SHA256
   TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	      *ECDHE_RSA_AES_256_GCM_SHA384
   TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
   TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   *ECDHE_RSA_CHACHA20_POLY1305_SHA256
   

2. The current default cipher suite list can be different from the install time list due to changes made to the QSSLCSL (TLS cipher specification list) system value via the Change System Value (CHGSYSVAL) command. A cipher suite removed from the TLS 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 TLSCONFIG will also be removed from the default cipher suite list shown here. For additional information see the help text for TLSCONFIG. The order of the cipher suites in QSSLCSL will be used to order the cipher suites in the default list.

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

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 TLS 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]

TLS is not available for use.

[SSL_ERROR_UNSUPPORTED]

Operation is not supported by TLS.

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

[SSL_ERROR_UNKNOWN]

An unknown or unexpected error occurred during TLS 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 TLS processing before attempting to use any other TLS 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.
4. 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.

Related Information

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