 |
OpenVMS Utility Routines Manual
13.3 LDAP Error Codes
Many of the LDAP API functions return LDAP error codes, some of which
indicate local errors and some of which may be returned by servers. All
of the LDAP error codes returned will be positive integers; those
between 0x00 and 0x50 are returned from the LDAP server, those above
0x50 are generated by the API itself. Supported error codes are as
follows (hexadecimal values are given in parentheses after the
constant):
LDAP_SUCCESS (0x00)
LDAP_OPERATIONS_ERROR (0x01)
LDAP_PROTOCOL_ERROR (0x02)
LDAP_TIMELIMIT_EXCEEDED (0x03)
LDAP_SIZELIMIT_EXCEEDED (0x04)
LDAP_COMPARE_FALSE (0x05)
LDAP_COMPARE_TRUE (0x06)
LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
LDAP_STRONG_AUTH_REQUIRED (0x08)
LDAP_REFERRAL (0x0a) -- new in LDAPv3
LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3
LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3
LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3
LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3
LDAP_NO_SUCH_ATTRIBUTE (0x10)
LDAP_UNDEFINED_TYPE (0x11)
LDAP_INAPPROPRIATE_MATCHING (0x12)
LDAP_CONSTRAINT_VIOLATION (0x13)
LDAP_TYPE_OR_VALUE_EXISTS (0x14)
LDAP_INVALID_SYNTAX (0x15)
LDAP_NO_SUCH_OBJECT (0x20)
LDAP_ALIAS_PROBLEM (0x21)
LDAP_INVALID_DN_SYNTAX (0x22)
LDAP_IS_LEAF (0x23) -- not used in LDAPv3
LDAP_ALIAS_DEREF_PROBLEM (0x24)
LDAP_INAPPROPRIATE_AUTH (0x30)
LDAP_INVALID_CREDENTIALS (0x31)
LDAP_INSUFFICIENT_ACCESS (0x32)
LDAP_BUSY (0x33)
LDAP_UNAVAILABLE (0x34)
LDAP_UNWILLING_TO_PERFORM (0x35)
LDAP_LOOP_DETECT (0x36)
LDAP_NAMING_VIOLATION (0x40)
LDAP_OBJECT_CLASS_VIOLATION (0x41)
LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
LDAP_NOT_ALLOWED_ON_RDN (0x43)
LDAP_ALREADY_EXISTS (0x44)
LDAP_NO_OBJECT_CLASS_MODS (0x45)
LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDA
LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3
LDAP_OTHER (0x50)
LDAP_SERVER_DOWN (0x51)
LDAP_LOCAL_ERROR (0x52)
LDAP_ENCODING_ERROR (0x53)
LDAP_DECODING_ERROR (0x54)
LDAP_TIMEOUT (0x55)
LDAP_AUTH_UNKNOWN (0x56)
LDAP_FILTER_ERROR (0x57)
LDAP_USER_CANCELLED (0x58)
LDAP_PARAM_ERROR (0x59)
LDAP_NO_MEMORY (0x5a)
LDAP_CONNECT_ERROR (0x5b)
LDAP_NOT_SUPPORTED (0x5c)
LDAP_CONTROL_NOT_FOUND (0x5d)
LDAP_NO_RESULTS_RETURNED (0x5e)
LDAP_MORE_RESULTS_TO_RETURN (0x5f)
LDAP_CLIENT_LOOP (0x60)
LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
|
13.4 Initializing an LDAP Session
The
ldap_init()
function initializes a session with an LDAP server. The server is not
actually contacted until an operation is performed that requires it,
allowing various options to be set after initialization.
LDAP *ldap_init(
const char *hostname,
int portno);
|
Use of the following function is deprecated.
LDAP *ldap_open(
const char *hostname,
int portno);
|
Unlike
ldap_init()
, the
ldap_open()
function attempts to make a server connection before returning to the
caller. A more complete description can be found in RFC 1823.
Parameters are as follows:
|
hostname
|
Contains a space-separated list of hostnames or dotted strings
representing the IP address of hosts running an LDAP server to connect
to. Each hostname in the list can include an optional port number which
is separated from the host itself with a colon (:) character. The hosts
are tried in the order listed, stopping with the first one to which a
successful connection is made. Note that only
ldap_open()
attempts to make the connection before returning to the caller.
ldap_init()
does not connect to the LDAP server.
|
|
portno
|
Contains the TCP port number to connect to. The default LDAP port of
389 can be obtained by supplying the constant LDAP_PORT. If a host
includes a port number, then this parameter is ignored.
|
The
ldap_init()
and
ldap_open()
functions both return a session handle, a pointer to an opaque
structure that should be passed to subsequent calls pertaining to the
session. These functions return NULL if the session cannot be
initialized, in which case the operating system error reporting
mechanism can be checked to see why the call failed.
Note that if you connect to an LDAP Version 2 server, one of the
ldap_bind()
calls must be completed before other operations can be performed on the
session. LDAPv3 does not require that a bind operation be completed
before other operations can be performed.
The calling program can set various attributes of the session by
calling the functions described in the next section.
13.5 LDAP Session Handle Options
The LDAP session handle returned by
ldap_init()
is a pointer to an opaque data type representing an LDAP session.
Formerly, this data type was a structure exposed to the caller, and
various fields in the structure could be set to control aspects of the
session, such as size and time limits on searches.
To insulate callers from inevitable changes to this structure, these
aspects of the session are now accessed through a pair of accessor
functions.
The
ldap_get_option()
function is used to access the current value of various session-wide
parameters. The
ldap_set_option()
function is used to set the value of these parameters. Note that some
options are READ-ONLY and cannot be set; it is an error to call
ldap_set_option()
and attempt to set a READ-ONLY option.
int ldap_get_option(
LDAP *ld,
int option,
void *outvalue
);
int ldap_set_option(
LDAP *ld,
int option,
const void *invalue
);
|
Parameters are as follows:
|
ld
|
The session handle. If this is NULL, a set of global defaults is
accessed. New LDAP session handles created with
ldap_init()
or
ldap_open()
inherit their characteristics from these global defaults.
|
|
option
|
The name of the option being accessed or set. This parameter should be
one of the following constants, which have the indicated meanings.
After the constant, the actual hexadecimal value of the constant is
listed in parentheses.
|
|
|
LDAP_OPT_DESC (0x01)
|
Type for invalue parameter: not applicable (option is read-only).
Type for outvalue parameter: int *
Description: The underlying socket descriptor corresponding to the
primary LDAP connection. This option is read-only and cannot be set.
|
|
|
LDAP_OPT_DEREF (0x02)
|
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description: Determines how aliases are handled during search. It
can have one of the following values: LDAP_DEREF_NEVER (0x00),
LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value means aliases
should be dereferenced during the search but not when locating the base
object of the search.The LDAP_DEREF_FINDING value means aliases should
be dereferenced when locating the base object but not during the search.
|
|
|
LDAP_OPT_SIZELIMIT (0x03)
|
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description: A limit on the number of entries to return from a
search. A value of LDAP_NO_LIMIT (0) means no limit.
|
|
|
LDAP_OPT_TIMELIMIT (0x04)
|
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description: A limit on the number of seconds to spend on a search.
A value of LDAP_NO_LIMIT (0) means no limit.
|
|
|
LDAP_OPT_REFERRALS (0x08)
|
Type for invalue parameter: int (LDAP_OPT_ON or LDAP_OPT_OFF)
Type for outvalue parameter: int *
Description: Determines whether the LDAP library automatically
follows referrals returned by LDAP servers. It can be set to one of the
constants LDAP_OPT_ON (1) or LDAP_OPT_OFF (0).
|
|
|
LDAP_OPT_RESTART (0x09)
|
Type for invalue parameter: int (LDAP_OPT_ON or LDAP_OPT_OFF)
Type for outvalue parameter: int *
Description: Determines whether LDAP I/O operations should
automatically be restarted if they abort prematurely. It should be set
to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. This option is
useful if an LDAP I/O operation is interrupted prematurely, (for
example, by a timer going off) or other interrupt.
|
|
|
LDAP_OPT_PROTOCOL_VERSION (0x11)
|
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description: This option indicates the version of the LDAP protocol
used when communicating with the primary LDAP server. It must be one of
the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3). If no version is
set, the default is LDAP_VERSION2 (2).
|
|
|
LDAP_OPT_SERVER_CONTROLS (0x12)
|
Type for invalue parameter: LDAPControl **
Type for outvalue parameter: LDAPControl ***
Description: A default list of LDAP server controls to be sent with
each request. See Section 13.6 for more information.
|
|
|
LDAP_OPT_CLIENT_CONTROLS (0x13)
|
Type for invalue parameter: LDAPControl **
Type for outvalue parameter: LDAPControl ***
Description: A default list of client controls that affect the LDAP
session. See Section 13.6 for more information.
|
|
|
LDAP_OPT_HOST_NAME (0x30)
|
Type for invalue parameter: char *
Type for outvalue parameter: char **
Description: The host name (or list of host) for the primary LDAP
server.
|
|
|
LDAP_OPT_ERROR_NUMBER (0x31)
|
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description: The code of the most recent LDAP error that occurred
for this session.
|
|
|
LDAP_OPT_ERROR_STRING (0x32)
|
Type for invalue parameter: char *
Type for outvalue parameter: char **
Description: The message returned with the most recent LDAP error
that occurred for this session.
|
|
outvalue
|
The address of a place to put the value of the option. The actual type
of this parameter depends on the setting of the option parameter. For
outvalues of type char ** and LDAPControl **, a pointer to data that is
associated with the LDAP session ld is returned; callers should dispose
of the memory by calling
ldap_memfree()
or
ldap_controls_free()
.
|
|
invalue
|
A pointer to the value the option is to be given. The actual type of
this parameter depends on the setting of the option parameter. The
constants LDAP_OPT_ON and LDAP_OPT_OFF can be given for options that
have on or off settings.
Both
ldap_get_option()
and
ldap_set_option()
return 0 if successful and -1 if an error occurs.
|
13.6 Working with Controls
LDAPv3 operations can be extended through the use of controls. Controls
may be sent to a server or returned to the client with any LDAP
message. These controls are referred to as server controls.
The LDAP API also supports a client-side extension mechanism through
the use of client controls. These controls affect the behavior of the
LDAP API only and are never sent to a server. A common data structure
is used to represent both types of controls:
typedef struct ldapcontrol {
char *ldctl_oid;
struct berval ldctl_value;
char ldctl_iscritical;
} LDAPControl, *PLDAPControl;
|
The fields in the ldapcontrol structure have the following meanings:
|
ldctl_oid
|
The control type, represented as a string.
|
|
ldctl_value
|
The data associated with the control (if any). To specify a zero-length
value, set ldctl_value.bv_len to zero and ldctl_value.bv_val to a
zero-length string. To indicate that no data is associated with the
control, set ldctl_value.bv_val to NULL.
|
|
ldctl_iscritical
|
Indicates whether the control is critical or not. If this field is
non-zero, the operation will only be carried out if the control is
recognized by the server and/or client.
|
Some LDAP API calls allocate an ldapcontrol structure or a
NULL-terminated array of ldapcontrol structures. The following
functions can be used to dispose of a single control or an array of
controls:
void ldap_control_free( LDAPControl *ctrl );
void ldap_controls_free( LDAPControl **ctrls );
|
A set of controls that affect the entire session can be set using the
ldap_set_option()
function. A list of controls can also be passed directly to some LDAP
API calls, such as
ldap_search_ext()
, in which case any controls set for the session through the use of
ldap_set_option()
are ignored. Control lists are represented as a NULL-terminated array
of pointers to ldapcontrol structures.
Server controls are defined by LDAPv3 protocol extension documents; for
example, a control has been proposed to support paging of search
results. No client controls are currently implemented in this version
of the API.
13.7 Authenticating to the Directory
The following functions are used to authenticate an LDAP client to an
LDAP directory server.
The
ldap_sasl_bind()
and
ldap_sasl_bind_s()
functions can be used to do general and extensible authentication over
LDAP through the use of the Simple Authentication Security Layer. The
functions both take the DN to bind as, the method to use, as a
dotted-string representation of an OID identifying the method, and a
struct berval holding the credentials. The special constant value
LDAP_SASL_SIMPLE (NULL) can be passed to request simple authentication,
or the simplified functions
ldap_simple_bind()
or
ldap_simple_bind_s()
can be used.
int ldap_sasl_bind(
LDAP *ld,
const char *dn,
const char *mechanism,
const struct berval *cred,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_sasl_bind_s(
LDAP *ld,
const char *dn,
const char *mechanism,
const struct berval *cred,
LDAPControl **serverctrls,
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
);
|
The use of the following functions is deprecated:
int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
|
Parameters are as follows:
|
ld
|
The session handle.
|
|
dn
|
The name of the entry to bind as.
|
|
mechanism
|
Either LDAP_SASL_SIMPLE (NULL) to get simple authentication, or a text
string identifying the SASL method.
|
|
cred
|
The credentials with which to authenticate. Arbitrary credentials can
be passed using this parameter. The format and content of the
credentials depends on the setting of the mechanism parameter.
|
|
passwd
|
For
ldap_simple_bind()
, the password to compare to the entry's userPassword attribute.
|
|
serverctrls
|
List of LDAP server controls.
|
|
clientctrls
|
List of client controls.
|
|
msgidp
|
This result parameter will be set to the message id of the request if
the
ldap_sasl_bind()
call succeeds.
|
|
servercredp
|
This result parameter will be filled in with the credentials passed
back by the server for mutual authentication, if given. An allocated
berval structure is returned that should be disposed of by calling
ber_bvfree(). NULL may be passed to ignore this field.
|
Additional parameters for the deprecated functions are not described.
See the RFC 1823 documentation for more information.
The
ldap_sasl_bind()
function initiates an asynchronous bind operation and returns the
constant LDAP_SUCCESS if the request was successfully sent or another
LDAP error code if not. See Section 13.18 for more information about
possible errors and how to interpret them. If successful,
ldap_sasl_bind()
places the message id of the request in *msgidp. A subsequent call to
ldap_result()
can be used to obtain the result of the bind.
The
ldap_simple_bind()
function initiates a simple asynchronous bind operation and returns the
message id of the operation initiated. A subsequent call to
ldap_result()
can be used to obtain the result of the bind. In case of error,
ldap_simple_bind()
will return -1, setting the session error parameters in the LDAP
structure appropriately.
The synchronous
ldap_sasl_bind_s()
and
ldap_simple_bind_s()
functions both return the result of the operation, either the constant
LDAP_SUCCESS if the operation was successful, or another LDAP error
code if it was not. See Section 13.18 for more information about
possible errors and how to interpret them.
Note that if an LDAP Version 2 server is contacted, no other operations
over the connection should be attempted before a bind call has
successfully completed.
Subsequent bind calls can be used to reauthenticate over the same
connection, and multistep SASL sequences can be accomplished through a
sequence of calls to
ldap_sasl_bind()
or
ldap_sasl_bind_s()
.
13.8 Closing the Session
The following functions are used to unbind from the directory, close
the connection, and dispose of the session handle.
int ldap_unbind( LDAP *ld );
int ldap_unbind_s( LDAP *ld );
|
Parameter is as follows:
The
ldap_unbind()
and
ldap_unbind_s()
functions both work synchronously, unbinding from the directory,
closing the connection, and freeing up the ld structure before
returning. There is no server response to an unbind operation. The
ldap_unbind()
function returns LDAP_SUCCESS (or another LDAP error code if the
request cannot be sent to the LDAP server). After a call to
ldap_unbind()
or
ldap_unbind_s()
, the session handle ld is invalid and it is illegal to make any
further LDAP API calls using ld.
13.9 Searching
The following functions are used to search the LDAP directory,
returning a requested set of attributes for each entry matched. There
are five variations.
int ldap_search_ext(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
int *msgidp
);
int ldap_search_ext_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
LDAPMessage **res
);
int ldap_search(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly
);
int ldap_search_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPMessage **res
);
int ldap_search_st(
LDAP *ld,
char *base,
int scope,
char *filter,
char **attrs,
int attrsonly,
struct timeval *timeout,
LDAPMessage **res
);
|
Parameters are as follows:
|
ld
|
The session handle.
|
|
base
|
The dn of the entry at which to start the search.
|
|
scope
|
One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), or
LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the search.
|
|
filter
|
A character string representing the search filter. The value NULL can
be passed to indicate that the filter (objectclass=*) that matches all
entries should be used.
|
|
attrs
|
A NULL-terminated array of strings indicating which attributes to
return for each matching entry. Passing NULL for this parameter causes
all available user attributes to be retrieved. The special constant
string LDAP_NO_ATTRS (1.1) can be used as the only element in the array
to indicate that no attribute types should be returned by the server.
The special constant string LDAP_ALL_USER_ATTRS (*), can be used in the
attrs array along with the names of some operational attributes to
indicate that all user attributes plus the listed operational
attributes should be returned.
|
|
attrsonly
|
A boolean value that should be either zero if both attribute types and
values are to be returned or non-zero if only types are wanted.
|
|
timeout
|
For the
ldap_search_st()
function, this specifies the local search timeout value (if it is NULL,
the timeout is infinite). For the
ldap_search_ext()
and
ldap_search_ext_s()
functions, this specifies both the local search timeout value and the
operation time limit that is sent to the server within the search
request. For the
ldap_search_ext()
and
ldap_search_ext_s()
functions, passing a NULL value for timeout causes the global default
timeout stored in the LDAP session handle to be used (set using
ldap_set_option()
with the LDAP_OPT_TIMELIMIT parameter).
|
|
sizelimit
|
For the
ldap_search_ext()
and
ldap_search_ext_s()
calls, this is a limit on the number of entries to return from the
search. A value of LDAP_NO_LIMIT (0) means no limit.
|
|
res
|
For the synchronous calls, this is a result parameter which will
contain the results of the search upon completion of the call.
|
|
serverctrls
|
List of LDAP server controls.
|
|
clientctrls
|
List of client controls.
|
|
msgidp
|
This result parameter will be set to the message id of the request if
the
ldap_search_ext()
call succeeds.
|
|
