ldap_ssl_init --Initializes an SSL Connection.

Syntax #include <ldap.h> #include <ldapssl.h> LDAP *ldap_ssl_init( char *host, int port, char *name) Threadsafe: Yes

The ldap_ssl_init() routine is used to initialize a secure SSL session with a server. Note that the server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization. Once the secure connection is established for the ld, all subsequent LDAP messages that flow over the secure connection are encrypted, including the ldap_simple_bind() parameters, until ldap_unbind() is invoked.

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

host

(Input) Specifies the name of the host on which the LDAP server is running. The host parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If present, the :port overrides the ldap_ssl_init() port parameter. If the host parameter is null, the LDAP server will be assumed to be running on the local host.

port

(Input) Specifies the port number to which to connect. If the default IANA-assigned SSL port of 636 is desired, LDAPS_PORT should be specified.

name

(Input) Specifies the name, or label, associated with the client private key/certificate pair in the key database. It is used to uniquely identify a private key/certificate pair, as stored in the key database, and may be something like: "Digital ID for Fred Smith".

If the LDAP server is configured to perform Server Authentication, a client certificate is not required (and name can be set to null). If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. name can be set to null if a default certificate/private key pair has been designated as the default (using Using Ikmgui). Similarly, name can be set to null if there is a single certificate/private key pair in the designated key database.

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.

Return Value

Session Handle

if the request was successful. If successful, the Session Handle returned by ldap_ssl_init is a pointer to an opaque data type representing an LDAP session. The ldap_get_option() and ldap_set_option() APIs are used to access and set a variety of session-wide parameters. See ldap_get_option() and ldap_set_option() for more information.

NULL

if the request was not successful.

Error Conditions

ldap_ssl_init() will return NULL and set the ld_errno error code, if not successful. See LDAP Client API Error Conditions for possible LDAP error codes values.

Error Messages

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

Related Information

    ldap_ssl_client_init() -- Initializes the SSL library.
    ldap_ssl_start() -- Creates a secure SSL connection (deprecated).

The ldap_ssl_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.