ldap_app_ssl_init_np--Initialize an SSL Connection

Syntax

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

  Library Name/Service Program: QSYS/QGLDCLNT

  Default Public Authority: *USE

  Threadsafe: Yes

The ldap_app_ssl_init_np() 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, all subsequent LDAP messages that flow over the secure connection are encrypted, including the ldap_simple_bind() parameters, until ldap_unbind() is called.

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.

The ciphers for the encryption of the connection are based on the current Crypto Access Provider licensed program loaded. See ldap_get or set_option() for more information on setting the ciphers to be used.

Authorities and Locks

*R authority is needed to the selected Certificate Store and *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_app_ssl_init_np ("server1", ldaps_port); ld=ldap_app_ssl_init_np ("server2:1200", ldaps_port); ld=ldap_app_ssl_init_np ("server1:800 server2:2000 server3", ldaps_port);
Localhost	If the host parameter is null, it is assumed that the LDAP server is 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_app_ssl_init_np ("ldaps://", ldaps_port); ld=ldap_app_ssl_init_np (LDAPS_URL_PREFIX, LDAPS_PORT); 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_app_ssl_init_np ("ldaps:///cn=fred, dc=austin, dc=ibm, dc=com", LDAPS_PORT) 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_app_ssl_init_np ("ldaps://myserver", LDAPS_PORT); ld=ldap_app_ssl_init_np ("myserver", LDAPS_PORT);
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_app_ssl_init_np() 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, ldap_app_ssl_init_np() will fail. For example: ld=ldap_app_ssl_init_np ("privport://server1, ldaps_port"); ld=ldap_app_ssl_init_np ("privport://server2:1200", ldaps_port); ld=ldap_app_ssl_init_np ("privport://server1:800 server2:2000 privport://server3", ldaps_port);

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. The value specified for this parameter is ignored in some situations; see the description for the host parameter.

Return Value

Session Handle: if the request was successful. The Session Handle returned by ldap_app_ssl_init_np() 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 these APIs for more information.
NULL: if the request was not successful.

Error Conditions

ldap_app_ssl_init_np() will return NULL if not successful.

Error Messages

The following message may be sent from this function.

Message ID	Error Message Text
CPF3CF2 E	Error(s) occurred during running of ldap_app_ssl_init_np API.

Related Information

ldap_app_ssl_client_init_np() -- Initialize the Client for a Secure LDAP Connection using DCM.
ldap_ssl_client_init() -- Initializes the SSL library.
ldap_ssl_environment_init() -- Initializes SSL for a secure connection between client and server.
ldap_start_tls_s_np() -- Starts a TLS session with a Certificate.
ldap_start_tls_app_np() -- Starts a TLS session with an Application ID.
ldap_stop_tls_s_np() -- Ends a TLS session.
ldap_app_ssl_start_np() -- Creates a secure SSL connection (deprecated).
ldap_ssl_start() -- Creates a secure SSL connection (deprecated).

Example

The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions are protected by using a secure SSL connection.

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

 rc = ldap_app_ssl_client_init_np (dcm_identifier, &reasoncode);
 ld = ldap_app_ssl_init_np(ldaphost, ldapport );
 rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers);
        rc = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, NULL, NULL );

 ...additional LDAP API calls

 rc = ldap_unbind( ld );

API introduced: V5R1

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