1ldap_bind(3LDAP)            LDAP Library Functions            ldap_bind(3LDAP)
2
3
4

NAME

6       ldap_bind,  ldap_bind_s,  ldap_sasl_bind,  ldap_sasl_bind_s,  ldap_sim‐
7       ple_bind,     ldap_simple_bind_s,      ldap_unbind,      ldap_unbind_s,
8       ldap_unbind_ext,  ldap_set_rebind_proc,  ldap_sasl_interactive_bind_s -
9       LDAP bind functions
10

SYNOPSIS

12       cc [ flag... ] file... -lldap [ library... ]
13       #include <lber.h>
14       #include <ldap.h>
15
16       int ldap_bind(LDAP *ld, char *who, char *cred, int method);
17
18
19       int ldap_bind_s(LDAP *ld, char *who, char *cred, int method);
20
21
22       int ldap_simple_bind(LDAP *ld, char *who, char *passwd);
23
24
25       int ldap_simple_bind_s(LDAP *ld, char *who, char *passwd);
26
27
28       int ldap_unbind(LDAP *ld);
29
30
31       int ldap_unbind_s(LDAP *ld);
32
33
34       int ldap_unbind_ext(LDAP *ld, LDAPControl **serverctrls,
35            LDAPControl **clientctrls);
36
37
38       void ldap_set_rebind_proc(LDAP *ld, int (*rebindproc);
39
40
41       int ldap_sasl_bind(LDAP *ld, char *dn, char *mechanism,
42            struct berval **serverctrls, LDAPControl **clientctrls,
43            int *msgidp);
44
45
46       int ldap_sasl_bind_s(LDAP *ld, char *dn, char *mechanism,
47            struct berval *cred, LDAPControl **serverctrls,
48            LDAPControl **clientctrls);
49
50
51       int ldap_sasl_interactive_bind_s(LDAP *ld, char *dn,
52            char *saslMechanism, LDAPControl **sctrl, LDAPControl **cctrl,
53            LDAPControl **unsigned flags, LDAP_SASL_INTERACT_PROC *callback,
54            void *defaults);
55
56

DESCRIPTION

58       These functions provide various interfaces to the LDAP bind  operation.
59       After  a connection is made to an LDAP server, the ldap_bind() function
60       returns the message ID of  the  request  initiated.  The  ldap_bind_s()
61       function returns an LDAP error code.
62
63   Simple Authentication
64       The  simplest  form of the bind call is ldap_simple_bind_s(). The func‐
65       tion takes the DN (Distinguished Name) of  the  dn  parameter  and  the
66       userPassword  associated  with  the  entry  in passwd to return an LDAP
67       error code. See ldap_error(3LDAP).
68
69
70       The ldap_simple_bind() call is asynchronous.  The  function  takes  the
71       same  parameters  as ldap_simple_bind_s() but initiates the bind opera‐
72       tion and returns the message ID of the request sent. The result of  the
73       operation can be obtained by a subsequent call to ldap_result(3LDAP).
74
75   General Authentication
76       The  ldap_bind()  and  ldap_bind_s()  functions  are used to select the
77       authentication method at runtime. Both functions take an  extra  method
78       parameter  to set the authentication method. For simple authentication,
79       the method parameter is set to LDAP_AUTH_SIMPLE. The ldap_bind()  func‐
80       tion returns the message id of the request initiated. The ldap_bind_s()
81       function returns an LDAP error code.
82
83   SASL Authentication
84       The ldap_sasl_bind() and ldap_sasl_bind_s() functions are used for gen‐
85       eral  and  extensible  authentication  over LDAP through the use of the
86       Simple Authentication Security Layer. The routines both take the DN  to
87       bind as the authentication method. A dotted-string representation of an
88       OID identifies the method, and the berval structure holds  the  creden‐
89       tials.  The  special constant value LDAP_SASL_SIMPLE ("") can be passed
90       to request simple  authentication.  Otherwise,  the  ldap_simple_bind()
91       function or the ldap_simple_bind_s() function can be used.
92
93
94       The  ldap_sasl_interactive_bind_s()  helper function takes its data and
95       performs the necessary ldap_sasl_bind()  and  associated  SASL  library
96       authentication  sequencing  with the LDAP server that uses the provided
97       connection (ld).
98
99
100       Upon a successful bind, the ldap_sasl_bind() function will, if  negoti‐
101       ated  by  the  SASL  interface,  install the necessary internal libldap
102       plumbing to enable SASL integrity and privacy (over  the  wire  encryp‐
103       tion) with the LDAP server.
104
105
106       The  LDAP_SASL_INTERACTIVE  option  flag  is  passed to the libldap API
107       through the flags argument of the API. The flag tells the  API  to  use
108       the  SASL interactive mode and to have the API request SASL authentica‐
109       tion data through the LDAP_SASL_INTERACTIVE_PROC  callback  as  needed.
110       The callback provided is in the form:
111
112         typedef int (LDAP_SASL_INTERACT_PROC)
113             (LDAP *ld, unsigned flags, void* defaults, void *interact);
114
115
116
117
118       The  user-provided  SASL callback is passed to the current LDAP connec‐
119       tion pointer, the current flags field, an  optional  pointer  to  user-
120       defined  data,  and  the  list of sasl_interact_t authentication values
121       requested by libsasl(3LIB) to complete authentication.
122
123
124       The user-defined  callback  collects  and  returns  the  authentication
125       information  in  the  sasl_interact_t array according to libsasl rules.
126       The authentication information can include user IDs, passwords, realms,
127       or  other  information defined by SASL. The SASL library uses this date
128       during sequencing to complete authentication.
129
130   Unbinding
131       The ldap_unbind() call is used to unbind from a directory, to terminate
132       the  current association, and to free the resources contained in the ld
133       structure. Once the function is called,  the  connection  to  the  LDAP
134       server  is  closed and the ld structure is invalid. The ldap_unbind_s()
135       and ldap_unbind() calls are identical and synchronous in nature.
136
137
138       The ldap_unbind_ext() function is used to unbind from a  directory,  to
139       terminate  the current association, and to free the resources contained
140       in the LDAP structure. Unlike ldap_unbind() and  ldap_unbind_s(),  both
141       server   and   client   controls   can   be  explicitly  included  with
142       ldap_unbind_ext() requests. No server response is  made  to  an  unbind
143       request  and  responses  should  not  be  expected from server controls
144       included with unbind requests.
145
146   Rebinding While Following Referral
147       The ldap_set_rebind_proc() call is used to set a function  called  back
148       to  obtain bind credentials. The credentials are used when a new server
149       is contacted after an LDAP referral. If ldap_set_rebind_proc() is never
150       called,  or  if it is called with a NULL rebindproc parameter, an unau‐
151       thenticated simple LDAP bind is always done when chasing referrals.
152
153
154       The rebindproc() function is declared as shown below:
155
156         int rebindproc(LDAP *ld, char **whop, char **credp,
157             int *methodp, int freeit);
158
159
160
161       The LDAP library first calls the rebindproc() to  obtain  the  referral
162       bind  credentials.  The  freeit parameter is zero. The whop, credp, and
163       methodp parameters  should  be  set  as  appropriate.  If  rebindproc()
164       returns  LDAP_SUCCESS,  referral processing continues. The rebindproc()
165       is called a second time with a non-zero freeit value to give the appli‐
166       cation a chance to free any memory allocated in the previous call.
167
168
169       If  anything  but LDAP_SUCCESS is returned by the first call to rebind‐
170       proc(), referral processing is stopped and the error code  is  returned
171       for the original LDAP operation.
172

RETURN VALUES

174       Make a call to ldap_result(3LDAP) to obtain the result of a bind opera‐
175       tion.
176

ERRORS

178       Asynchronous  functions  will  return  −1  in  case   of   error.   See
179       ldap_error(3LDAP)  for  more information on error codes returned. If no
180       credentials are returned, the result parameter is set to NULL.
181

ATTRIBUTES

183       See attributes(5) for descriptions of the following attributes:
184
185
186
187
188       ┌─────────────────────────────┬─────────────────────────────┐
189       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
190       ├─────────────────────────────┼─────────────────────────────┤
191       │Interface Stability          │Evolving                     │
192       ├─────────────────────────────┼─────────────────────────────┤
193       │MT-Level                     │Safe                         │
194       └─────────────────────────────┴─────────────────────────────┘
195

SEE ALSO

197       ldap(3LDAP), ldap_error(3LDAP),  ldap_open(3LDAP),  ldap_result(3LDAP),
198       libsasl(3LIB), attributes(5)
199
200
201
202SunOS 5.11                        14 Jan 2004                 ldap_bind(3LDAP)
Impressum