SSL_Init()--Initialize the Current Job for TLS
Syntax
#include <qsossl.h> int SSL_Init(SSLInit* init)
Service Program Name: QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The SSL_Init() function is used to establish the TLS security information to be used for all TLS sessions for the current job. The SSL_Init() API establishes the certificate and the associated public and private key information for use by the TLS 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 TLS 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 TLS (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 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
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_AES_128_GCM_SHA256 0x009C *RSA_AES_128_GCM_SHA256 (TLS Version 1.2 only) TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D *RSA_AES_256_GCM_SHA384 (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006 *ECDHE_ECDSA_NULL_SHA (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007 *ECDHE_ECDSA_RC4_128_SHA (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008 *ECDHE_ECDSA_3DES_EDE_CBC_SHA (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010 *ECDHE_RSA_NULL_SHA (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011 *ECDHE_RSA_RC4_128_SHA (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012 *ECDHE_RSA_3DES_EDE_CBC_SHA (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023 *ECDHE_ECDSA_AES_128_CBC_SHA256 (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024 *ECDHE_ECDSA_AES_256_CBC_SHA384 (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027 *ECDHE_RSA_AES_128_CBC_SHA256 (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028 *ECDHE_RSA_AES_256_CBC_SHA384 (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B *ECDHE_ECDSA_AES_128_GCM_SHA256 (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C *ECDHE_ECDSA_AES_256_GCM_SHA384 (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F *ECDHE_RSA_AES_128_GCM_SHA256 (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030 *ECDHE_RSA_AES_256_GCM_SHA384 (TLS Version 1.2 only) TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9 *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256 (TLS Version 1.2 only) TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8 *ECDHE_RSA_CHACHA20_POLY1305_SHA256 (TLS Version 1.2 only) TLS_AES_128_GCM_SHA256 0x1301 *AES_128_GCM_SHA256 (TLS Version 1.3 only) TLS_AES_256_GCM_SHA384 0x1302 *AES_256_GCM_SHA384 (TLS Version 1.3 only) TLS_CHACHA20_POLY1305_SHA256 0x1303 *CHACHA20_POLY1305_SHA256 (TLS Version 1.3 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_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 TLS_RSA_WITH_AES_128_GCM_SHA256 *RSA_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 *RSA_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 *ECDHE_ECDSA_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 *ECDHE_ECDSA_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 *ECDHE_RSA_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 *ECDHE_RSA_AES_256_CBC_SHA384 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 (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 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 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 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 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 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 TLS
processing before attempting to use any other TLS 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 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 TLS (using
NLS-enabled path name)
- 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_Application()--Initialize the Current Job for TLS
Processing Based on the Application Identifier
- SSL_Read()--Receive Data from a TLS-Enabled Socket
Descriptor
- SSL_Write()--Write Data to a TLS-Enabled Socket
Descriptor
API introduced: V4R3
Top | UNIX-Type APIs | APIs by category |