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

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