Authenticating

   The following functions are used to authenticate an LDAP client
   to an LDAP directory server.

   The ldap_sasl_bind() and ldap_sasl_bind_s()  functions can be
   used to do general and extensible authentication over LDAP
   through the use of the Simple Authentication Security Layer.
   The functions both take the DN to bind as, the method to use, as
   a dotted-string representation of an OID identifying the method,
   and a struct berval holding the credentials. The special constant
   value LDAP_SASL_SIMPLE (NULL) can be passed to request simple
   authentication, or the simplified functions ldap_simple_bind() or
   ldap_simple_bind_s() can be used.

     int ldap_sasl_bind(
             LDAP                                    *ld,
             const char                              *dn,
             const char                              *mechanism,
             const struct berval                     *cred,
             LDAPControl                             **serverctrls,
             LDAPControl                             **clientctrls,
             int                                     *msgidp
     );

     int ldap_sasl_bind_s(
             LDAP                                    *ld,
             const char                              *dn,
             const char                              *mechanism,
             const struct berval                     *cred,
             LDAPControl                             **serverctrls,
             LDAPControl                             **clientctrls,
             struct berval                           **servercredp
     );

     int ldap_simple_bind(
             LDAP                                    *ld,
             const char                              *dn,
             const char                              *passwd
     );

      int ldap_simple_bind_s(
             LDAP                                    *ld,
             const char                              *dn,
             const char                              *passwd
           );

   The use of the following functions is deprecated:

        int ldap_bind( LDAP *ld, char *dn, char *cred, int method );

        int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );

   Parameters are as follows:

   ld             The session handle.
   dn             The name of the entry to bind as.
   mechanism      Either LDAP_SASL_SIMPLE (NULL) to get simple
                  authentication, or a text string identifying the
                  SASL method.
   cred           The credentials with which to authenticate.
                  Arbitrary credentials can be passed using
                  this parameter. The format and content of
                  the credentials depends on the setting of the
                  mechanism parameter.
   passwd         For ldap_simple_bind(), the password to compare to
                  the entry's userPassword attribute.
   serverctrls    List of LDAP server controls.
   clientctrls    List of client controls.
   msgidp         This result parameter will be set to the message
                  id of the request if the ldap_sasl_bind() call
                  succeeds.
   servercredp    This result parameter will be filled in with the
                  credentials passed back by the server for mutual
                  authentication, if given. An allocated berval
                  structure is returned that should be disposed of
                  by calling ber_bvfree(). NULL may be passed to
                  ignore this field.

   Additional parameters for the deprecated functions are not
   described. See the RFC 1823 documentation for more information.

   The ldap_sasl_bind() function initiates an asynchronous bind
   operation and returns the constant LDAP_SUCCESS if the request
   was successfully sent or another LDAP error code if not. See
   Errors for more information about possible errors and how to
   interpret them. If successful, ldap_sasl_bind() places the
   message id of the request in *msgidp. A subsequent call to ldap_
   result() can be used to obtain the result of the bind.

   The ldap_simple_bind() function initiates a simple asynchronous
   bind operation and returns the message id of the operation
   initiated. A subsequent call to ldap_result() can be used to
   obtain the result of the bind. In case of error, ldap_simple_
   bind() will return -1, setting the session error parameters in
   the LDAP structure appropriately.

   The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s()
   functions both return the result of the operation, either the
   constant LDAP_SUCCESS if the operation was successful, or another
   LDAP error code if it was not. See Errors for more information
   about possible errors and how to interpret them.

   Note that if an LDAP Version 2 server is contacted, no other
   operations over the connection should be attempted before a bind
   call has successfully completed.

   Subsequent bind calls can be used to reauthenticate over the
   same connection, and multistep SASL sequences can be accomplished
   through a sequence of calls to ldap_sasl_bind() or ldap_sasl_
   bind_s().