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-2006 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_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_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
  28 .RS
  29 .BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
  30 .BI "LDAPControl *" cctrls "[], int *" msgidp ");"
  31 .RE
  32 .LP
  33 .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
  34 .RS
  35 .BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
  36 .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");"
  37 .RE
  38 .LP
  39 .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res ","
  40 .RS
  41 .BI "struct berval **" servercredp ", int " freeit ");"
  42 .RE
  43 .LP
  44 .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn ","
  45 .RS
  46 .BI "const char *" mechs ","
  47 .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[],"
  48 .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact ","
  49 .BI "void *" defaults ");"
  50 .RE
  51 .LP
  52 .BI "int ldap_unbind(LDAP *" ld ");"
  53 .LP
  54 .BI "int ldap_unbind_s(LDAP *" ld ");"
  55 .\" .LP
  56 .\" .ft B
  57 .\" void ldap_set_rebind_proc( ld, rebindproc )
  58 .\" .ft
  59 .\" LDAP *ld;
  60 .\" int (*rebindproc)();
  61 .SH DESCRIPTION
  62 .LP
  63 These routines provide various interfaces to the LDAP bind operation.
  64 After an association with an LDAP server is made using
  65 .BR ldap_init (3),
  66 an LDAP bind operation should be performed before other operations are
  67 attempted over the connection.  An LDAP bind is required when using
  68 Version 2 of the LDAP protocol; it is optional for Version 3 but is
  69 usually needed due to security considerations.
  70 .LP
  71 There are three types of bind calls, ones providing simple authentication,
  72 ones providing SASL authentication, and general routines capable of doing
  73 either simple or SASL authentication.
  74 .LP
  75 .B SASL
  76 (Simple Authentication and Security Layer)
  77 that can negotiate one of many different kinds of authentication.
  78 Both synchronous and asynchronous versions of each variant of the bind
  79 call are provided.  All routines
  80 take \fIld\fP as their first parameter, as returned from
  81 .BR ldap_init (3).
  82 .LP
  83 .SH SIMPLE AUTHENTICATION
  84 The simplest form of the bind call is
  85 .BR ldap_simple_bind_s() .
  86 It takes the DN to bind as in \fIwho\fP, and the userPassword associated
  87 with the entry in \fIpasswd\fP.  It returns an LDAP error indication
  88 (see
  89 .BR ldap_error (3)).
  90 The
  91 .B ldap_simple_bind()
  92 call is asynchronous,
  93 taking the same parameters but only initiating the bind operation and
  94 returning the message id of the request it sent.  The result of the
  95 operation can be obtained by a subsequent call to
  96 .BR ldap_result (3).
  97 .SH GENERAL AUTHENTICATION
  98 The
  99 .B ldap_bind()
 100 and
 101 .B ldap_bind_s()
 102 routines can be used when the
 103 authentication method to use needs to be selected at runtime.  They
 104 both take an extra \fImethod\fP parameter selecting the authentication
 105 method to use.  It should be set to LDAP_AUTH_SIMPLE
 106 to select simple authentication.
 107 .B ldap_bind()
 108 returns the message id of the request it initiates.
 109 .B ldap_bind_s()
 110 returns an LDAP error indication.
 111 .SH SASL AUTHENTICATION
 112 Description still under construction...
 113 .SH UNBINDING
 114 The
 115 .B ldap_unbind()
 116 call is used to unbind from the directory,
 117 terminate the current association, and free the resources contained
 118 in the \fIld\fP structure.  Once it is called, the connection to
 119 the LDAP server is closed, and the \fIld\fP structure is invalid.
 120 The
 121 .B ldap_unbind_s()
 122 call is just another name for
 123 .BR ldap_unbind() ;
 124 both of these calls are synchronous in nature.
 125 .\" .SH RE-BINDING WHILE FOLLOWING REFERRALS
 126 .\" The
 127 .\" .B ldap_set_rebind_proc()
 128 .\" call is used to set a routine that will be called back to obtain bind
 129 .\" credentials used when a new server is contacted during the following of
 130 .\" an LDAP referral.  Note that this function is only available when the
 131 .\" LDAP libraries are compiled with LDAP_REFERRALS defined and is only
 132 .\" used when the ld_options field in the LDAP structure has
 133 .\" LDAP_OPT_REFERRALS set (this is the default).  If
 134 .\" .B ldap_set_rebind_proc()
 135 .\" is never called, or if it is called with a NULL \fIrebindproc\fP
 136 .\" parameter, an unauthenticated simple LDAP bind will always be done
 137 .\" when chasing referrals.
 138 .\" .LP
 139 .\" \fIrebindproc\fP should be a function that is declared like this:
 140 .\" .LP
 141 .\" .nf
 142 .\" int rebindproc( LDAP *ld, char **whop, char **credp,
 143 .\" int *methodp, int freeit );
 144 .\" .fi
 145 .\" .LP
 146 .\" The LDAP library will first call the rebindproc to obtain the
 147 .\" referral bind credentials, and the \fIfreeit\fP parameter will be
 148 .\" zero.  The \fIwhop\fP, \fIcredp\fP, and \fImethodp\fP should be
 149 .\" set as appropriate.  If the rebindproc returns LDAP_SUCCESS, referral
 150 .\" processing continues, and the rebindproc will be called a second
 151 .\" time with \fIfreeit\fP non-zero to give your application a chance to
 152 .\" free any memory allocated in the previous call.
 153 .\" .LP
 154 .\" If anything but LDAP_SUCCESS is returned by the first call to
 155 .\" the rebindproc, then referral processing is stopped and that error code
 156 .\" is returned for the original LDAP operation.
 157 .SH ERRORS
 158 Asynchronous routines will return -1 in case of error, setting the
 159 \fIld_errno\fP parameter of the \fIld\fP structure.  Synchronous
 160 routines return whatever \fIld_errno\fP is set to.  See
 161 .BR ldap_error (3)
 162 for more information.
 163 .SH SEE ALSO
 164 .BR ldap (3),
 165 .BR ldap_error (3),
 166 .BR ldap_open (3),
 167 .B RFC 2222
 168 (http://www.ietf.org),
 169 .B Cyrus SASL
 170 (http://asg.web.cmu.edu/sasl/)
 171 .SH ACKNOWLEDGEMENTS
 172 .B OpenLDAP
 173 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 174 .B OpenLDAP
 175 is derived from University of Michigan LDAP 3.3 Release.