X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman3%2Fldap_bind.3;h=34b6a23846f520a87105b9499c9180d7df1da8d5;hb=2be146e20ffdabe32514445b6034e40cb7df77be;hp=d2f26a02f2d894ed1a07e808f0b8c4cb9c0ca5d5;hpb=b43ad1dd0eac7f09ef5a6d205cd7f614411bee0c;p=openldap diff --git a/doc/man/man3/ldap_bind.3 b/doc/man/man3/ldap_bind.3 index d2f26a02f2..34b6a23846 100644 --- a/doc/man/man3/ldap_bind.3 +++ b/doc/man/man3/ldap_bind.3 @@ -1,9 +1,11 @@ .TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION" .\" $OpenLDAP$ -.\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. +.\" 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_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, 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 .B #include @@ -22,16 +24,6 @@ ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_kerberos_bind .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 "[]," @@ -51,7 +43,7 @@ ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_kerberos_bind .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS -.BI "const char *" mechs ", struct berval *" cred "," +.BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" @@ -66,6 +58,18 @@ ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_kerberos_bind .\" .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. @@ -76,9 +80,10 @@ 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 +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. @@ -86,13 +91,6 @@ 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_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() . @@ -107,41 +105,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 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 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() @@ -150,16 +113,49 @@ 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 X.500 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() @@ -204,22 +200,38 @@ both of these calls are synchronous in nature. .\" 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 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_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.