SSL_Init()--Initialize the Current Job for SSL

 #include <qsossl.h>

 int SSL_Init(SSLInit* init)

The SSL_Init() function is used to establish the SSL security information to be used for all SSL sessions for the current job. The SSL_Init() API establishes 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 situations where the client is connecting to a server which has enabled and requires client authentication.

Parameters

SSLInit * init  (input)

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

struct SSLInitStr { /* SSLInitStr */ char* 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 SSLInit structure as pointed to by init are defined as follows:

char *keyringFileName  (input)

A pointer to a null-terminated character string, identifying the path to the key database file to be used for this job's SSL processing. The path must be a fully qualified integrated file system file name.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name) for a description of supplying the keyringFileName in any CCSID.

char *keyringPassword  (input)

A pointer to a null-terminated character string, identifying the password for the key database file named in the keyringFileName field.

If this parameter's value is equal to NULL, then the SSL_Init() support will attempt to extract the key database password that has been securely stored on the system.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

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() API or SSL_Init_Application() API or the system default cipher specification list if the previous SSL_Init() API or SSL_Init_Application() 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() API or SSL_Init_Application() API
• Use the system default cipher specification list if a previous SSL_Init() API or SSL_Init_Application() 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.

Authorities

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

Return Value

The SSL_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 SSL_Init() 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 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 an 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, or SSL_Init() APIs are performed in a job, then only the values associated with the last SSL_Init_Application(), QlgSSL_Init, or or SSL_Init() performed are used.
   
   
3. If the keyringPassword parameter pointer value is equal to NULL, then SSL_Init() will attempt to extract the password value as stored on the system with the keyringFileName parameter's value. The existence of the securely stored key database password is based on a configuration selection made during the creation of the key database file.

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_Handshake()--Initiate the SSL Handshake Protocol
  
  
• SSL_Init_Application()--Initialize the Current Job for SSL Processing Based on the Application Identifier
  
  
• SSL_Read()--Receive Data from an SSL-Enabled Socket Descriptor
  
  
• SSL_Write()--Write Data to an SSL-Enabled Socket Descriptor