+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.
projects / openldap / blobdiff