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.
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:
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:
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.
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_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() 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
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
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.
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.
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.
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
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
