ldap_ssl_init--Initialize an SSL Connection

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

The ldap_ssl_init() routine is used to initialize a secure SSL session with a server. 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 called.

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

Authorities and Locks

Read, *R, authority is needed to the selected Certificate Store and Execute, *X, to the associated directories.

Parameters

host

(Input) Several methods are supported for specifying one or more target LDAP servers, including the following:

Explicit Host List	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 port parameter. The following are typical examples: ld=ldap_ssl_init ("server1", ldaps_port, cert_label); ld=ldap_ssl_init ("server2:1200", ldaps_port, cert_label); ld=ldap_ssl_init ("server1:800 server2:2000 server3", ldaps_port, cert_label);
Localhost	If the host parameter is null, the LDAP server will be assumed to be running on the local host.
Default Hosts	If the host parameter is set to "ldaps://" the LDAP library will attempt to locate one or more default LDAP servers, with SSL ports, using the SecureWay® ldap_server_locate() function. The port specified on the call is ignored, since ldap_server_locate() returns the port. For example, the following two are equivalent: ld=ldap_ssl_init ("ldaps://", ldaps_port, cert_label); ld=ldap_ssl_init (LDAPS_URL_PREFIX, LDAPS_PORT, cert_label);
	If more than one default server is located, the list is processed in sequence, until an active server is found.
	The LDAP URL can include a Distinguished Name, used as a filter for selecting candidate LDAP servers based on the server's suffix (or suffixes). If the most significant portion of the DN is an exact match with a server's suffix (after normalizing for case), the server is added to the list of candidate servers. For example, the following will only return default LDAP servers that have a suffix that supports the specified DN: ld=ldap_ssl_init ("ldaps:///cn=fred, dc=austin, dc=ibm, dc=com", LDAPS_PORT, cert_label); In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" would match. If more than one default server is located, the list is processed in sequence, until an active server is found.
	If the LDAP URL contains a host name and optional port, the host is used to create the connection. No attempt is made to locate the default server(s), and the DN, if present, is ignored. For example, the following two are equivalent: ld=ldap_ssl_init ("ldaps://myserver", LDAPS_PORT, cert_label); ld=ldap_ssl_init ("myserver", LDAPS_PORT, cert_label);
Local Socket	If the host parameter is prefixed with "/", the host parameter is assumed to be the name of a UNIX® socket (that is, socket family is AF_UNIX) and port is ignored. This will fail for ldap_ssl_init() because UNIX sockets do not support SSL, nor is it necessary since data will not be flowing over the network.
Host with Privileged Port	If a specified host is prefixed with "privport://", then the LDAP library will use the rresvport() function to attempt to obtain one of the reserved ports (512 through 1023), instead of an "ephemeral" port. The search for a reserved port starts at 1023 and stops at 512. If a reserved port cannot be obtained, the function call will fail. For example:

ld=ldap_ssl_init ("privport://server1, ldaps_port, cert_label");
ld=ldap_ssl_init ("privport://server2:1200", ldaps_port, cert_label);
ld=ldap_ssl_init ("privport://server1:800 server2:2000 privport://server3",ldaps_port,cert_label);

port

(Input) 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) 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.

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

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 );

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

See ldap_get or set_option() for more information about 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 if not successful.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_init() -- Perform an LDAP initialization operation.
• ldap_ssl_client_init() -- Initializes the SSL library.
• ldap_app_ssl_init_np() -- Initializes an SSL Connection.
• ldap_ssl_start() -- Creates a secure SSL connection (deprecated).
• ldap_ssl_environment_init() --Initialize SSL for a secure connection between client and server.
• ldap_start_tls_app_np() --Start a TLS session with an Application ID.
• ldap_start_tls_s_np() --Start a TLS session with a Certificate.
• ldap_stop_tls_s_np() --End a TLS session.

[ Back to top | LDAP APIs | APIs by category ]