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

   1 .TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2003 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_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s \- LDAP bind routines
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .B #include <ldap.h>
  12 .LP
  13 .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred ","
  14 .RS
  15 .BI "int " method ");"
  16 .RE
  17 .LP
  18 .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred ","
  19 .RS
  20 .BI "int " method ");"
  21 .RE
  22 .LP
  23 .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");"
  24 .LP
  25 .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");"
  26 .LP
  27 .BI "int ldap_kerberos_bind_s(LDAP *" ld ", const char *" who ");"
  28 .LP
  29 .BI "int ldap_kerberos_bind1(LDAP *" ld ", const char *" who ");"
  30 .LP
  31 .BI "int ldap_kerberos_bind1_s(LDAP *" ld ", const char *" who ");"
  32 .LP
  33 .BI "int ldap_kerberos_bind2(LDAP *" ld ", const char *" who ");"
  34 .LP
  35 .BI "int ldap_kerberos_bind2_s(LDAP *" ld ", const char *" who ");"
  36 .LP
  37 .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
  38 .RS
  39 .BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
  40 .BI "LDAPControl *" cctrls "[], int *" msgidp ");"
  41 .RE
  42 .LP
  43 .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
  44 .RS
  45 .BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
  46 .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");"
  47 .RE
  48 .LP
  49 .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res ","
  50 .RS
  51 .BI "struct berval **" servercredp ", int " freeit ");"
  52 .RE
  53 .LP
  54 .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn ","
  55 .RS
  56 .BI "const char *" mechs ","
  57 .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[],"
  58 .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact ","
  59 .BI "void *" defaults ");"
  60 .RE
  61 .LP
  62 .BI "int ldap_unbind(LDAP *" ld ");"
  63 .LP
  64 .BI "int ldap_unbind_s(LDAP *" ld ");"
  65 .\" .LP
  66 .\" .ft B
  67 .\" void ldap_set_rebind_proc( ld, rebindproc )
  68 .\" .ft
  69 .\" LDAP *ld;
  70 .\" int (*rebindproc)();
  71 .SH DESCRIPTION
  72 .LP
  73 These routines provide various interfaces to the LDAP bind operation.
  74 After an association with an LDAP server is made using
  75 .BR ldap_init (3),
  76 an LDAP bind operation should be performed before other operations are
  77 attempted over the connection.  An LDAP bind is required when using
  78 Version 2 of the LDAP protocol; it is optional for Version 3 but is
  79 usually needed due to security considerations.
  80 .LP
  81 There are many types of bind calls, providing simple authentication, Kerberos
  82 version 4 authentication, and general routines to do either one, as
  83 well as calls using
  84 .B SASL
  85 (Simple Authentication and Security Layer)
  86 that can negotiate one of many different kinds of authentication.
  87 Both synchronous and asynchronous versions of each variant of the bind
  88 call are provided.  All routines
  89 take \fIld\fP as their first parameter, as returned from
  90 .BR ldap_init (3).
  91 .LP
  92 Kerberos version 4 has been superseded by Kerberos version 5, and the
  93 Kerberos version 4 support is only provided for backward compatibility. The
  94 SASL interfaces should be used for new applications. SASL provides
  95 a general interface for using Kerberos versions 4 and 5 and many other
  96 security systems.
  97 .LP
  98 .SH SIMPLE AUTHENTICATION
  99 The simplest form of the bind call is
 100 .BR ldap_simple_bind_s() .
 101 It takes the DN to bind as in \fIwho\fP, and the userPassword associated
 102 with the entry in \fIpasswd\fP.  It returns an LDAP error indication
 103 (see
 104 .BR ldap_error (3)).
 105 The
 106 .B ldap_simple_bind()
 107 call is asynchronous,
 108 taking the same parameters but only initiating the bind operation and
 109 returning the message id of the request it sent.  The result of the
 110 operation can be obtained by a subsequent call to
 111 .BR ldap_result (3).
 112 .SH KERBEROS AUTHENTICATION
 113 If the LDAP library and LDAP server being contacted have been
 114 compiled with the KERBEROS option defined,
 115 Kerberos version 4 authentication can be performed. As mentioned above,
 116 these Kerberos routines are provided only for backward compatibility.
 117 .LP
 118 These routines assume the user already
 119 has obtained a ticket granting ticket.  The routines take \fIwho\fP, the DN
 120 of the entry to bind as.  The
 121 .B ldap_kerberos_bind_s()
 122 routine does both steps of the Kerberos binding process synchronously.  The
 123 .B ldap_kerberos_bind1_s()
 124 and
 125 .B ldap_kerberos_bind2_s()
 126 routines allow synchronous access to the
 127 individual steps, authenticating to the LDAP server and X.500 DSA, respectively.
 128 The
 129 .B ldap_kerberos_bind1()
 130 and
 131 .B ldap_kerberos_bind2()
 132 routines provide equivalent asynchronous access.
 133 .LP
 134 The
 135 .B ldap_kerberos_bind_s()
 136 routine is used to perform both authentication steps when contacting
 137 an LDAP server that is a gateway to an X.500 DSA.  This kind of server
 138 configuration is only supported in the (very old) University of Michigan LDAP
 139 release.  The OpenLDAP package no longer provides this gateway server.
 140 The standalone LDAP server provided in OpenLDAP may still be configured
 141 with Kerberos version 4 support, but it only requires one authentication
 142 step, and will return an error if the second step is attempted.  Therefore,
 143 only the
 144 .B ldap_kerberos_bind1()
 145 routine or its synchronous equivalent may be used when contacting an
 146 OpenLDAP server.
 147 .SH GENERAL AUTHENTICATION
 148 The
 149 .B ldap_bind()
 150 and
 151 .B ldap_bind_s()
 152 routines can be used when the
 153 authentication method to use needs to be selected at runtime.  They
 154 both take an extra \fImethod\fP parameter selecting the authentication
 155 method to use.  It should be set to one of LDAP_AUTH_SIMPLE,
 156 LDAP_AUTH_KRBV41, or LDAP_AUTH_KRBV42, to select simple authentication,
 157 Kerberos authentication to the LDAP server, or Kerberos authentication
 158 to the X.500 DSA, respectively.
 159 .B ldap_bind()
 160 returns the message id of the request it initiates.
 161 .B ldap_bind_s()
 162 returns an LDAP error indication.
 163 .SH SASL AUTHENTICATION
 164 Description still under construction...
 165 .SH UNBINDING
 166 The
 167 .B ldap_unbind()
 168 call is used to unbind from the directory,
 169 terminate the current association, and free the resources contained
 170 in the \fIld\fP structure.  Once it is called, the connection to
 171 the LDAP server is closed, and the \fIld\fP structure is invalid.
 172 The
 173 .B ldap_unbind_s()
 174 call is just another name for
 175 .BR ldap_unbind() ;
 176 both of these calls are synchronous in nature.
 177 .\" .SH RE-BINDING WHILE FOLLOWING REFERRALS
 178 .\" The
 179 .\" .B ldap_set_rebind_proc()
 180 .\" call is used to set a routine that will be called back to obtain bind
 181 .\" credentials used when a new server is contacted during the following of
 182 .\" an LDAP referral.  Note that this function is only available when the
 183 .\" LDAP libraries are compiled with LDAP_REFERRALS defined and is only
 184 .\" used when the ld_options field in the LDAP structure has
 185 .\" LDAP_OPT_REFERRALS set (this is the default).  If
 186 .\" .B ldap_set_rebind_proc()
 187 .\" is never called, or if it is called with a NULL \fIrebindproc\fP
 188 .\" parameter, an unauthenticated simple LDAP bind will always be done
 189 .\" when chasing referrals.
 190 .\" .LP
 191 .\" \fIrebindproc\fP should be a function that is declared like this:
 192 .\" .LP
 193 .\" .nf
 194 .\" int rebindproc( LDAP *ld, char **whop, char **credp,
 195 .\" int *methodp, int freeit );
 196 .\" .fi
 197 .\" .LP
 198 .\" The LDAP library will first call the rebindproc to obtain the
 199 .\" referral bind credentials, and the \fIfreeit\fP parameter will be
 200 .\" zero.  The \fIwhop\fP, \fIcredp\fP, and \fImethodp\fP should be
 201 .\" set as appropriate.  If the rebindproc returns LDAP_SUCCESS, referral
 202 .\" processing continues, and the rebindproc will be called a second
 203 .\" time with \fIfreeit\fP non-zero to give your application a chance to
 204 .\" free any memory allocated in the previous call.
 205 .\" .LP
 206 .\" If anything but LDAP_SUCCESS is returned by the first call to
 207 .\" the rebindproc, then referral processing is stopped and that error code
 208 .\" is returned for the original LDAP operation.
 209 .SH ERRORS
 210 Asynchronous routines will return -1 in case of error, setting the
 211 \fIld_errno\fP parameter of the \fIld\fP structure.  Synchronous
 212 routines return whatever \fIld_errno\fP is set to.  See
 213 .BR ldap_error (3)
 214 for more information.
 215 .SH SEE ALSO
 216 .BR ldap (3),
 217 .BR ldap_error (3),
 218 .BR ldap_open (3),
 219 .B RFC 2222
 220 (http://www.ietf.org),
 221 .B Cyrus SASL
 222 (http://asg.web.cmu.edu/sasl/)
 223 .SH ACKNOWLEDGEMENTS
 224 .B      OpenLDAP
 225 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 226 .B      OpenLDAP
 227 is derived from University of Michigan LDAP 3.3 Release.