usr/src/man/man3ldap/ldap_bind.3ldap

   1 '\" te
   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"
   8 .SH NAME
   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
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR... ] \fIfile\fR... -lldap [ \fIlibrary\fR... ]
  16 #include <lber.h>
  17 #include <ldap.h>
  18
  19 \fBint\fR \fBldap_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIcred\fR, \fBint\fR \fImethod\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBldap_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIcred\fR, \fBint\fR \fImethod\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBldap_simple_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIpasswd\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBldap_simple_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIpasswd\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBldap_unbind\fR(\fBLDAP *\fR\fIld\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBint\fR \fBldap_unbind_s\fR(\fBLDAP *\fR\fIld\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBint\fR \fBldap_unbind_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPControl **\fR\fIserverctrls\fR,
  50      \fBLDAPControl **\fR\fIclientctrls\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBvoid\fR \fBldap_set_rebind_proc\fR(\fBLDAP\fR \fI*ld\fR, \fBint (*\fR\fIrebindproc\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  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);
  63 .fi
  64
  65 .LP
  66 .nf
  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);
  70 .fi
  71
  72 .LP
  73 .nf
  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);
  78 .fi
  79
  80 .SH DESCRIPTION
  81 .sp
  82 .LP
  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"
  88 .sp
  89 .LP
  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).
  94 .sp
  95 .LP
  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"
 101 .sp
 102 .LP
 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"
 110 .sp
 111 .LP
 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.
 120 .sp
 121 .LP
 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).
 126 .sp
 127 .LP
 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
 131 server.
 132 .sp
 133 .LP
 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
 138 is in the form:
 139 .sp
 140 .in +2
 141 .nf
 142 typedef int (LDAP_SASL_INTERACT_PROC)
 143     (LDAP *ld, unsigned flags, void* defaults, void *interact);
 144 .fi
 145 .in -2
 146 .sp
 147
 148 .sp
 149 .LP
 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.
 154 .sp
 155 .LP
 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.
 161 .SS "Unbinding"
 162 .sp
 163 .LP
 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.
 169 .sp
 170 .LP
 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
 177 unbind requests.
 178 .SS "Rebinding While Following Referral"
 179 .sp
 180 .LP
 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.
 186 .sp
 187 .LP
 188 The \fBrebindproc()\fR function is declared as shown below:
 189 .sp
 190 .in +2
 191 .nf
 192 int rebindproc(LDAP *ld, char **whop, char **credp,
 193     int *methodp, int freeit);
 194 .fi
 195 .in -2
 196
 197 .sp
 198 .LP
 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
 205 previous call.
 206 .sp
 207 .LP
 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.
 211 .SH RETURN VALUES
 212 .sp
 213 .LP
 214 Make a call to \fBldap_result\fR(3LDAP) to obtain the result of a bind
 215 operation.
 216 .SH ERRORS
 217 .sp
 218 .LP
 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.
 222 .SH ATTRIBUTES
 223 .sp
 224 .LP
 225 See \fBattributes\fR(7) for descriptions of the following attributes:
 226 .sp
 227
 228 .sp
 229 .TS
 230 box;
 231 c | c
 232 l | l .
 233 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 234 _
 235 Interface Stability     Evolving
 236 _
 237 MT-Level        Safe
 238 .TE
 239
 240 .SH SEE ALSO
 241 .sp
 242 .LP
 243 .BR ldap (3LDAP),
 244 .BR ldap_error (3LDAP),
 245 .BR ldap_open (3LDAP),
 246 .BR ldap_result (3LDAP),
 247 .BR libsasl (3LIB),
 248 .BR attributes (7)