LDAP Library Functions ldapbind(3LDAP)
NAME
ldapbind, ldapbinds, ldapsaslbind, ldapsaslbinds,
ldapsimplebind, ldapsimplebinds, ldapunbind,
ldapunbinds, ldapunbindext, ldapsetrebindproc,
ldapsaslinteractivebinds - LDAP bind functions
SYNOPSIS
cc [ flag... ] file... -lldap [ library... ]
#include
#include
int ldapbind(LDAP *ld, char *who, char *cred, int method);
int ldapbinds(LDAP *ld, char *who, char *cred, int method);
int ldapsimplebind(LDAP *ld, char *who, char *passwd);
int ldapsimplebinds(LDAP *ld, char *who, char *passwd);
int ldapunbind(LDAP *ld);
int ldapunbinds(LDAP *ld);
int ldapunbindext(LDAP *ld, LDAPControl **serverctrls,
LDAPControl **clientctrls);
void ldapsetrebindproc(LDAP *ld, int (*rebindproc);
int ldapsaslbind(LDAP *ld, char *dn, char *mechanism,
struct berval **serverctrls, LDAPControl **clientctrls,
int *msgidp);
int ldapsaslbinds(LDAP *ld, char *dn, char *mechanism,
struct berval *cred, LDAPControl **serverctrls,
LDAPControl **clientctrls);
int ldapsaslinteractivebinds(LDAP *ld, char *dn,
char *saslMechanism, LDAPControl **sctrl, LDAPControl **cctrl,
LDAPControl **unsigned flags, LDAPSASLINTERACTPROC *callback,
void *defaults);
SunOS 5.11 Last change: 14 Jan 2004 1
LDAP Library Functions ldapbind(3LDAP)
DESCRIPTION
These functions provide various interfaces to the LDAP bind
operation. After a connection is made to an LDAP server, the
ldapbind() function returns the message ID of the request
initiated. The ldapbinds() function returns an LDAP error
code.
Simple Authentication
The simplest form of the bind call is ldapsimplebinds().
The function takes the DN (Distinguished Name) of the dn
parameter and the userPassword associated with the entry in
passwd to return an LDAP error code. See ldaperror(3LDAP).
The ldapsimplebind() call is asynchronous. The function
takes the same parameters as ldapsimplebinds() but ini-
tiates the bind operation and returns the message ID of the
request sent. The result of the operation can be obtained by
a subsequent call to ldapresult(3LDAP).
General Authentication
The ldapbind() and ldapbinds() functions are used to
select the authentication method at runtime. Both functions
take an extra method parameter to set the authentication
method. For simple authentication, the method parameter is
set to LDAPAUTHSIMPLE. The ldapbind() function returns
the message id of the request initiated. The ldapbinds()
function returns an LDAP error code.
SASL Authentication
The ldapsaslbind() and ldapsaslbinds() functions are
used for general and extensible authentication over LDAP
through the use of the Simple Authentication Security Layer.
The routines both take the DN to bind as the authentication
method. A dotted-string representation of an OID identifies
the method, and the berval structure holds the credentials.
The special constant value LDAPSASLSIMPLE ("") can be
passed to request simple authentication. Otherwise, the
ldapsimplebind() function or the ldapsimplebinds()
function can be used.
The ldapsaslinteractivebinds() helper function takes its
data and performs the necessary ldapsaslbind() and associ-
ated SASL library authentication sequencing with the LDAP
server that uses the provided connection (ld).
Upon a successful bind, the ldapsaslbind() function will,
if negotiated by the SASL interface, install the necessary
internal libldap plumbing to enable SASL integrity and
privacy (over the wire encryption) with the LDAP server.
SunOS 5.11 Last change: 14 Jan 2004 2
LDAP Library Functions ldapbind(3LDAP)
The LDAPSASLINTERACTIVE option flag is passed to the
libldap API through the flags argument of the API. The flag
tells the API to use the SASL interactive mode and to have
the API request SASL authentication data through the
LDAPSASLINTERACTIVEPROC callback as needed. The callback
provided is in the form:
typedef int (LDAPSASLINTERACTPROC)
(LDAP *ld, unsigned flags, void* defaults, void *interact);
The user-provided SASL callback is passed to the current
LDAP connection pointer, the current flags field, an
optional pointer to user-defined data, and the list of
saslinteractt authentication values requested by
libsasl(3LIB) to complete authentication.
The user-defined callback collects and returns the authenti-
cation information in the saslinteractt array according to
libsasl rules. The authentication information can include
user IDs, passwords, realms, or other information defined by
SASL. The SASL library uses this date during sequencing to
complete authentication.
Unbinding
The ldapunbind() call is used to unbind from a directory,
to terminate the current association, and to free the
resources contained in the ld structure. Once the function
is called, the connection to the LDAP server is closed and
the ld structure is invalid. The ldapunbinds() and
ldapunbind() calls are identical and synchronous in nature.
The ldapunbindext() function is used to unbind from a
directory, to terminate the current association, and to free
the resources contained in the LDAP structure. Unlike
ldapunbind() and ldapunbinds(), both server and client
controls can be explicitly included with ldapunbindext()
requests. No server response is made to an unbind request
and responses should not be expected from server controls
included with unbind requests.
Rebinding While Following Referral
The ldapsetrebindproc() call is used to set a function
called back to obtain bind credentials. The credentials are
used when a new server is contacted after an LDAP referral.
If ldapsetrebindproc() is never called, or if it is
called with a NUL rebindproc parameter, an unauthenticated
simple LDAP bind is always done when chasing referrals.
SunOS 5.11 Last change: 14 Jan 2004 3
LDAP Library Functions ldapbind(3LDAP)
The rebindproc() function is declared as shown below:
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. The freeit parameter is zero. The
whop, credp, and methodp parameters should be set as
appropriate. If rebindproc() returns LDAPSUCES, referral
processing continues. The rebindproc() is called a second
time with a non-zero freeit value to give the application a
chance to free any memory allocated in the previous call.
If anything but LDAPSUCES is returned by the first call
to rebindproc(), referral processing is stopped and the
error code is returned for the original LDAP operation.
RETURN VALUES
Make a call to ldapresult(3LDAP) to obtain the result of a
bind operation.
ERORS
Asynchronous functions will return -1 in case of error. See
ldaperror(3LDAP) for more information on error codes
returned. If no credentials are returned, the result parame-
ter is set to NUL.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level Safe
SEE ALSO
ldap(3LDAP), ldaperror(3LDAP), ldapopen(3LDAP),
ldapresult(3LDAP), libsasl(3LIB), attributes(5)
SunOS 5.11 Last change: 14 Jan 2004 4
|
