X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman3%2Fldap_bind.3;h=d4b12503a076a3ea2ffeb7b991aef2722e21787a;hb=7190a68f2867bf8f21322fce2eec0e3234264b20;hp=7deb8823686615f23d4a3ef5d778357bebfca252;hpb=0e2af54a3ffdeebe3901370683be56fcc53023b0;p=openldap

diff --git a/doc/man/man3/ldap_bind.3 b/doc/man/man3/ldap_bind.3
index 7deb882368..d4b12503a0 100644
--- a/doc/man/man3/ldap_bind.3
+++ b/doc/man/man3/ldap_bind.3
@@ -1,97 +1,94 @@
-.TH LDAP_BIND 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
-.\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
+.\" 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 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 <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() .
@@ -106,26 +103,6 @@ taking the same parameters but only initiating the bind operation 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).
-.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()
@@ -134,14 +111,143 @@ and
 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()
@@ -154,50 +260,35 @@ The
 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.
+.LP
+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