ldap_sasl_bind_s()--Perform an LDAP SASL Bind Request (Synchronous)

Syntax #include <ldap.h> int ldap_sasl_bind_s( LDAP *ld, char *dn, char *mechanism, struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, struct berval **servercredp) Threadsafe: Yes

The ldap_sasl_bind_s() function is used to authenticate a distinguished name (DN) to a directory server using Simple Authentication Security Layer (SASL).

After a connection is made to an LDAP server an LDAP bind API must be called before any other LDAP APIs can be called for that connection.

ldap_sasl_bind_s() is a synchronous request.

With this implementation, the primary reason for using the SASL bind facility is to use the client authentication mechanism provided by SSL to strongly authenticate to the directory server, using the client's X.509 certificate. For example, the client application can use the following logic:

• ldap_ssl_client_init (initialize the SSL library)
• ldap_ssl_init (host, port, name), where name references a public/private key pair in the client's key database file.
• ldap_sasl_bind_s(ld, dn=null, mechanism=LDAP_MECHANISM_EXTERNAL, cred=null...)

A server that supports this mechanism (such as the DSSeries X.500 Directory Server), can then access the directory using the strongly authenticated client identity (as extracted from the client's X.509 certificate).

By setting mechanism to a NULL pointer, the SASL bind request will be interpreted as a request for simple authentication (i.e. equivalent to using ldap_simple_bind() or ldap_simple_bind_s()).

Authorities and Locks

No OS/400 authority is required. All authority checking is done by the LDAP server.

Parameters

ld

(Input) Specifies the LDAP pointer returned by a previous call to ldap_init(),ldap_ssl_init(), or ldap_open().

dn

(Input) Specifies the Distinguished Name of the entry to bind as.

mechanism

(Input) Although a variety of mechanisms have been IANA registered, the only mechanism supported by the library at this time is LDAP_MECHANISM_EXTERNAL mechanism, represented by the string "EXTERNAL". The LDAP_MECHANISM_EXTERNAL mechanism indicates to the server that information external to SASL should be used to determine whether the client is authorized to authenticate. For this implementation, the system providing the external information must be SSL. For example, if the client sets dn and credential to NULL (the value of the pointers should be NULL), with mechanism set to LDAP_MECHANISM_EXTERNAL, the client is requesting that the server use the strongly authenticated identity from the client's X.509 certificate that was used to authenticate the client to the server during the SSL handshake. The server can then use the strongly authenticated identity to access the directory.

cred

(Input) Specifies the credentials with which to authenticate. Arbitrary credentials can be passed using this parameter. In most cases, this is the user's password.

serverctrls

(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP Controls for more information about server controls.

clientctrls

(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP Controls for more information about client controls.

servercredp

(Output) This result parameter will be set to the credentials returned by the server. If no credentials are returned, it will be set to NULL.

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error code

if the request was not successful.

Error Conditions

If ldap_sasl_bind_s() is not successful, an error code will be returned. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

    The following message may be set from this function.
    CPF3CF2 E  Error(s) occurred during running of ldap_sasl_bind_s API.

Related Information

    ldap_sasl_bind() -- Asynchronously bind to the directory using the Simple Authentication Security Layer (SASL).
    ldap_simple_bind() -- Asynchronously bind to the directory using simple authentication.
    ldap_simple_bind_s() -- Synchronously bind to the directory using simple authentication.
    ldap_unbind() -- Asynchronously unbind from the
      LDAP server and close the connection. 
    ldap_unbind_s() -- Synchronously unbind from the
      LDAP server and close the connection. 
    ldap_set_rebind_proc() -- Sets the entry-point of a routine that will be called back to obtain bind credentials when contacting a new LDAP server during the chasing of referrals. 
    ldap_bind () -- Asynchronously bind to the directory (deprecated).
    ldap_bind_s () -- Synchronously bind to the directory (deprecated).