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

 #include <ldap.h>

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

The ldap_sasl_bind_s() function can be used to do general authentication over LDAP through the use of the Simple Authentication Security Layer (SASL).

After a connection is made to an LDAP V2 server an LDAP bind API must be called before any other LDAP APIs can be called for that connection. For LDAP V3 servers, binding is optional.

ldap_sasl_bind_s() performs a synchronous request.

Authorities and Locks

For the EXTERNAL mechanism, *R authority is needed to the selected Certificate Store and *X authority is needed to each directory of its path.

Parameters

ld

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

dn

(Input) The Distinguished Name of the entry to bind as, may be NULL.

mechanism

(Input) Although a variety of mechanisms have been IANA registered, the mechanisms supported by the library at this time are:

• LDAP_MECHANISM_EXTERNAL mechanism, represented by the string "EXTERNAL".
• LDAP_MECHANISM_CRAMMD5 mechanism, represented by the string "CRAM-MD5".
• LDAP_MECHANISM_GSSAPI mechanism, represented by the string "GSSAPI".
• LDAP_SASL_SIMPLE, represented by the empty string.
• LDAP_MECHANISM_DIGEST mechanism, represented by the string "DIGEST-MD5".

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

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. The server will use the identity from the client's X.509 certificate that was chosen using the ldap_ssl_client_init() and ldap_ssl_init() or ldap_app_ssl_client_init_np() API. The dn and cred parameters must be NULL.

The LDAP_MECHANISM_CRAMMD5 mechanism is used to authenticate with the server using a challenge/response protocol that protects the "clear-text" password over the wire. This mechanism is useful only when the LDAP server can retrieve the user's password. The contents of the cred berval must be a UTF8 representation of the password. See ldap_xlate_local_to_utf8() for converting local data to UTF8.

The LDAP_MECHANISM_GSSAPI mechanism is used to enable Kerberos authentication. The dn parameter must be NULL. If the cred parameter is NULL, then it is assumed that the user has already authenticated to a Kerberos security server and has obtained a Ticket Granting Ticket (TGT) using a program such as kinit. The GSSAPI credential handle used to initiate a security context on the LDAP client side is obtained from the current login context. The cred parameter can also point to a berval containing a GSSAPI credential handle that will be used to initiate a security context with the LDAP server. For example, a server application can call ldap_sasl_bind_s with a credential handle that the server received from a client as a delegated credential handle.

The LDAP_MECHANISM_DIGEST mechanism is used to authenticate with the server using a challenge/response protocol that protects the "clear-text" password over the wire. Unlike the CRAM-MD5 mechanism, the protocol also includes elements to prevent chosen plaintext attacks. When using this mechanism, the contents of the cred berval must be a UTF-8 representation of the password. See ldap_xlate_local_to_utf8() for converting local data to UTF-8. The LDAP_MECHANISM_DIGEST mechanism requires a username parameter. This is supplied to the API using a client control with an OID of IBM_CLIENT_MD5_USER_NAME_OID and value containing the user name string in UTF-8. The client can specify the DIGEST realm using a client control with an OID of IBM_CLIENT_MD5_REALM_NAME_OID and value containing the realm string in UTF-8. If no realm is supplied the client API will use the first one supplied by the server. The client can specify the DIGEST authorization ID by passing the value as the dn parameter. The format allowed for the dn parameter when using the LDAP_MECHANISM_DIGEST mechanism is either a DN, a DN prefixed with "dn:", or a username prefixed with "u:".

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 Controls for LDAP APIs for more information about server controls.

clientctrls

(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See Controls for LDAP APIs 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 is returned. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_init -- Perform an LDAP initialization operation,
• ldap_ssl_client_init -- Initializes the SSL library.
• ldap_ssl_init -- Initializes an SSL connection.
• ldap_app_ssl_client_init_np -- Initialize the LDAP client for a secure connection using DCM.
• ldap_app_ssl_init_np -- Initializes an SSL connection.
• ldap_get_bind_controls -- Get LDAP bind controls.
• 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.

Examples

This example shows how to use the bind controls to specify parameters to the DIGEST-MD5 mechanism and pass them to the ldap_sasl_bind_s API.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

LDAPControl digest_realm, digest_user_name;
LDAPControl *ctrls[] = { &digest_realm, &digest_user_name, NULL };

digest_realm.ldctl_oid = IBM_CLIENT_MD5_REALM_NAME_OID;
digest_realm.ldctl_value = { strlen( realm ), realm }; /* realm is UTF-8 */
digest_realm.ldctl_iscritical = 0;

Digest_user_name.ldctl_oid = IBM_CLIENT_MD5_USER_NAME_OID;
Digest_user_name.ldctl_value = { strlen( username ), username }; /* username is UTF-8 */
Digest_user_name.ldctl_iscritical = 0;

rc = ldap_sasl_bind_s( ld,
                       dn, /* this is the authzId */
                       LDAP_MECHANISM_DIGEST,
                       NULL, /* server controls */
                       ctrls, /* client controls - realm & username */
                       &servercred );

[ Back to top | LDAP APIs | APIs by category ]