MAN page from RedHat Other ldap-devel-3.3-3.i386.rpm

LDAP_BIND

Section: C Library Functions (3)
Updated: 28 March 1996
Index

NAME

ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_kerberos_bind_s, ldap_kerberos_bind1, ldap_kerberos_bind1_s, ldap_kerberos_bind2, ldap_kerberos_bind2_s, ldap_unbind, ldap_unbind_s, ldap_set_rebind_proc - LDAP bind routines

SYNOPSIS

#include <lber.h>#include <ldap.h>int ldap_bind(ld, who, cred, method)LDAP *ld;char *who, *cred;int method;int ldap_bind_s(ld, who, cred, method)LDAP *ld;char *who, *cred;int method;int ldap_simple_bind(ld, who, passwd)LDAP *ld;char *who, *passwd;int ldap_simple_bind_s(ld, who, passwd)LDAP *ld;char *who, *passwd;int ldap_kerberos_bind_s(ld, who)LDAP *ld;char *who;int ldap_kerberos_bind1(ld, who)LDAP *ld;char *who;int ldap_kerberos_bind1_s(ld, who)LDAP *ld;char *who;int ldap_kerberos_bind2(ld, who)LDAP *ld;char *who;int ldap_kerberos_bind2_s(ld, who)LDAP *ld;char *who;int ldap_unbind(ld)LDAP *ld;int ldap_unbind_s(ld)LDAP *ld;void ldap_set_rebind_proc( ld, rebindproc )LDAP *ld;int (*rebindproc)();

DESCRIPTION

These routines provide various interfaces to the LDAP bind operation.After a connection is made to an LDAP server usingldap_open(3),an LDAP bind operation must be performed before other operations canbe attempted over the conection. Both synchronous and asynchronousversions of each variant of the bind call are provided. There arethree types of calls, providing simple authentication, kerberosauthentication, and general routines to do either one. All routinestake ld as their first parameter, as returned fromldap_open(3).

SIMPLE AUTHENTICATION

The simplest form of the bind call isldap_simple_bind_s().It takes the DN to bind as in who, and the userPassword associatedwith the entry in passwd. It returns an LDAP error indication(seeldap_error(3)).Theldap_simple_bind()call is asynchronous,taking the same parameters but only initiating the bind operation andreturning the message id of the request it sent. The result of theoperation can be obtained by a subsequent call toldap_result(3).

KERBEROS AUTHENTICATION

If the LDAP library and LDAP server being contacted have beencompiled with the KERBEROS option defined,Kerberos version 4 authentication can be accomplished by callingtheldap_kerberos_bind_s()routine. It assumes the user alreadyhas obtained a ticket granting ticket. It takes who, the DNof the entry to bind as. This routine does both steps of thekerberos binding process synchronously. Theldap_kerberos_bind1_s()andldap_kerberos_bind2_s()routines allow synchronous access to theindividual steps, authenticating to the LDAP server and DSA, respectively.Theldap_kerberos_bind1()andldap_kerberos_bind2()routines provide equivalent asynchronous access.

GENERAL AUTHENTICATION

Theldap_bind()andldap_bind_s()routines can be used when theauthentication method to use needs to be selected at runtime. Theyboth take an extra method parameter selecting the authenticationmethod to use. It should be set to one of LDAP_AUTH_SIMPLE,LDAP_AUTH_KRBV41, or LDAP_AUTH_KRBV42, to select simple authentication,kerberos authentication to the LDAP server, or kerberos authenticationto the DSA, respectively.ldap_bind()returns the message id of the request it initiates.ldap_bind_s()returns an LDAP error indication.

UNBINDING

Theldap_unbind()call is used to unbind from the directory,terminate the current association, and free the resources containedin the ld structure. Once it is called, the connection tothe LDAP server is closed, and the ld structure is invalid.Theldap_unbind_s()call is just another name forldap_unbind();both of these calls are synchronous in nature.

RE-BINDING WHILE FOLLOWING REFERRALS

Theldap_set_rebind_proc()call is used to set a routine that will be called back to obtain bindcredentials used when a new server is contacted during the following ofan LDAP referral. Note that this function is only available when theLDAP libraries are compiled with LDAP_REFERRALS defined and is onlyused when the ld_options field in the LDAP structure hasLDAP_OPT_REFERRALS set (this is the default). Ifldap_set_rebind_proc()is never called, or if it is called with a NULL rebindprocparameter, an unauthenticated simple LDAP bind will always be donewhen chasing referrals.

rebindproc should be a function that is declared like this:

int rebindproc( LDAP *ld, char **whop, char **credp,    int *methodp, int freeit );

The LDAP library will first call the rebindproc to obtain thereferral bind credentials, and the freeit parameter will bezero. The whop, credp, and methodp should beset as appropriate. If the rebindproc returns LDAP_SUCCESS, referralprocessing continues, and the rebindproc will be called a secondtime with freeit non-zero to give your application a chance tofree any memory allocated in the previous call.

If anything but LDAP_SUCCESS is returned by the first call tothe rebindproc, then referral processing is stopped and that error codeis returned for the original LDAP operation.

ERRORS

Asynchronous routines will return -1 in case of error, setting theld_errno parameter of the ld structure. Synchronousroutines return whatever ld_errno is set to. Seeldap_error(3)for more information.

This document was created byman2html,using the manual pages.