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