336 lines
12 KiB
HTML
336 lines
12 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>ldap_ssl_init --Initialize an SSL Connection.</title>
|
||
|
|
<!-- Begin Header Records -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- File Edited April 2001 -->
|
||
|
|
<!-- This file has undergone html cleanup on 2/19/02 by JET -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
|
||
|
|
<h2>ldap_ssl_init --Initialize an SSL Connection.</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <ldap.h>
|
||
|
|
#include <ldapssl.h>
|
||
|
|
|
||
|
|
LDAP *ldap_ssl_init(
|
||
|
|
char <em>*host</em>,
|
||
|
|
int <em>port</em>,
|
||
|
|
char <em>*name</em>)
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Library Name/Service Program: QSYS/QGLDCLNT<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>ldap_ssl_init()</strong> 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 <em>
|
||
|
|
ld</em>, all subsequent LDAP messages that flow over the secure connection are
|
||
|
|
encrypted, including the <a href="ldap_simple_bind.htm">ldap_simple_bind()</a>
|
||
|
|
parameters, until <a href="ldap_unbind.htm">ldap_unbind()</a> is called.</p>
|
||
|
|
|
||
|
|
<p>Although still supported, the use of the <a href="ldap_ssl_start.htm">
|
||
|
|
ldap_ssl_start()</a> API is now deprecated. The <a href=
|
||
|
|
"ldap_ssl_client_init.htm">ldap_ssl_client_init()</a> and <strong>
|
||
|
|
ldap_ssl_init()</strong> or <a href="ldap_app_ssl_client_init_np.htm">
|
||
|
|
ldap_app_ssl_client_init_np()</a> and <a href="ldap_app_ssl_init_np.htm">
|
||
|
|
ldap_app_ssl_init_np()</a> APIs should be used instead.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>Read, *R, authority is needed to the selected Certificate Store and Execute,
|
||
|
|
*X, to the associated directories.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>host</em></dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>(Input) Several methods are supported for specifying one or more target LDAP
|
||
|
|
servers, including the following:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td width="10%" valign="top"><em>Explicit Host List</em></td>
|
||
|
|
<td width="90%" valign="top">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:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
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);
|
||
|
|
</pre>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>Localhost</em></td>
|
||
|
|
<td valign="top">If the host parameter is null, the LDAP server will be assumed
|
||
|
|
to be running on the local host.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>Default Hosts</em></td>
|
||
|
|
<td valign="top">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 <a href="ldap_server_locate.htm">ldap_server_locate()</a>
|
||
|
|
function. The port specified on the call is ignored, since ldap_server_locate()
|
||
|
|
returns the port. For example, the following two are equivalent:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
ld=ldap_ssl_init ("ldaps://", ldaps_port, cert_label);
|
||
|
|
ld=ldap_ssl_init (LDAPS_URL_PREFIX, LDAPS_PORT, cert_label);
|
||
|
|
</pre>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"></td>
|
||
|
|
<td valign="top">If more than one default server is located, the list is
|
||
|
|
processed in sequence, until an active server is found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"></td>
|
||
|
|
<td valign="top">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:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
ld=ldap_ssl_init ("ldaps:///cn=fred, dc=austin, dc=ibm, dc=com", LDAPS_PORT, cert_label);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
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.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"></td>
|
||
|
|
<td valign="top">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:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
ld=ldap_ssl_init ("ldaps://myserver", LDAPS_PORT, cert_label);
|
||
|
|
ld=ldap_ssl_init ("myserver", LDAPS_PORT, cert_label);
|
||
|
|
</pre>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>Local Socket</em></td>
|
||
|
|
<td valign="top">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.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>Host with Privileged Port</em></td>
|
||
|
|
<td valign="top">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:
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<pre>
|
||
|
|
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);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>port</em></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The port number to which to connect. If the default IANA-assigned
|
||
|
|
SSL port of 636 is desired, LDAPS_PORT should be specified.</dd>
|
||
|
|
|
||
|
|
<dt><em>name</em></dt>
|
||
|
|
|
||
|
|
<dd>(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.
|
||
|
|
|
||
|
|
<p>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. <em>name</em> can be set to null if a default certificate/private
|
||
|
|
key pair has been designated as the default (using Using Ikmgui). Similarly,
|
||
|
|
<em>name</em> can be set to null if there is a single certificate/private key
|
||
|
|
pair in the designated key database.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
<p>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 <strong>
|
||
|
|
ldap_simple_bind()</strong>:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
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 );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The sequence of calls for the deprecated APIs is <strong>
|
||
|
|
ldap_open/init()</strong>, <strong>ldap_ssl_start()</strong>, followed by
|
||
|
|
<strong>ldap_bind()</strong>.</p>
|
||
|
|
|
||
|
|
<p>See <a href="ldap_get_option.htm">ldap_get</a> or <a href=
|
||
|
|
"ldap_set_option.htm">set_option()</a> for more information on setting the
|
||
|
|
ciphers to be used.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Session Handle</strong></dt>
|
||
|
|
|
||
|
|
<dd>if the request was successful. If successful, the Session Handle returned
|
||
|
|
by <strong>ldap_ssl_init()</strong> is a pointer to an opaque data type
|
||
|
|
representing an LDAP session. The <a href="ldap_get_option.htm">
|
||
|
|
ldap_get_option()</a> and <a href="ldap_set_option.htm">ldap_set_option()</a>
|
||
|
|
APIs are used to access and set a variety of session-wide parameters. See <a
|
||
|
|
href="ldap_get_option.htm">ldap_get_option()</a> and <a href=
|
||
|
|
"ldap_set_option.htm">ldap_set_option()</a> for more information.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>NULL</strong></dt>
|
||
|
|
|
||
|
|
<dd>if the request was not successful.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p><strong>ldap_ssl_init()</strong> will return NULL if not successful.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<p>The following message may be sent from this function.</p>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="3">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">CPF3CF2 E</td>
|
||
|
|
<td width="85%" valign="top">Error(s) occurred during running of ldap_ssl_init
|
||
|
|
API.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="ldap_init.htm">ldap_init()</a> -- Perform an LDAP initialization
|
||
|
|
operation.</li>
|
||
|
|
|
||
|
|
<li><a href="ldap_ssl_client_init.htm">ldap_ssl_client_init()</a> --
|
||
|
|
Initializes the SSL library.</li>
|
||
|
|
|
||
|
|
<li><a href="ldap_app_ssl_init_np.htm">ldap_app_ssl_init_np()</a> --
|
||
|
|
Initializes an SSL Connection.</li>
|
||
|
|
|
||
|
|
<li><a href="ldap_ssl_start.htm">ldap_ssl_start()</a> -- Creates a secure SSL
|
||
|
|
connection (deprecated).</li>
|
||
|
|
<li><img src="delta.gif" alt="Start of change"><a href="ldap_ssl_environment_init.htm">ldap_ssl_environment_init()</a> --Initialize SSL for a secure connection between client and server.<img src="deltaend.gif" alt="End of change"></li>
|
||
|
|
<li><img src="delta.gif" alt="Start of change"><a href="ldap_start_tls_app_np.htm">ldap_start_tls_app_np()</a> --Start a TLS session with an Application ID.<img src="deltaend.gif" alt="End of change"></li>
|
||
|
|
<li><img src="delta.gif" alt="Start of change"><a href="ldap_start_tls_s_np.htm">ldap_start_tls_s_np()</a> --Start a TLS session with a Certificate.<img src="deltaend.gif" alt="End of change"></li>
|
||
|
|
<li><img src="delta.gif" alt="Start of change"><a href="ldap_stop_tls_s_np.htm">ldap_stop_tls_s_np()</a> --End a TLS session.<img src="deltaend.gif" alt="End of change"></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V4R5
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<table align="center" cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"dirserv1.htm">LDAP APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|