LDAP_BIND / UNBIND

Synopsis

Input parameters

ld

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

dn

Specifies the Distinguished Names (DN) of the entry to bind as.

mechanism

Although various mechanisms are IANA (Internet Assigned Numbers Authority) registered, the only basic mechanisms that are supported by the LDAP library currently are:

• LDAP_MECHANISM_EXTERNAL mechanism, represented by the string EXTERNAL.
• LDAP_MECHANISM_GSSAPI mechanism, represented by the string GSSAPI.
• LDAP_MECHANISM_DIGEST_MD5 mechanism, represented by the string DIGEST-MD5.
  Note: The CRAM-MD5 mechanism is not supported in a bind operation.

The LDAP_MECHANISM_EXTERNAL mechanism indicates to the server that information external to SASL must be used to determine whether the client is authorized to authenticate. For this implementation, the system that provides the external information must be SSL. For example, if the client sets the DN and credentials to NULL (the value of the pointers must be NULL), with mechanism set to LDAP_MECHANISM_EXTERNAL, the client is requesting that the server use the authenticated identity from the client X.509 certificate that was used to authenticate the client to the server during the SSL handshake. The server can then use the authenticated identity to access the directory.

The LDAP_MECHANISM_GSSAPI mechanism is used to enable Kerberos authentication. In Kerberos authentication, a client presents valid credentials that are obtained from a Kerberos key distribution center (KDC) to an application server. The server decrypts and verifies the credentials using its service key.

When mechanism is set to a NULL pointer, the SASL bind request is interpreted as a request for simple authentication, that is, equivalent to using ldap_simple_bind() or ldap_simple_bind_s().

For more information about using LDAP client plug-ins, see LDAP_PLUGIN_REGISTRATION. For more information about developing an LDAP client plug-in, see LDAP client plug-in programming reference.

The LDAP_MECHANISM_DIGEST_MD5 mechanism is used to authenticate your ID and password with the server by using a challenge or response protocol. The protocol protects the clear-text password over the wire and prevents replay attacks.

This mechanism is useful only when the LDAP server can retrieve the user password. If the password is stored in a hashed form, for example, crypt or SHA, then authentication by using the DIGEST-MD5 mechanism fails. When you use the DIGEST-MD5 mechanism, the host name that is supplied on the ldap_init call must resolve to the fully qualified host name of the server.

The application must supply a user name on the ldap_sasl_bind_s call by using the IBM_CLIENT_MD5_USER_NAME_OID client control. The application can optionally supply a realm on the ldap_sasl_bind_s call by using the IBM_CLIENT_MD5_REALM_NAME_OID client control. The application can optionally supply an authorization ID as the dn parameter.

cred

Specifies the credentials with which to authenticate. Arbitrary credentials can be passed with this parameter. In most cases, this credential is the user password. When you use a Simple Authentication Security Layer (SASL) bind, the format and content of the credentials depends on the setting of the mechanism parameter.

method

Selects the authentication method to use. Specify LDAP_AUTH_SIMPLE for simple authentication or LDAP_AUTH_SASL for SASL bind. The use of the ldap_bind and ldap_bind_s APIs is deprecated.

password

Specifies the password that is used in association with the DN of the entry in which to bind.

serverctrls

Specifies a list of LDAP server controls. For more information about server controls, see LDAP controls.

clientctrls

Specifies a list of LDAP client controls. For more information about client controls, see LDAP controls.

rebindproc

Specifies the entry-point of a routine that is called to obtain bind credentials that are used when a new server is contacted following an LDAP referral.

Output parameters

msgidp

This result parameter is set to the message ID of the request if the ldap_sasl_bind() call succeeds.

servercredp

This result parameter is set to the credentials returned by the server. If no credentials are returned, it is set to NULL.

Usage

These routines provide various interfaces to the LDAP bind operation. After you use ldap_init, ldap_ssl_init or ldap_open to create an LDAP handle, a bind can be run before other operations are attempted over the connection. Both synchronous and asynchronous versions of each variant of the bind call are provided.

A bind is optional when you communicate with an LDAP server that supports the LDAP V3 protocol. The absence of a bind is interpreted by the LDAP V3 server as a request for unauthenticated access. A bind is required by LDAP servers that support only the LDAP V2 protocol.

The ldap_simple_bind() and ldap_simple_bind_s() APIs provide simple authentication, by using a user ID or dn and a password that is passed in clear-text to the LDAP API.

The ldap_bind() and ldap_bind_s() provide general authentication routines, where an authentication method can be chosen. In this toolkit, method must be set to LDAP_AUTH_SIMPLE. Because the use of these two APIs is deprecated, ldap_simple_bind and ldap_simple_bind_s must be used instead.

The ldap_sasl_bind and ldap_sasl_bind_s APIs can be used to run general and extensible authentication over LDAP by using the SASL.

All bind routines take ld as their first parameter as returned from ldap_init, ldap_ssl_init, or ldap_open.

Simple authentication

The simplest form of the bind call is ldap_simple_bind_s(). It takes the DN to bind and the user password (supplied in password). It returns an LDAP error indication (see LDAP_ERROR). The ldap_simple_bind() call is asynchronous, taking the same parameters but initiating only the bind operation and returning the message ID of the request it sent. The result of the operation can be obtained with a subsequent call to ldap_result().

General authentication

The ldap_bind() and ldap_bind_s() routines are deprecated.

The deprecated APIs can be used when the authentication method is selected at run time. They both take an extra method parameter when you select the authentication method to use. However, when you use this toolkit, method must be set to LDAP_AUTH_SIMPLE to select simple authentication. ldap_bind() and ldap_simple_bind() return the message ID of the initiated request. ldap_bind_s() and ldap_simple_bind_s() return an LDAP error indication on unsuccessful completion, or LDAP_SUCCESS on successful completion.

SASL authentication

Five categories of SASL authentication are supported:

• SASL authentication by using the EXTERNAL mechanism
• SASL authentication by using the GSSAPI mechanism (Kerberos is supported and implemented as a plug-in)
• SASL authentication by using the DIGEST-MD5 mechanism (implemented as a plug-in)
• SASL authentication by using a user-supplied SASL plug-in library
• SASL authentication by using a SASL mechanism that is implemented by the application itself

When the input parameter mechanism is set to a NULL pointer, the SASL bind request is interpreted as a request for simple authentication, that is, equivalent to using ldap_simple_bind() or ldap_simple_bind_s().

Also, the SASL authentication mechanism provides a facility for the LDAP server to return server credentials to the client. An application can obtain the server credentials that are returned from the server in the SASL bind result with the ldap_parse_sasl_bind_result() API.

EXTERNAL SASL binds

The primary reason for using the EXTERNAL SASL bind mechanism is to use the client authentication mechanism. This mechanism is provided by SSL to strongly authenticate to the directory server by using the client 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 or private key pair in the client 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 IBM® Directory server, can then access the directory. It uses the authenticated client identity as extracted from the client X.509 certificate.

GSSAPI SASL binds

Kerberos authentication is supported in this release. If the input parameters for ldap_sasl_bind or ldap_sasl_bind_s are mechanism==GSSAPI and cred==NULL, then it is assumed that the user already authenticated to a Kerberos security server and obtained a ticket-granting-ticket (TGT), either through a desktop log-on process, or by 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. If the input parameters for these two SASL bind functions are mechanism==GSSAPI and cred!=NULL, the caller of the functions must provide the GSSAPI credential handle for the LDAP client to initiate a security context with an LDAP server. For example, an LDAP server calls an SASL bind function with a credential handle that the server receives from a client as a delegated credential handle.

DIGEST-MD5 SASL binds

The server accepts SASL bind requests by using the DIGEST-MD5 mechanism. There are two types of DIGEST-MD5 bind requests: Initial Authentication bind requests and Subsequent Authentication bind requests. Initial Authentication is required and supported by IBM Security Directory Server. Subsequent Authentication support is optional, and is not supported by IBM Security Directory Server.

The server responds to a DIGEST-MD5 SASL bind request with a digest-challenge. The challenge contains the values that are required by RFC2831 section 2.1.1, with the following implementation-specific behavior:

• realm - The server always sends the realm that the server is configured to be in.
• nonce - The server generates a random nonce.
• qop-options - The server supports auth only.

The next response from the client to the server must be another DIGEST-MD5 SASL bind message. The response includes several fields with values that the server uses as follows:

• username- The server uses the user name value to determine whether the user is binding as an administrator or to find an entry in the primary rdbm. If the user name is an administrator DigestUsername, then the server uses that administrator to bind. If the user name was not an administrator, then the server searches the primary rdbm for a user with that user name. If the user name does not correspond to a single entry or the entry does not have a user-password value, the server returns LDAP_INVALID_CREDENTIALS. It also prints the appropriate error message.
• realm - The value in the realm field must match the realm that the server is configured to be in. If the realm value does not match the realm that the server is configured to be in, the server returns LDAP_PROTOCOL_ERROR.
• nonce - The value in the nonce field must match the nonce value that the server sent the client with the digest-challenge. If the value does not match, the server returns LDAP_PROTOCOL_ERROR.
• response - The value in the response field contains a hash of the password. For each of the user-password values that the server gets from the user entry, it generates the DIGEST-MD5 hash. The server then compares it with the hash from the client. If one matches, the server returns LDAP_SUCCESS and the user is bound as that user. Otherwise, the server returns LDAP_INVALID_CREDENTIALS and print an error message.
• authzid - The value in the authzid field contains a "dn:"- or "u:"-style authorization ID from RFC 2829. The server uses RFC 2829 for authority checking after the bind, rather than the entry found for the user name, similar to Proxied Authentication. The entry that the user name corresponds to must have the authority to use the other DN. The server maps the value to an entry similar to the user name parameter if the authzid contains a "u:"-style authorization ID. If the mapping fails, the server returns LDAP_INVALID_CREDENTIALS.

User-supplied SASL plug-ins

The application developer, or a third party, can implement more SASL mechanisms by using the IBM Security Directory Server C-Client SASL plug-in facility. For example, a client and server SASL plug-in can be developed that supports a new authentication mechanism that is based upon a retinal scan. If the mechanism associated with this new authentication mechanism is retscan, the application calls ldap_sasl_bind() with mechanism set to retscan. Depending on how the mechanism and plug-in are designed, the application might be required to also supply the user's DN and credentials. Alternatively, the plug-in itself might be responsible for obtaining the user identity and credentials, which are derived in some way from a retinal scan image.

If the retinal scan plug-in is not defined in ibmldap.conf, the application must explicitly register the plug-in, by using the ldap_register_plugin() API. For information about defining a SASL plug-in for use with an application, see the section, Defining a SASL plug-in in LDAP_BIND / UNBIND. For more information about using an LDAP client plug-in, see LDAP_PLUGIN_REGISTRATION. For more information about developing an LDAP client plug-in, see LDAP client plug-in programming reference.

try

SASL mechanisms that are implemented by the application

In some cases, the SASL mechanism might not require the presence of a plug-in, or any special support in the LDAP library. If the application can call the ldap_sasl_bind() or ldap_sasl_bind_s() API with the parameters appropriate to the mechanism, the LDAP library encodes the SASL bind request and sends it to the server. If a plug-in is defined for the specified mechanism, the request is diverted to the plug-in. The request can do more processing before it sends the SASL bind to the server.

SASL mechanisms that are supported by the LDAP server

The application can query the LDAP server root DSE, by using ldap_search() with the following settings:

• base DN set to NULL
• scope that is set to base
• filter that is set to "(objectclass=*)"

If the LDAP server supports one or more SASL mechanisms, the search results include one or more values for the supportedsaslmechanisms attribute type.

Defining a SASL plug-in

When the application issues an ldap_sasl_bind_s() API with a mechanism that is supported by a particular SASL plug-in, the LDAP library must be able to locate the plug-in shared library. Two mechanisms are available for making an LDAP client plug-in that is known to the LDAP library:

• The plug-in for the specified SASL mechanism is defined in the ibmldap.conf file.
• The plug-in is explicitly registered by the application, by using the ldap_register_plugin() API.

For more information about locating a plug-in library and defining plug-ins in the ibmldap.conf file, see the section Finding the plug-in library in LDAP_PLUGIN_REGISTRATION.

Unbinding

ldap_unbind_ext(), ldap_unbind(), and ldap_unbind_s() are synchronous APIs. They send an unbind request to the server. Then, they close all open connections that are associated with the LDAP session handle. Later, they dispose of all resources that are associated with the session handle before a return. There is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS or another LDAP error code if the request cannot be sent to the LDAP server. After a call to one of the unbind functions, the session handle ld is invalid and it is not valid to make any further LDAP API calls by using the ld.

The ldap_unbind() and ldap_unbind_s() APIs behave identically. The ldap_unbind_ext() API allows server and client controls to be included explicitly. Because there is no server response to an unbind request, therefore you cannot receive a response to a server control sent with an unbind request.

Rebinding while following referrals

The ldap_set_rebind_proc() call is used to set the entry-point of a routine that is called back to obtain bind credentials for use when a new server is contacted following an LDAP referral or search reference. This function is available only when LDAP_OPT_REFERRALS is set, which is the default setting. If ldap_set_rebind_proc() is never called, or if it is called with a NULL rebindproc parameter, an unauthenticated simple LDAP bind is always done when you chase referrals. The SSL characteristics of the connections to the referred servers are preserved when you chase referrals. In addition, if the original bind was an LDAP V3 bind, an LDAP V3 bind is used to connect to the referred servers. If the original bind was an LDAP V2 bind, an LDAP V2 bind is used to connect to each referred server.

rebindproc must be a function that is declared as follows:

  int rebindproc( LDAP *ld, char **whop, char **credp,

      int *methodp, int freeit );

The LDAP library first calls the rebindproc to obtain the referral bind credentials, and the freeit parameter is zero. The whop, credp, and methodp parameters must be set as appropriate. If the rebindproc returns LDAP_SUCCESS, referral processing continues, and the rebindproc is called a second time with freeit nonzero to give the application a chance to free any memory that is allocated in the previous call.

If anything other than LDAP_SUCCESS is returned by the first call to the rebindproc, referral processing is stopped and the error code is returned for the original LDAP operation.

Errors

Asynchronous routines return -1 in case of error. However, in the case of the asynchronous bind routine ldap_sasl_bind(), it returns LDAP result code other than LDAP_SUCCESS if the sent request was unsuccessful. To obtain the LDAP result code of the asynchronous bind routine, ldap_sasl_bind(), use the ldap_result() API. To obtain the LDAP error, use the ldap_get_errno() API. Synchronous routines return the LDAP error code that results from the operation.

See also

ldap_error, ldap_open