X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman3%2Fldap_bind.3;h=d4b12503a076a3ea2ffeb7b991aef2722e21787a;hb=7190a68f2867bf8f21322fce2eec0e3234264b20;hp=d2f26a02f2d894ed1a07e808f0b8c4cb9c0ca5d5;hpb=b43ad1dd0eac7f09ef5a6d205cd7f614411bee0c;p=openldap diff --git a/doc/man/man3/ldap_bind.3 b/doc/man/man3/ldap_bind.3 index d2f26a02f2..d4b12503a0 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-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_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,21 +43,31 @@ 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 ");" .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 -.\" .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 ");" +.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. @@ -76,9 +78,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 +89,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 +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 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 +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 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... +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() @@ -172,54 +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), -.B RFC 2222 -(http://www.ietf.org), +.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