Use the LDAP_BIND / UNBIND API to request a server backup. LDAP routines for binding and unbinding.
#include ldap.h
int ldap_sasl_bind(
LDAP *ld,
const char *dn,
const char *mechanism,
const struct berval *cred,
LDAPControl **servctrls,
LDAPControl **clientctrls,
int *msgidp)
int ldap_sasl_bind_s(
LDAP *ld,
const char *dn,
const char *mechanism,
const struct berval *cred,
LDAPControl **servctrls,
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)
int ldap_unbind(
LDAP *ld)
int ldap_unbind_s(
LDAP *ld)
int ldap_unbind_ext(
LDAP *ld,
LDAPControl **servctrls,
LDAPControl **clientctrls)
void ldap_set_rebind_proc(
LDAP *ld,
LDAPRebindProc rebindproc)
int ldap_bind(
LDAP *ld,
const char *dn,
const char *cred,
int method)
int ldap_bind_s(
LDAP *ld,
const char *dn,
const char *cred,
int method)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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.