git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_bind.3

   1 .TH LDAP_BIND 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_kerberos_bind_s, ldap_kerberos_bind1, ldap_kerberos_bind1_s, ldap_kerberos_bind2, ldap_kerberos_bind2_s, ldap_unbind, ldap_unbind_s \- LDAP bind routines
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <ldap.h>
  11 .LP
  12 .ft B
  13 int ldap_bind(ld, who, cred, method)
  14 .ft
  15 LDAP *ld;
  16 char *who, *cred;
  17 int method;
  18 .LP
  19 .ft B
  20 int ldap_bind_s(ld, who, cred, method)
  21 .ft
  22 LDAP *ld;
  23 char *who, *cred;
  24 int method;
  25 .LP
  26 .ft B
  27 int ldap_simple_bind(ld, who, passwd)
  28 .ft
  29 LDAP *ld;
  30 char *who, *passwd;
  31 .LP
  32 .ft B
  33 int ldap_simple_bind_s(ld, who, passwd)
  34 .ft
  35 LDAP *ld;
  36 char *who, *passwd;
  37 .LP
  38 .ft B
  39 int ldap_kerberos_bind_s(ld, who)
  40 .ft
  41 LDAP *ld;
  42 char *who;
  43 .LP
  44 .ft B
  45 int ldap_kerberos_bind1(ld, who)
  46 .ft
  47 LDAP *ld;
  48 char *who;
  49 .LP
  50 .ft B
  51 int ldap_kerberos_bind1_s(ld, who)
  52 .ft
  53 LDAP *ld;
  54 char *who;
  55 .LP
  56 .ft B
  57 int ldap_kerberos_bind2(ld, who)
  58 .ft
  59 LDAP *ld;
  60 char *who;
  61 .LP
  62 .ft B
  63 int ldap_kerberos_bind2_s(ld, who)
  64 .ft
  65 LDAP *ld;
  66 char *who;
  67 .LP
  68 .ft B
  69 int ldap_unbind(ld)
  70 .ft
  71 LDAP *ld;
  72 .LP
  73 .ft B
  74 int ldap_unbind_s(ld)
  75 .ft
  76 LDAP *ld;
  77 .\" .LP
  78 .\" .ft B
  79 .\" void ldap_set_rebind_proc( ld, rebindproc )
  80 .\" .ft
  81 .\" LDAP *ld;
  82 .\" int (*rebindproc)();
  83 .SH DESCRIPTION
  84 .LP
  85 These routines provide various interfaces to the LDAP bind operation.
  86 After a connection is made to an LDAP server using
  87 .BR ldap_open (3),
  88 an LDAP bind operation must be performed before other operations can
  89 be attempted over the conection.  Both synchronous and asynchronous
  90 versions of each variant of the bind call are provided.  There are
  91 three types of calls, providing simple authentication, kerberos
  92 authentication, and general routines to do either one.  All routines
  93 take \fIld\fP as their first parameter, as returned from
  94 .BR ldap_open (3).
  95 .SH SIMPLE AUTHENTICATION
  96 The simplest form of the bind call is
  97 .BR ldap_simple_bind_s() .
  98 It takes the DN to bind as in \fIwho\fP, and the userPassword associated
  99 with the entry in \fIpasswd\fP.  It returns an LDAP error indication
 100 (see
 101 .BR ldap_error (3)).
 102 The
 103 .B ldap_simple_bind()
 104 call is asynchronous,
 105 taking the same parameters but only initiating the bind operation and
 106 returning the message id of the request it sent.  The result of the
 107 operation can be obtained by a subsequent call to
 108 .BR ldap_result (3).
 109 .SH KERBEROS AUTHENTICATION
 110 If the LDAP library and LDAP server being contacted have been
 111 compiled with the KERBEROS option defined,
 112 Kerberos version 4 authentication can be accomplished by calling
 113 the
 114 .BR ldap_kerberos_bind_s()
 115 routine.  It assumes the user already
 116 has obtained a ticket granting ticket.  It takes \fIwho\fP, the DN
 117 of the entry to bind as.  This routine does both steps of the
 118 kerberos binding process synchronously.  The
 119 .B ldap_kerberos_bind1_s()
 120 and
 121 .B ldap_kerberos_bind2_s()
 122 routines allow synchronous access to the
 123 individual steps, authenticating to the LDAP server and DSA, respectively.
 124 The
 125 .B ldap_kerberos_bind1()
 126 and
 127 .B ldap_kerberos_bind2()
 128 routines provide equivalent asynchronous access.
 129 .SH GENERAL AUTHENTICATION
 130 The
 131 .B ldap_bind()
 132 and
 133 .B ldap_bind_s()
 134 routines can be used when the
 135 authentication method to use needs to be selected at runtime.  They
 136 both take an extra \fImethod\fP parameter selecting the authentication
 137 method to use.  It should be set to one of LDAP_AUTH_SIMPLE,
 138 LDAP_AUTH_KRBV41, or LDAP_AUTH_KRBV42, to select simple authentication,
 139 kerberos authentication to the LDAP server, or kerberos authentication
 140 to the DSA, respectively.
 141 .B ldap_bind()
 142 returns the message id of the request it initiates.
 143 .B ldap_bind_s()
 144 returns an LDAP error indication.
 145 .SH UNBINDING
 146 The
 147 .B ldap_unbind()
 148 call is used to unbind from the directory,
 149 terminate the current association, and free the resources contained
 150 in the \fIld\fP structure.  Once it is called, the connection to
 151 the LDAP server is closed, and the \fIld\fP structure is invalid.
 152 The
 153 .B ldap_unbind_s()
 154 call is just another name for
 155 .BR ldap_unbind() ;
 156 both of these calls are synchronous in nature.
 157 .\" .SH RE-BINDING WHILE FOLLOWING REFERRALS
 158 .\" The
 159 .\" .B ldap_set_rebind_proc()
 160 .\" call is used to set a routine that will be called back to obtain bind
 161 .\" credentials used when a new server is contacted during the following of
 162 .\" an LDAP referral.  Note that this function is only available when the
 163 .\" LDAP libraries are compiled with LDAP_REFERRALS defined and is only
 164 .\" used when the ld_options field in the LDAP structure has
 165 .\" LDAP_OPT_REFERRALS set (this is the default).  If
 166 .\" .B ldap_set_rebind_proc()
 167 .\" is never called, or if it is called with a NULL \fIrebindproc\fP
 168 .\" parameter, an unauthenticated simple LDAP bind will always be done
 169 .\" when chasing referrals.
 170 .\" .LP
 171 .\" \fIrebindproc\fP should be a function that is declared like this:
 172 .\" .LP
 173 .\" .nf
 174 .\" int rebindproc( LDAP *ld, char **whop, char **credp,
 175 .\" int *methodp, int freeit );
 176 .\" .fi
 177 .\" .LP
 178 .\" The LDAP library will first call the rebindproc to obtain the
 179 .\" referral bind credentials, and the \fIfreeit\fP parameter will be
 180 .\" zero.  The \fIwhop\fP, \fIcredp\fP, and \fImethodp\fP should be
 181 .\" set as appropriate.  If the rebindproc returns LDAP_SUCCESS, referral
 182 .\" processing continues, and the rebindproc will be called a second
 183 .\" time with \fIfreeit\fP non-zero to give your application a chance to
 184 .\" free any memory allocated in the previous call.
 185 .\" .LP
 186 .\" If anything but LDAP_SUCCESS is returned by the first call to
 187 .\" the rebindproc, then referral processing is stopped and that error code
 188 .\" is returned for the original LDAP operation.
 189 .SH ERRORS
 190 Asynchronous routines will return -1 in case of error, setting the
 191 \fIld_errno\fP parameter of the \fIld\fP structure.  Synchronous
 192 routines return whatever \fIld_errno\fP is set to.  See
 193 .BR ldap_error (3)
 194 for more information.
 195 .SH SEE ALSO
 196 .BR ldap(3),
 197 .BR ldap_error(3),
 198 .BR ldap_open(3)
 199 .SH ACKNOWLEDGEMENTS
 200 .B      OpenLDAP
 201 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 202 .B      OpenLDAP
 203 is derived from University of Michigan LDAP 3.3 Release.