2 .\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved.
3 .\" Portions Copyright 2004, Sun Microsystems, Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH LDAP_BIND 3LDAP "Jan 14, 2004"
9 ldap_bind, ldap_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_simple_bind,
10 ldap_simple_bind_s, ldap_unbind, ldap_unbind_s, ldap_unbind_ext,
11 ldap_set_rebind_proc, ldap_sasl_interactive_bind_s \- LDAP bind functions
15 cc [ \fIflag\fR... ] \fIfile\fR... -lldap [ \fIlibrary\fR... ]
19 \fBint\fR \fBldap_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIcred\fR, \fBint\fR \fImethod\fR);
24 \fBint\fR \fBldap_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIcred\fR, \fBint\fR \fImethod\fR);
29 \fBint\fR \fBldap_simple_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIpasswd\fR);
34 \fBint\fR \fBldap_simple_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIpasswd\fR);
39 \fBint\fR \fBldap_unbind\fR(\fBLDAP *\fR\fIld\fR);
44 \fBint\fR \fBldap_unbind_s\fR(\fBLDAP *\fR\fIld\fR);
49 \fBint\fR \fBldap_unbind_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPControl **\fR\fIserverctrls\fR,
50 \fBLDAPControl **\fR\fIclientctrls\fR);
55 \fBvoid\fR \fBldap_set_rebind_proc\fR(\fBLDAP\fR \fI*ld\fR, \fBint (*\fR\fIrebindproc\fR);
60 \fBint\fR \fBldap_sasl_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIdn\fR, \fBchar *\fR\fImechanism\fR,
61 \fBstruct berval **\fR\fIserverctrls\fR, \fBLDAPControl **\fR\fIclientctrls\fR,
62 \fBint *\fR\fImsgidp\fR);
67 \fBint\fR \fBldap_sasl_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIdn\fR, \fBchar *\fR\fImechanism\fR,
68 \fBstruct berval *\fR\fIcred\fR, \fBLDAPControl **\fR\fIserverctrls\fR,
69 \fBLDAPControl **\fR\fIclientctrls\fR);
74 \fBint\fR \fBldap_sasl_interactive_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIdn\fR,
75 \fBchar *\fR\fIsaslMechanism\fR, \fBLDAPControl **\fR\fIsctrl\fR, \fBLDAPControl **\fR\fIcctrl\fR,
76 \fBLDAPControl **\fR\fIunsigned flags\fR, \fBLDAP_SASL_INTERACT_PROC *\fR\fIcallback\fR,
77 \fBvoid *\fR\fIdefaults\fR);
83 These functions provide various interfaces to the LDAP bind operation. After a
84 connection is made to an LDAP server, the \fBldap_bind()\fR function returns
85 the message ID of the request initiated. The \fBldap_bind_s()\fR function
86 returns an LDAP error code.
87 .SS "Simple Authentication"
90 The simplest form of the bind call is \fBldap_simple_bind_s()\fR. The function
91 takes the DN (Distinguished Name) of the \fIdn\fR parameter and the
92 \fBuserPassword\fR associated with the entry in \fIpasswd\fR to return an LDAP
93 error code. See \fBldap_error\fR(3LDAP).
96 The \fBldap_simple_bind()\fR call is asynchronous. The function takes the same
97 parameters as \fBldap_simple_bind_s()\fR but initiates the bind operation and
98 returns the message ID of the request sent. The result of the operation can be
99 obtained by a subsequent call to \fBldap_result\fR(3LDAP).
100 .SS "General Authentication"
103 The \fBldap_bind()\fR and \fBldap_bind_s()\fR functions are used to select the
104 authentication method at runtime. Both functions take an extra \fImethod\fR
105 parameter to set the authentication method. For simple authentication, the
106 \fImethod\fR parameter is set to \fBLDAP_AUTH_SIMPLE\fR. The \fBldap_bind()\fR
107 function returns the message id of the request initiated. The
108 \fBldap_bind_s()\fR function returns an LDAP error code.
109 .SS "SASL Authentication"
112 The \fBldap_sasl_bind()\fR and \fBldap_sasl_bind_s()\fR functions are used for
113 general and extensible authentication over LDAP through the use of the Simple
114 Authentication Security Layer. The routines both take the \fBDN\fR to bind as
115 the authentication method. A dotted-string representation of an OID identifies
116 the method, and the \fBberval\fR structure holds the credentials. The special
117 constant value \fBLDAP_SASL_SIMPLE\fR ("") can be passed to request simple
118 authentication. Otherwise, the \fBldap_simple_bind()\fR function or the
119 \fBldap_simple_bind_s()\fR function can be used.
122 The \fBldap_sasl_interactive_bind_s()\fR helper function takes its data and
123 performs the necessary \fBldap_sasl_bind()\fR and associated SASL library
124 authentication sequencing with the LDAP server that uses the provided
125 connection (\fIld\fR).
128 Upon a successful bind, the \fBldap_sasl_bind()\fR function will, if negotiated
129 by the SASL interface, install the necessary internal \fBlibldap\fR plumbing to
130 enable SASL integrity and privacy (over the wire encryption) with the LDAP
134 The \fBLDAP_SASL_INTERACTIVE\fR option flag is passed to the libldap API
135 through the flags argument of the API. The flag tells the API to use the SASL
136 interactive mode and to have the API request SASL authentication data through
137 the \fBLDAP_SASL_INTERACTIVE_PROC\fR callback as needed. The callback provided
142 typedef int (LDAP_SASL_INTERACT_PROC)
143 (LDAP *ld, unsigned flags, void* defaults, void *interact);
150 The user-provided SASL callback is passed to the current LDAP connection
151 pointer, the current flags field, an optional pointer to user-defined data, and
152 the list of \fBsasl_interact_t\fR authentication values requested by
153 \fBlibsasl\fR(3LIB) to complete authentication.
156 The user-defined callback collects and returns the authentication information
157 in the \fBsasl_interact_t\fR array according to \fBlibsasl\fR rules. The
158 authentication information can include user IDs, passwords, realms, or other
159 information defined by SASL. The SASL library uses this date during sequencing
160 to complete authentication.
164 The \fBldap_unbind()\fR call is used to unbind from a directory, to terminate
165 the current association, and to free the resources contained in the \fIld\fR
166 structure. Once the function is called, the connection to the LDAP server is
167 closed and the \fIld\fR structure is invalid. The \fBldap_unbind_s()\fR and
168 \fBldap_unbind()\fR calls are identical and synchronous in nature.
171 The \fBldap_unbind_ext()\fR function is used to unbind from a directory, to
172 terminate the current association, and to free the resources contained in the
173 LDAP structure. Unlike \fBldap_unbind()\fR and \fBldap_unbind_s()\fR, both
174 server and client controls can be explicitly included with
175 \fBldap_unbind_ext()\fR requests. No server response is made to an unbind
176 request and responses should not be expected from server controls included with
178 .SS "Rebinding While Following Referral"
181 The \fBldap_set_rebind_proc()\fR call is used to set a function called back to
182 obtain bind credentials. The credentials are used when a new server is
183 contacted after an LDAP referral. If \fBldap_set_rebind_proc()\fR is never
184 called, or if it is called with a \fBNULL\fR \fIrebindproc\fR parameter, an
185 unauthenticated simple LDAP bind is always done when chasing referrals.
188 The \fBrebindproc()\fR function is declared as shown below:
192 int rebindproc(LDAP *ld, char **whop, char **credp,
193 int *methodp, int freeit);
199 The LDAP library first calls the \fBrebindproc()\fR to obtain the referral bind
200 credentials. The \fIfreeit\fR parameter is zero. The \fIwhop\fR, \fIcredp\fR,
201 and \fImethodp\fR parameters should be set as appropriate. If
202 \fBrebindproc()\fR returns \fBLDAP_SUCCESS\fR, referral processing continues.
203 The \fBrebindproc()\fR is called a second time with a non-zero \fIfreeit\fR
204 value to give the application a chance to free any memory allocated in the
208 If anything but \fBLDAP_SUCCESS\fR is returned by the first call to
209 \fBrebindproc()\fR, referral processing is stopped and the error code is
210 returned for the original LDAP operation.
214 Make a call to \fBldap_result\fR(3LDAP) to obtain the result of a bind
219 Asynchronous functions will return \fB\(mi1\fR in case of error. See
220 \fBldap_error\fR(3LDAP) for more information on error codes returned. If no
221 credentials are returned, the result parameter is set to \fINULL\fR.
225 See \fBattributes\fR(7) for descriptions of the following attributes:
233 ATTRIBUTE TYPE ATTRIBUTE VALUE
235 Interface Stability Evolving
244 .BR ldap_error (3LDAP),
245 .BR ldap_open (3LDAP),
246 .BR ldap_result (3LDAP),