-.TH LDAP_BIND 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
.SH NAME
-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
+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_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines
+.SH LIBRARY
+OpenLDAP LDAP (libldap, -lldap)
.SH SYNOPSIS
.nf
-.ft B
-#include <lber.h>
-#include <ldap.h>
-.LP
-.ft B
-int ldap_bind(ld, who, cred, method)
-.ft
-LDAP *ld;
-char *who, *cred;
-int method;
-.LP
-.ft B
-int ldap_bind_s(ld, who, cred, method)
-.ft
-LDAP *ld;
-char *who, *cred;
-int method;
-.LP
-.ft B
-int ldap_simple_bind(ld, who, passwd)
-.ft
-LDAP *ld;
-char *who, *passwd;
-.LP
-.ft B
-int ldap_simple_bind_s(ld, who, passwd)
-.ft
-LDAP *ld;
-char *who, *passwd;
-.LP
-.ft B
-int ldap_kerberos_bind_s(ld, who)
-.ft
-LDAP *ld;
-char *who;
-.LP
-.ft B
-int ldap_kerberos_bind1(ld, who)
-.ft
-LDAP *ld;
-char *who;
-.LP
-.ft B
-int ldap_kerberos_bind1_s(ld, who)
-.ft
-LDAP *ld;
-char *who;
-.LP
-.ft B
-int ldap_kerberos_bind2(ld, who)
-.ft
-LDAP *ld;
-char *who;
-.LP
-.ft B
-int ldap_kerberos_bind2_s(ld, who)
-.ft
-LDAP *ld;
-char *who;
-.LP
-.ft B
-int ldap_unbind(ld)
-.ft
-LDAP *ld;
-.LP
-.ft B
-int ldap_unbind_s(ld)
-.ft
-LDAP *ld;
-.LP
-.ft B
-void ldap_set_rebind_proc( ld, rebindproc )
-.ft
-LDAP *ld;
-int (*rebindproc)();
+.B #include <ldap.h>
+.LP
+.BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred ","
+.RS
+.BI "int " method ");"
+.RE
+.LP
+.BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred ","
+.RS
+.BI "int " method ");"
+.RE
+.LP
+.BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");"
+.LP
+.BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");"
+.LP
+.BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
+.RS
+.BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
+.BI "LDAPControl *" cctrls "[], int *" msgidp ");"
+.RE
+.LP
+.BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
+.RS
+.BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
+.BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");"
+.RE
+.LP
+.BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res ","
+.RS
+.BI "struct berval **" servercredp ", int " freeit ");"
+.RE
+.LP
+.BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn ","
+.RS
+.BI "const char *" mechs ","
+.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[],"
+.BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact ","
+.BI "void *" defaults ");"
+.RE
+.LP
+.BI "int ldap_unbind(LDAP *" ld ");"
+.LP
+.BI "int ldap_unbind_s(LDAP *" ld ");"
+.\" .LP
+.\" .ft B
+.\" void ldap_set_rebind_proc( ld, rebindproc )
+.\" .ft
+.\" LDAP *ld;
+.\" int (*rebindproc)();
+.LP
+.BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[],"
+.RS
+.BI LDAPControl *" cctrls "[]);"
+.RE
+.LP
+.BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[],"
+.RS
+.BI LDAPControl *" cctrls "[]);"
+.RE
+.LP
+.BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params);"
.SH DESCRIPTION
.LP
These routines provide various interfaces to the LDAP bind operation.
-After a connection is made to an LDAP server using
-.BR ldap_open (3),
-an LDAP bind operation must be performed before other operations can
-be attempted over the conection. Both synchronous and asynchronous
-versions of each variant of the bind call are provided. There are
-three types of calls, providing simple authentication, kerberos
-authentication, and general routines to do either one. All routines
+After an association with an LDAP server is made using
+.BR ldap_init (3),
+an LDAP bind operation should be performed before other operations are
+attempted over the connection. An LDAP bind is required when using
+Version 2 of the LDAP protocol; it is optional for Version 3 but is
+usually needed due to security considerations.
+.LP
+There are three types of bind calls, ones providing simple authentication,
+ones providing SASL authentication, and general routines capable of doing
+either simple or SASL authentication.
+.LP
+.B SASL
+(Simple Authentication and Security Layer)
+that can negotiate one of many different kinds of authentication.
+Both synchronous and asynchronous versions of each variant of the bind
+call are provided. All routines
take \fIld\fP as their first parameter, as returned from
-.BR ldap_open (3).
+.BR ldap_init (3).
.SH SIMPLE AUTHENTICATION
The simplest form of the bind call is
.BR ldap_simple_bind_s() .
returning the message id of the request it sent. The result of the
operation can be obtained by a subsequent call to
.BR ldap_result (3).
-.SH KERBEROS AUTHENTICATION
-If the LDAP library and LDAP server being contacted have been
-compiled with the KERBEROS option defined,
-Kerberos version 4 authentication can be accomplished by calling
-the
-.BR ldap_kerberos_bind_s()
-routine. It assumes the user already
-has obtained a ticket granting ticket. It takes \fIwho\fP, the DN
-of the entry to bind as. This routine does both steps of the
-kerberos binding process synchronously. The
-.B ldap_kerberos_bind1_s()
-and
-.B ldap_kerberos_bind2_s()
-routines allow synchronous access to the
-individual steps, authenticating to the LDAP server and DSA, respectively.
-The
-.B ldap_kerberos_bind1()
-and
-.B ldap_kerberos_bind2()
-routines provide equivalent asynchronous access.
.SH GENERAL AUTHENTICATION
The
.B ldap_bind()
routines can be used when the
authentication method to use needs to be selected at runtime. They
both take an extra \fImethod\fP parameter selecting the authentication
-method to use. It should be set to one of LDAP_AUTH_SIMPLE,
-LDAP_AUTH_KRBV41, or LDAP_AUTH_KRBV42, to select simple authentication,
-kerberos authentication to the LDAP server, or kerberos authentication
-to the DSA, respectively.
+method to use. It should be set to LDAP_AUTH_SIMPLE
+to select simple authentication.
.B ldap_bind()
returns the message id of the request it initiates.
.B ldap_bind_s()
returns an LDAP error indication.
+.SH SASL AUTHENTICATION
+Description still under construction...
+.SH REBINDING
+.LP
+The
+.B ldap_set_rebind_proc
+function() sets the process to use for binding when an operation returns a
+referral. This function is used when an application needs to bind to another server
+in order to follow a referral or search continuation reference.
+.LP
+The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP,
+the arbitrary data like state information which the client might need to properly rebind.
+The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries
+to use the rebind function. Use the
+.BR ldap_set_option
+function to set the value.
+.LP
+The rebind function has the following syntax.
+.B int rebind_function (LDAP *ld, const char *url,int request,ber_int_t msgid);
+.LP
+The \fIld\fP parameter must be used by the application when binding to the
+referred server if the application wants the libraries to follow the referral.
+.LP
+The \fIurl\fP parameter points to the URL referral string received from the LDAP server.
+The LDAP application can use the
+.BR ldap_url_parse()
+.LP
+The \fIrequest\fP parameter specifies the request operation that generated the referral.
+function to parse the string into its components.
+.LP
+The \fImsgid\fP parameter specifies the message ID of the request generating the referral.
+.LP
+The LDAP libraries set all the parameters when they call the rebind function. The application
+should not attempt to free either the ld or the url structures in the rebind function.
+.LP
+The application must supply to the rebind function the required authentication information such as,
+user name, password, and certificates. The rebind function must use a synchronous bind method.
.SH UNBINDING
The
.B ldap_unbind()
call is just another name for
.BR ldap_unbind() ;
both of these calls are synchronous in nature.
-.SH RE-BINDING WHILE FOLLOWING REFERRALS
-The
-.B ldap_set_rebind_proc()
-call is used to set a routine that will be called back to obtain bind
-credentials used when a new server is contacted during the following of
-an LDAP referral. Note that this function is only available when the
-LDAP libraries are compiled with LDAP_REFERRALS defined and is only
-used when the ld_options field in the LDAP structure has
-LDAP_OPT_REFERRALS set (this is the default). If
-.B ldap_set_rebind_proc()
-is never called, or if it is called with a NULL \fIrebindproc\fP
-parameter, an unauthenticated simple LDAP bind will always be done
-when chasing referrals.
-.LP
-\fIrebindproc\fP should be a function that is declared like this:
+.\" .SH RE-BINDING WHILE FOLLOWING REFERRALS
+.\" The
+.\" .B ldap_set_rebind_proc()
+.\" call is used to set a routine that will be called back to obtain bind
+.\" credentials used when a new server is contacted during the following of
+.\" an LDAP referral. Note that this function is only available when the
+.\" LDAP libraries are compiled with LDAP_REFERRALS defined and is only
+.\" used when the ld_options field in the LDAP structure has
+.\" LDAP_OPT_REFERRALS set (this is the default). If
+.\" .B ldap_set_rebind_proc()
+.\" is never called, or if it is called with a NULL \fIrebindproc\fP
+.\" parameter, an unauthenticated simple LDAP bind will always be done
+.\" when chasing referrals.
+.\" .LP
+.\" \fIrebindproc\fP should be a function that is declared like this:
+.\" .LP
+.\" .nf
+.\" int rebindproc( LDAP *ld, char **whop, char **credp,
+.\" int *methodp, int freeit );
+.\" .fi
+.\" .LP
+.\" The LDAP library will first call the rebindproc to obtain the
+.\" referral bind credentials, and the \fIfreeit\fP parameter will be
+.\" zero. The \fIwhop\fP, \fIcredp\fP, and \fImethodp\fP should be
+.\" set as appropriate. If the rebindproc returns LDAP_SUCCESS, referral
+.\" processing continues, and the rebindproc will be called a second
+.\" time with \fIfreeit\fP non-zero to give your application a chance to
+.\" free any memory allocated in the previous call.
+.\" .LP
+.\" If anything but LDAP_SUCCESS is returned by the first call to
+.\" the rebindproc, then referral processing is stopped and that error code
+.\" is returned for the original LDAP operation.
.LP
-.nf
-int rebindproc( LDAP *ld, char **whop, char **credp,
- int *methodp, int freeit );
-.fi
-.LP
-The LDAP library will first call the rebindproc to obtain the
-referral bind credentials, and the \fIfreeit\fP parameter will be
-zero. The \fIwhop\fP, \fIcredp\fP, and \fImethodp\fP should be
-set as appropriate. If the rebindproc returns LDAP_SUCCESS, referral
-processing continues, and the rebindproc will be called a second
-time with \fIfreeit\fP non-zero to give your application a chance to
-free any memory allocated in the previous call.
-.LP
-If anything but LDAP_SUCCESS is returned by the first call to
-the rebindproc, then referral processing is stopped and that error code
-is returned for the original LDAP operation.
+The
+.B ldap_unbind_ext()
+and
+.B ldap_unbind_ext_s()
+allows the operations to sepicify controls.
.SH ERRORS
Asynchronous routines will return -1 in case of error, setting the
\fIld_errno\fP parameter of the \fIld\fP structure. Synchronous
routines return whatever \fIld_errno\fP is set to. See
.BR ldap_error (3)
for more information.
+.SH NOTES
+If an anonymous bind is sufficient for the application,the rebind process
+need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option
+set to ON (default value) will automatically follow referrals using an anonymous bind.
+.LP
+If the application needs stronger authentication than an anonymous bind,
+you need to provide a rebind process for that authentication method.
+The bind method must be synchronous.
.SH SEE ALSO
-.BR ldap(3),
-.BR ldap_error(3),
-.BR ldap_open(3)
+.BR ldap (3),
+.BR ldap_error (3),
+.BR ldap_open (3),
+.BR ldap_set_option (3),
+.BR ldap_url_parse (3)
+.B RFC 2222
+(http://www.ietf.org),
+.B Cyrus SASL
+(http://asg.web.cmu.edu/sasl/)
.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
+.B OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
+.B OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.
projects / openldap / blobdiff