QlgSSL_Init()--Initialize the Current Job for SSL
(using NLS-enabled path name)
Syntax
#include <qsossl.h>
int QlgSSL_Init(QlgSSLInit* init)
Service Program Name: *SRVPGM
Default Public Authority: *USE
Threadsafe: Yes
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, 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 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_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 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
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
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 (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.
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.
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 SSL Support for the Specified
Socket Descriptor
SSL_Destroy()--End SSL Support for the Specified
SSL Session