ldap_ssl_client_init()

Purpose

Initialize the SSL client run time

Format

#include <ldap.h> 
#include <ldapssl.h> 

int ldap_ssl_client_init(
    const char *          keyring,
    const char *          keyring_pw,
    int                   ssl_timeout,
    int *                 ssl_rsncode)

Parameters

Input

keyring

Specifies the name of the SSL key database, SAF key ring, or PKCS #11 token as a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by the LDAP_LIBASCII compiler variable. Specify NULL for this parameter to use the GSK_KEYRING_FILE environment variable. An SSL key database must be a z/OS® UNIX System Services file and cannot be a partitioned or sequential data set. For a PKCS #11 token, specify the following format to indicate the token to be used:

*TOKEN*/NAME

where NAME is the name of the PKCS #11 token.

keyring_pw

Specifies the password for the SSL key database as a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by the LDAP_LIBASCII compiler variable. Specify file://filename to use an SSL stash file where filename is the name of the stash file. Specify a zero-length character string to use a SAF key ring or PKCS #11 token instead of a key database. Specify NULL for this parameter to use the GSK_KEYRING_PW or GSK_KEYRING_STASH environment variable. An SSL stash file must be a z/OS UNIX System Services file and cannot be a partitioned or sequential data set. If NULL is specified and the GSK_KEYRING_PW and GSK_KEYRING_STASH environment variables are not defined, a SAF key ring or PKCS #11 token can be used. The PKCS #11 token is used if the keyring parameter is in the following format:

*TOKEN*/NAME

If NULL is specified for the keyring parameter, this parameter is ignored.

ssl_timeout

Specifies the SSL session cache timeout in seconds. The value must be between 1 and 86400. Specify a value of 0 to use the GSK_V3_SESSION_TIMEOUT environment variable. If 0 is specified and the GSK_V3_SESSION_TIMEOUT environment variable is not defined, the default is 86400.

Output

ssl_rsncode: Returns the LDAP reason code as defined in the ldapssl.h include file. Specify NULL for this parameter if the LDAP reason code is not needed.

Usage

Start of change The ldap_ssl_client_init() routine initializes the SSL client run time and must be called before any SSL options are set or an SSL connection is established with an LDAP server. In addition, ldap_ssl_client_init() must be run before starting ldap_init() or ldap_ssl_init() to create a handle for an SSL connection. An error is returned if ldap_ssl_client_init() should be called more than once. LDAP does not support SSL V2 protocol, and disables it from being used. SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 protocols are supported. The z/OS System SSL defaults and environment variables control which of these supported protocols are enabled or disabled. For example, the environment variable GSK_PROTOCOL_SSLV3 can be set to "ON" to enable SSL V3 protocol, or "OFF" to disable SSL V3 protocol. The environment variable GSK_PROTOCOL_TLSV1 can be set to "ON" to enable TLS V1.0 protocol, or "OFF" to disable TLS V1.0 protocol. TLS V1.1 and TLS V1.2 protocols are disabled by default. To enable TLS V1.1 protocol, set the environment variable GSK_PROTOCOL_TLSV1_1 to "ON". Similarly, to enable TLS V1.2 protocol, set the environment variable GSK_PROTOCOL_TLSV1_2 to "ON". End of change

A SAF key ring name is specified as userid/keyring. The current user ID can be used if the user ID is omitted. The user must have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by the current user. The user must have UPDATE access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by another user. Note certificate private keys are not available when using a SAF key ring owned by another user.

A PKCS #11 token is specified in the following format:

*TOKEN*/NAME

where NAME is the name of the PKCS #11 token. The user must have READ access to the SO.NAME and USER.NAME resources in the CRYPTOZ class when using a PKCS #11 token.

For information about System SSL, see ../com.ibm.zos.v2r2.gska100/gsk2aa00.htm.

Function return value

The function return value is LDAP_SUCCESS if no error is detected. Otherwise, it is one of the LDAP error codes listed in the ldap.h include file.

The following are some common errors for this routine:

LDAP_PARAM_ERROR: A parameter is not correct.
LDAP_SSL_ALREADY_INITIALIZED: The SSL client run time is already initialized.
LDAP_SSL_INITIALIZE_FAILED: SSL initialization failed.
LDAP_SSL_NOT_AVAILABLE: System SSL is not available.