-.TH LDAP_BIND 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_BIND 3 "13 January 2002" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 1998-2002 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_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
.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;
+.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_kerberos_bind_s(LDAP *" ld ", const char *" who ");"
+.LP
+.BI "int ldap_kerberos_bind1(LDAP *" ld ", const char *" who ");"
+.LP
+.BI "int ldap_kerberos_bind1_s(LDAP *" ld ", const char *" who ");"
+.LP
+.BI "int ldap_kerberos_bind2(LDAP *" ld ", const char *" who ");"
+.LP
+.BI "int ldap_kerberos_bind2_s(LDAP *" ld ", const char *" who ");"
+.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 ", struct berval *" cred ","
+.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 )
.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 many types of bind calls, providing simple authentication, Kerberos
+version 4 authentication, and general routines to do either one, as
+well as calls using
+.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).
+.LP
+Kerberos version 4 has been superseded by Kerberos version 5, and the
+Kerberos version 4 support is only provided for backward compatibility. The
+SASL interfaces should be used for new applications. SASL provides
+a general interface for using Kerberos versions 4 and 5 and many other
+security systems.
+.LP
.SH SIMPLE AUTHENTICATION
The simplest form of the bind call is
.BR ldap_simple_bind_s() .
.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
+Kerberos version 4 authentication can be performed. As mentioned above,
+these Kerberos routines are provided only for backward compatibility.
+.LP
+These routines assume the user already
+has obtained a ticket granting ticket. The routines take \fIwho\fP, the DN
+of the entry to bind as. The
+.B ldap_kerberos_bind_s()
+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.
+individual steps, authenticating to the LDAP server and X.500 DSA, respectively.
The
.B ldap_kerberos_bind1()
and
.B ldap_kerberos_bind2()
routines provide equivalent asynchronous access.
+.LP
+The
+.B ldap_kerberos_bind_s()
+routine is used to perform both authentication steps when contacting
+an LDAP server that is a gateway to an X.500 DSA. This kind of server
+configuration is only supported in the (very old) University of Michigan LDAP
+release. The OpenLDAP package no longer provides this gateway server.
+The standalone LDAP server provided in OpenLDAP may still be configured
+with Kerberos version 4 support, but it only requires one authentication
+step, and will return an error if the second step is attempted. Therefore,
+only the
+.B ldap_kerberos_bind1()
+routine or its synchronous equivalent may be used when contacting an
+OpenLDAP server.
.SH GENERAL AUTHENTICATION
The
.B ldap_bind()
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.
+Kerberos authentication to the LDAP server, or Kerberos authentication
+to the X.500 DSA, respectively.
.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 UNBINDING
The
.B ldap_unbind()
.SH SEE ALSO
.BR ldap(3),
.BR ldap_error(3),
-.BR ldap_open(3)
+.BR ldap_open(3),
+.B RFC 2222
+(http://www.ietf.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/).
projects / openldap / commitdiff