ldap_ssl_client_init --Initializes the SSL Library.

Syntax #include <ldap.h> #include <ldapssl.h> int ldap_ssl_client_init( char *keyring, char *keyring_pw, int ssl_timeout, int *pSSLReasonCode) Threadsafe: Yes

The ldap_ssl_client_init() routine is used to initialize the SSL protocol stack for an application process. It should be invoked once, prior to making any other LDAP calls. Once ldap_ssl_client_init() has been successfully invoked, any subsequent invocations will return a return code of LDAP_SSL_ALREADY_INITIALIZED.

Note that when connecting to an LDAP V2 server, one of the ldap_simple_bind() or ldap_bind() calls must be completed before other operations can be performed on the session (with the exception of ldap_set/get_option()). The LDAP V3 protocol does not require a bind operation before performing other operations.

Although still supported, the use of the ldap_ssl_start() API is now deprecated. The ldap_ssl_client_init() and ldap_ssl_init() APIs should be used instead.

Authorities and Locks

No OS/400 authority is required. All authority checking is done by the LDAP server.

Parameters

keyring

(Input) Specifies the name of a key database file (with "kdb" extension). The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. A key database can also be used to store the client's private key(s) and associated client certificate(s). A private key and associated client certificate are required only if the LDAP server is configured to require client and server authentication. If the LDAP server is configured to provide only server authentication, a private key and client certificate are not required.

Note: Although still supported, use of the ldap_ssl_start() is discouraged (its use has been deprecated). Any application using the ldap_ssl_start() API should only use a single key database (per application process).

A fully-qualified path and filename is recommended. If a filename without a fully-qualified path is specified, the LDAP library will look in the current directory for the file. The key database file specified here must have been created using the ikmgui utility. If a key database is not supplied, the default roots are used for trusted Certification Authorities (CAs).

For more information on using ikmgui to manage the contents of a key database, see Using Ikmgui.

keyring_pw

(Input) Specifies the password that is used to protect the contents of the key database. This password is important since it protects the private key stored in the key database. The password was specified when the key database was initially created. A NULL pointer to the password is accepted.

ssl_timeout

(Input) Specifies the SSL timeout value in seconds. The timeout value controls the frequency with which the SSL protocol stack regenerates session keys. If ssl_timeout is set to 0, the default value SSLV3_CLIENT_TIMEOUT will be used. Otherwise, the value supplied will be used, provided it is less than or equal to 86,400 (number of seconds in a day). If ssl_timeout is greater than 86,400, LDAP_PARAM_ERROR is returned.

pSSLReasonCode

(Input) Specifies a pointer to the SSL Reason Code, which provides additional information in the event that an error occurs during initialization of the SSL stack (when ldap_ssl_client_init() is invoked). See ldapssl.h for reason codes that can be returned.

The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions are "protected" by using a secure SSL connection, including the dn and password that flow on the ldap_simple_bind():

	rc = ldap_ssl_client_init (keyfile, keyfile_pw, timeout, reasoncode);
	ld = ldap_ssl_init(ldaphost, ldapport, label );
	rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers);
	rc = ldap_simple_bind_s(ld, binddn, passwd);

	...additional LDAP API calls

	rc = ldap_unbind( ld );

Note that the sequence of calls for the deprecated APIs is ldap_open/init(), ldap_ssl_start(), followed by ldap_bind().

The following ciphers are attempted for the SSL handshake by default, in the order shown.

    (Export Version)
  
      RC4_MD5_EXPORT
      RC2_MD5_EXPORT
  
    (Non-export Version)
  
      RC4_SHA_US
      RC4_MD5_US
      DES_SHA_US
      3DES_SHA_US
      RC4_MD5_EXPORT
      RC2_MD5_EXPORT
  

See ldap_get/set_option() for more information on setting the ciphers to be used.

The ldap_ssl_client_init() API is only supported for the versions of the LDAP library that include the SSL component. It include RSA(1) software.

(1) RSA is a trademark of RSA Data Security, Inc.

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error

if the request was not successful.

Error Conditions

If ldap_ssl_client_init() is not successful, it returns another LDAP error code. See LDAP Client API Error Conditions for possible values for the error codes.

Error Messages

    The following message may be set from this function.
    CPF3CF2 E  Error(s) occurred during running of ldap_ssl_client_init API.

Related Information

    ldap_ssl_init() -- Initializes an SSL connection.
    ldap_ssl_start() -- Creates a secure SSL connection (deprecated).