-.TH LDAP_BIND 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2009 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_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");"
+.LP
+.BI "int ldap_unbind(LDAP *" ld ");"
+.LP
+.BI "int ldap_unbind_s(LDAP *" ld ");"
+.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 ");"
+.LP
+.BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", 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
+For SASL binds the server always ignores any provided DN, so the
+.I dn
+parameter should always be NULL.
+.BR ldap_sasl_bind_s ()
+sends a single SASL bind request with the given SASL
+.I mechanism
+and credentials in the
+.I cred
+parameter. The format of the credentials depends on the particular
+SASL mechanism in use. For mechanisms that provide mutual authentication
+the server's credentials will be returned in the
+.I servercredp
+parameter.
+The routine returns an LDAP error indication (see
+.BR ldap_error (3)).
+The
+.BR ldap_sasl_bind ()
+call is asynchronous, taking the same parameters but only sending the
+request and 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).
+The result must be additionally parsed by
+.BR ldap_parse_sasl_bind_result ()
+to obtain any server credentials sent from the server.
+.LP
+Many SASL mechanisms require multiple message exchanges to perform a
+complete authentication. Applications should generally use
+.BR ldap_sasl_interactive_bind_s ()
+rather than calling the basic
+.BR ldap_sasl_bind ()
+functions directly. The
+.I mechs
+parameter should contain a space-separated list of candidate mechanisms
+to use. If this parameter is NULL or empty the library will query
+the supportedSASLMechanisms attribute from the server's rootDSE
+for the list of SASL mechanisms the server supports. The
+.I flags
+parameter controls the interaction used to retrieve any necessary
+SASL authentication parameters and should be one of:
+.TP
+LDAP_SASL_AUTOMATIC
+use defaults if available, prompt otherwise
+.TP
+LDAP_SASL_INTERACTIVE
+always prompt
+.TP
+LDAP_SASL_QUIET
+never prompt
+.LP
+The
+.I interact
+function uses the provided
+.I defaults
+to handle requests from the SASL library for particular authentication
+parameters. There is no defined format for the
+.I defaults
+information;
+it is up to the caller to use whatever format is appropriate for the
+supplied
+.I interact
+function.
+The
+.I sasl_interact
+parameter comes from the underlying SASL library. When used with Cyrus SASL
+this is an array of
+.B sasl_interact_t
+structures. The Cyrus SASL library will prompt for a variety of inputs,
+including:
+.TP
+SASL_CB_GETREALM
+the realm for the authentication attempt
+.TP
+SASL_CB_AUTHNAME
+the username to authenticate
+.TP
+SASL_CB_PASS
+the password for the provided username
+.TP
+SASL_CB_USER
+the username to use for proxy authorization
+.TP
+SASL_CB_NOECHOPROMPT
+generic prompt for input with input echoing disabled
+.TP
+SASL_CB_ECHOPROMPT
+generic prompt for input with input echoing enabled
+.TP
+SASL_CB_LIST_END
+indicates the end of the array of prompts
+.LP
+See the Cyrus SASL documentation for more details.
+.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 parameters are as follows:
+.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 (3)
+function to parse the string into its components.
+.LP
+The \fIrequest\fP parameter specifies the type of request that generated the referral.
+.LP
+The \fImsgid\fP parameter specifies the message ID of the request generating the referral.
+.LP
+The \fIparams\fP parameter is the same value as passed originally to the
+.BR ldap_set_rebind_proc ()
+function.
+.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:
.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 specify controls.
.SH ERRORS
-Asynchronous routines will return -1 in case of error, setting the
+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 4422
+(http://www.rfc-editor.org),
+.B Cyrus SASL
+(http://asg.web.cmu.edu/sasl/)
.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+.so ../Project
projects / openldap / blobdiff