LDAP is the C language application programming interface (API)
for the Lightweight Directory Access Protocol (LDAP). This
API supports Version 3 of the LDAP API (LDAPv3), and includes
support for controls, information hiding, and thread safety. It
is available on OpenVMS Alpha only.
1 – Introduction
The C LDAP API is designed to be powerful, yet simple
to use. It defines compatible synchronous and asynchronous
interfaces to LDAP to support a wide variety of applications.
1.1 – Overview of the LDAP Model
LDAP is the lightweight directory access protocol, which is based
on a client-server model. In this model, a client makes a TCP
connection to an LDAP server, over which it sends requests and
receives responses.
The LDAP information model is based on the entry, which contains
information about some object (for example, a person). Entries
are composed of attributes, which have a type and one or more
values. Each attribute has a syntax that determines what kinds
of values are allowed in the attribute (for example, ASCII
characters or a jpeg photograph) and how those values behave
during directory operations (for example, whether case is
significant during comparisons).
Entries may be organized in a tree structure, usually based on
political, geographical, or organizational boundaries. Each entry
is uniquely named relative to its sibling entries by its relative
distinguished name (RDN) consisting of one or more distinguished
attribute values from the entry. At most, one value from each
attribute may be used in the RDN. For example, the entry for the
person Babs Jensen might be named with the Barbara Jensen value
from the commonName attribute.
A globally unique name for an entry, called a distinguished name
or DN, is constructed by concatenating the sequence of RDNs from
the entry up to the root of the tree. For example, if Babs worked
for the University of Michigan, the DN of her U-M entry might be
the following:
cn=Barbara Jensen, o=University of Michigan, c=US
Operations are provided to authenticate, search for and retrieve
information, modify information, and add and delete entries from
the tree.
1.2 – Overview of LDAP API Use
An application generally uses the C LDAP API in four simple
steps.
o Initialize an LDAP session with a primary LDAP server. The
ldap_init() function returns a handle to the session, allowing
multiple connections to be open at once.
o Authenticate to the LDAP server. The ldap_bind() function
supports a variety of authentication methods.
o Perform some LDAP operations and obtain some results. The
ldap_search() function returns results that can be parsed
by ldap_parse_result(), ldap_first_entry(), and ldap_next_
entry().
o Close the session. The ldap_unbind() function closes the
connection.
Operations can be performed either synchronously or
asynchronously. The names of the synchronous functions end
in _s. For example, a synchronous search can be completed by
calling ldap_search_s(). An asynchronous search can be initiated
by calling ldap_search(). All synchronous functions return an
indication of the outcome of the operation (for example, the
constant LDAP_SUCCESS or some other error code). The asynchronous
functions make available to the caller the message id of the
operation initiated. This id can be used in subsequent calls
to ldap_result() to obtain the result(s) of the operation. An
asynchronous operation can be abandoned by calling ldap_abandon()
or ldap_abandon_ext().
Results and errors are returned in an opaque structure called
LDAPMessage. Functions are provided to parse this structure,
step through entries and attributes returned. Functions are also
provided to interpret errors.
LDAPv3 servers may return referrals to other servers. By default,
implementations of this API will attempt to follow referrals
automatically for the application. This behavior can be disabled
globally (using the ldap_set_option() call) or on a per-request
basis through the use of a server control.
As in the LDAPv3 protocol, all DNs and string values that are
passed into or produced by the C LDAP API are represented as
UTF-8 characters. Conversion functions are described in Encoded
ASN.1.
For compatibility with existing applications, implementations of
this API will, by default, use Version 2 of the LDAP protocol.
Applications that intend to take advantage of LDAPv3 features
will need to use the ldap_set_option() call with a LDAP_OPT_
PROTOCOL_VERSION switch set to Version 3.
The file LDAP_EXAMPLE.C in SYS$EXAMPLES contains an example
program that demonstrates how to use the LDAP API on OpenVMS.
1.3 – LDAP API Use on OpenVMS Systems
This release of the LDAP API provides support for client
applications written in C or C++.
In order to use the LDAP API, a program must use an include
statement of the form:
#include <ldap.h>
The LDAP.H header file includes prototypes and data structures
for all of the functions that are available in the LDAP API.
The shareable image LDAP$SHR.EXE includes run-time support for
LDAP applications. This shareable image resides in SYS$LIBRARY
and should be included in the library IMAGELIB.OLB, which means
that no special action is necessary to link or run your programs.
For example:
$ type myprog.c
/* A not very useful program */
#include <stdio.h>
#include <ldap.h>
void main(int argc, char *argv[])
{
LDAP *ld;
if (argc != 2) {
printf("usage: %s <hostname>\n",argv[0]);
return;
}
ld = ldap_init(argv[1],LDAP_PORT);
if (ld != NULL) {
printf("ldap_init returned 0x%p\n",ld);
} else {
printf("ldap_init failed\n");
}
}
$ cc myprog
$ link myprog
$ myprog :== $mydisk:[mydir]myprog.exe
$ myprog fred
ldap_init returned 0xA6748
$
1.4 – 64-bit Addressing Support
OpenVMS Alpha provides support for 64-bit virtual memory
addressing. Applications that are built using a suitable compiler
may take advantage of the 64-bit virtual address space to map and
access large amounts of data.
1.4.1 – Background
The OpenVMS LDAP API supports both 32- and 64-bit client
applications. In order to allow this, separate entry points are
provided in the library for those functions that are sensitive to
pointer size.
When a user module is compiled, the header file LDAP.H determines
the pointer size in effect and uses the C preprocessor to map
the function names into the appropriate library entry point. This
mapping is transparent to the user application and is effected by
setting the /POINTER_SIZE qualifier at compilation time.
For LDAP API users, switching between different pointer sizes
should need only a recompilation-no code changes are necessary.
This means that programs using the specification for the C LDAP
API, as described in the Internet Engineering Task Force (IETF)
documentation, can be built on OpenVMS with either 32-bit or
64-bit pointer size, without having to change the source code.
1.4.2 – Implementation
The OpenVMS LDAP library uses 64-bit pointers internally and is
capable of dealing with data structures allocated by the caller
from 64-bit address space.
Applications that use 32-bit pointers will use the 32-bit
function entry points in the library. This means they can pass
arguments that are based on 32-bit pointers and can assume that
any pointers returned by the library will be 32-bit safe.
While the mapping performed by LDAP.H is designed to be
transparent, there may be occasions where it is useful (for
example in debugging) to understand the consequences of having
both 32- and 64-bit support in the same library.
1.4.2.1 – Library Symbol Names
The symbols exported by the LDAP$SHR OpenVMS run-time library
differ from those specified in the IETF C LDAP API specification.
The header file LDAP.H maps user references to LDAP API function
names to the appropriate LDAP$SHR symbol name. Therefore, any
application wishing to use the OpenVMS LDAP API must include the
version of LDAP.H that ships with OpenVMS.
All of the functions in the OpenVMS LDAP library are prefixed
with the facility code "LDAP$".
For those functions where the caller's pointer size is
significant, the name of the 64-bit entry point will have a "_
64" suffix, while the name of the 32-bit jacket will have a "_32"
suffix. Functions that are not sensitive to pointer size have no
special suffix.
For example, the function ldap_modify() is sensitive to the
caller's pointer size (because one of its arguments is an
array of pointers). Therefore, the library exports symbols for
LDAP$LDAP_MODIFY_64 and LDAP$LDAP_MODIFY_32. For the function
ldap_simple_bind(), which is not sensitive to the caller's
pointer size, a single entry point, LDAP$LDAP_SIMPLE_BIND, exists
in the library.
Because OpenVMS imposes a 31-character limit on the length of
symbol names, certain functions in the library have names which
are abbreviated versions of the public API name. For example,
in the case of the function ldap_parse_sasl_bind_result(), the
library provides two entry points, namely LDAP$LDAP_PRS_SASL_
BIND_RES_32 and LDAP$LDAP_PRS_SASL_BIND_RES_64.
1.4.2.2 – LDAP Data Structures
The LDAP API defines various data structures which are used to
pass information to and from a client application. Some of these
structures are opaque; that is, their internal layout is not
visible to a client application. In such cases, the API may
return a pointer to such a structure, but the only use of such
a pointer to a client application is as a parameter to subsequent
library calls.
Some structures are public. Their contents are defined by the
API, and client applications may allocate and manipulate such
structures or use them as parameters to LDAP functions.
All data structures used by the API are defined with "natural"
alignment; that is, each member of a data structure will be
aligned on an address boundary appropriate to its type.
Opaque Data Structures
The following data structures are opaque. Applications should
not make any assumptions about the contents or size of such data
structures.
typedef struct ldap
LDAP;
typedef struct ldapmsg
LDAPMessage;
typedef struct berelement
BerElement;
Public Data Structures
The following data structures are described in the IETF documents
relating to the LDAP API, and definitions are provided for
them in LDAP.H. Applications may allocate and manipulate such
structures, as well as use them in calls to the LDAP API.
typedef struct berval { .. }
BerValue;
typedef struct ldapapiinfo { .. }
LDAPAPIInfo;
typedef struct ldap_apifeature_info { .. }
LDAPAPIFeatureInfo;
typedef struct ldapcontrol { .. }
LDAPControl;
typedef struct ldapmod { .. }
LDAPMod;
Note that the pointer size in effect at compilation time
determines the layout of data structures, which themselves
contain pointer fields. Since all of the public data structures
listed here contain one or more pointers, their size and layout
will differ depending on the pointer size.
For example, in the case of the structure berval, the API
provides the following definition:
struct berval {
ber_len_t bv_len;
char *bv_val;
} BerValue;
(where ber_len_t is equivalent on OpenVMS to an unsigned 32-bit
integer).
The following code would therefore work correctly regardless of
pointer size:
#include <ldap.h>
.
.
.
char *buff;
BerValue val;
.
.
.
buff = (char *)malloc(255);
.
.
.
val.bv_len = 255;
val.bv_val = buff;
.
.
.
1.4.3 – Mixing Pointer Sizes
Two modules that include LDAP.H can be compiled with different
pointer sizes and linked together. While each module may use the
LDAP API on its own, it may not be possible for both modules to
share LDAP-related data.
None of the public LDAP data structures is directly compatible
between 32- and 64-bit modules. For example, a BerValue that
has been allocated by a 32-bit module does not have the same
layout as a BerValue which a 64-bit module expects to see, and
consequently cannot be exchanged between two such modules without
some sort of data conversion taking place.
Opaque data structures (such as LDAP *) have only a single
structure definition inside the library, and so pointers to such
structures may be exchanged between 32- and 64-bit callers. Note
that these structures are allocated only by the library itself,
and, in the case of a 64-bit caller, these structures may be
allocated in 64-bit space. So while the LDAP handle returned to
a 32-bit caller of ldap_init() could safely be used by a 64-bit
module, the reverse may not be true.
1.5 – Multithreading Support
The OpenVMS LDAP API may be used by a multi-threaded application.
Two of the functions in the library, ldap_perror() and ldap_
result2error(), are not thread-safe.
2 – Data Structures
The following are definitions of some data structures that are
common to several LDAP API functions.
typedef struct ldap LDAP;
typedef struct berelement BerElement;
typedef struct ldapmsg LDAPMessage;
typedef struct berval {
ber_len_t bv_len;
char *bv_val;
} BerValue;
struct timeval;
The LDAP structure is an opaque data type that represents an LDAP
session. Typically, this corresponds to a connection to a single
server, but it may encompass several server connections in LDAPv3
referrals.
The LDAPMessage structure is an opaque data type that is used
to return entry, reference, result, and error information. An
LDAPMessage structure may represent the beginning of a list or a
chain of messages that contain a series of entries, references,
and result messages that are returned by LDAP operations, such
as search. LDAP API functions, such as ldap_parse_result(), that
operate on message chains which may contain more than one result
message, always operate on the first result message in the chain.
See Results for more information.
The BerElement structure is an opaque data type that is used to
hold data and state information about encoded data.
The berval structure is used to represent arbitrary binary data,
and its fields have the following meanings:
bv_len Length of data in bytes.
bv_val A pointer to the data itself.
The timeval structure is used to represent an interval of time,
and its fields have the following meanings:
tv_sec Seconds component of time interval.
tv_usec Microseconds component of time interval.
All memory that is allocated by a function in this C LDAP API
and returned to the caller should be disposed of by calling the
appropriate free function provided by this API.
Memory that is allocated outside of the C LDAP API must not be
disposed of using a function provided by this API.
The following is a complete list of free functions that are used
to dispose of allocated memory:
ber_bvecfree()
ber_bvfree()
ber_free()
ldap_control_free()
ldap_controls_free()
ldap_memfree()
ldap_msgfree()
ldap_value_free()
ldap_value_free_len()
3 – 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)
4 – Initializing
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 Session Handles help
topic.
5 – Session Handles
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 Type for invalue parameter: not
(0x01) 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 Type for invalue parameter: int *
(0x02) 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_ Type for invalue parameter: int *
SIZELIMIT (0x03) 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_ Type for invalue parameter: int *
TIMELIMIT (0x04) 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_ Type for invalue parameter: int
REFERRALS (0x08) (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 Type for invalue parameter: int
(0x09) (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_ Type for invalue parameter: int *
PROTOCOL_VERSION Type for outvalue parameter: int *
(0x11)
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_ Type for invalue parameter:
CONTROLS (0x12) LDAPControl **
Type for outvalue parameter:
LDAPControl ***
Description: A default list of LDAP
server controls to be sent with
each request. See Controls for more
information.
LDAP_OPT_CLIENT_ Type for invalue parameter:
CONTROLS (0x13) LDAPControl **
Type for outvalue parameter:
LDAPControl ***
Description: A default list of
client controls that affect the
LDAP session. See Controls for more
information.
LDAP_OPT_HOST_ Type for invalue parameter: char *
NAME (0x30) Type for outvalue parameter: char
**
Description: The host name (or
list of host) for the primary LDAP
server.
LDAP_OPT_ERROR_ Type for invalue parameter: int *
NUMBER (0x31) Type for outvalue parameter: int *
Description: The code of the most
recent LDAP error that occurred for
this session.
LDAP_OPT_ERROR_ Type for invalue parameter: char *
STRING (0x32) 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.
6 – 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_ Indicates whether the control is critical or not.
iscritical 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.
7 – Authenticating
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
Errors 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 Errors 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().
8 – Closing
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:
ld The session handle.
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.
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.
There are three options in the session handle ld that potentially
affect how the search is performed. They are as follows:
LDAP_OPT_ A limit on the number of entries to return from
SIZELIMIT the search. A value of LDAP_NO_LIMIT (0) means
no limit. Note that the value from the session
handle is ignored when using the ldap_search_
ext() or ldap_search_ext_s() functions.
LDAP_OPT_ A limit on the number of seconds to spend on
TIMELIMIT the search. A value of LDAP_NO_LIMIT (0) means
no limit. Note that the value from the session
handle is ignored when using the ldap_search_
ext() or ldap_search_ext_s() functions.
LDAP_OPT_DEREF One of LDAP_DEREF_NEVER(0x00), LDAP_DEREF_
SEARCHING(0x01), LDAP_DEREF_FINDING (0x02),
or LDAP_DEREF_ALWAYS (0x03), specifying how
aliases should be handled during the search.
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.
The ldap_search_ext() function initiates an asynchronous search
operation and returns either the constant LDAP_SUCCESS if the
request was successfully sent or another LDAP error code if
not. See Errors for more information about possible errors and
how to interpret them. If successful, ldap_search_ext() places
the message id of the request in *msgidp. A subsequent call to
ldap_result() can be used to obtain the results from the search.
These results can be parsed using the result parsing functions
described in Errors.
Similar to ldap_search_ext(), the ldap_search() function
initiates an asynchronous search operation and returns the
message id of the operation initiated. As for ldap_search_ext(),
a subsequent call to ldap_result() can be used to obtain the
result of the search. In case of error, ldap_search() will return
-1, setting the session error parameters in the LDAP structure
appropriately.
The synchronous ldap_search_ext_s(), ldap_search_s(), and ldap_
search_st() functions all 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 Errors for more
information about possible errors and how to interpret them.
Entries returned from the search (if any) are contained in the
res parameter. This parameter is opaque to the caller. Entries,
attributes, and values should be extracted by calling the parsing
functions. The results contained in res should be freed when no
longer in use by calling ldap_msgfree().
The ldap_search_ext() and ldap_search_ext_s() functions support
LDAPv3 server controls, client controls, and allow varying size
and time limits to be easily specified for each search operation.
The ldap_search_st() function is identical to ldap_search_s()
except that it takes an additional parameter specifying a local
timeout for the search. The local search timeout is used to
limit the amount of time the API implementation will wait for
a search to complete. After the local search timeout the search
operation will return LDAP_TIMEOUT if the search result has not
been removed.
9.1 – Reading and Listing the Children of an Entry
LDAP does not support a read operation directly. Instead, this
operation is emulated by a search with base set to the DN of the
entry to read, scope set to LDAP_SCOPE_BASE, and filter set to
"(objectclass=*)" or NULL. The attrs parameter contains the list
of attributes to return.
LDAP does not support a list operation directly. Instead, this
operation is emulated by a search with base set to the DN of the
entry to list, scope set to LDAP_SCOPE_ONELEVEL, and filter set
to "(objectclass=*)" or NULL. The attrs parameter contains the
list of attributes to return for each child entry.
10 – Attribute Value
The following functions are used to compare a given attribute
value assertion against an LDAP entry. There are four variations.
int ldap_compare_ext(
LDAP *ld,
const char *dn,
const char *attr,
const struct berval *bvalue
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_compare_ext_s(
LDAP *ld,
const char *dn,
const char *attr,
const struct berval *bvalue,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_compare(
LDAP *ld,
const char *dn,
const char *attr,
const char *value
);
int ldap_compare_s(
LDAP *ld,
const char *dn,
const char *attr,
const char *value
);
Parameters are as follows:
ld The session handle.
dn The name of the entry to compare against.
attr The attribute to compare against.
bvalue The attribute value to compare against those found
in the given entry. This parameter is used in the
extended functions and is a pointer to a struct
berval so it is possible to compare binary values.
value A string attribute value to compare against,
used by the ldap_compare() and ldap_compare_s()
functions. Use ldap_compare_ext() or ldap_compare_
ext_s() if you need to compare binary values.
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_compare_ext() call
succeeds.
The ldap_compare_ext() function initiates an asynchronous compare
operation and returns either the constant LDAP_SUCCESS if the
request was successfully sent, or another LDAP error code if not.
See Errors for more information about possible errors and how
to interpret them. If successful, ldap_compare_ext() places the
message id of the request in *msgidp. A subsequent call to ldap_
result() can be used to obtain the result of the compare.
Similar to ldap_compare_ext(), the ldap_compare() function
initiates an asynchronous compare operation and returns the
message id of the operation initiated. As for ldap_compare_ext(),
a subsequent call to ldap_result() can be used to obtain the
result of the compare. In case of error, ldap_compare() will
return -1, setting the session error parameters in the LDAP
structure appropriately.
The synchronous ldap_compare_ext_s() and ldap_compare_s()
functions both return the result of the operation, either
the constants LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the
operation was successful, or another LDAP error code if it was
not. See Errors for more information about possible errors and
how to interpret them.
The ldap_compare_ext() and ldap_compare_ext_s() functions
support LDAPv3 server controls and client controls.
11 – Modifying Entry
The following functions are used to modify an existing LDAP
entry. There are four variations.
typedef struct ldapmod {
int mod_op;
char *mod_type;
union {
char **modv_strvals;
struct berval **modv_bvals;
} mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals
#define mod_bvalues mod_vals.modv_bvals
int ldap_modify_ext(
LDAP *ld,
const char *dn,
LDAPMod **mods,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_modify_ext_s(
LDAP *ld,
const char *dn,
LDAPMod **mods,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_modify(
LDAP *ld,
const char *dn,
LDAPMod **mods
);
int ldap_modify_s(
LDAP *ld,
const char *dn,
LDAPMod **mods
);
Parameters are as follows:
ld The session handle.
dn The name of the entry to modify.
mods A NULL-terminated array of modifications to make
to the entry.
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_modify_ext() call
succeeds.
The fields in the LDAPMod structure have the following meanings:
mod_op The modification operation to perform. It should be
one of LDAP_MOD_ADD(0x00), LDAP_MOD_DELETE (0x01), or
LDAP_MOD_REPLACE(0x02). This field also indicates the
type of values included in the mod_vals union. It is
logically ORed with LDAP_MOD_BVALUES (0x80) to select
the mod_bvalues form. Otherwise, the mod_values form is
used.
mod_type The type of the attribute to modify.
mod_vals The values (if any) to add, delete, or replace. Only
one of the mod_values or mod_bvalues variants should
be used, selected by ORing the mod_op field with the
constant LDAP_MOD_BVALUES. The mod_values field is
a NULL-terminated array of zero-terminated strings
and mod_bvalues is a NULL- terminated array of berval
structures that can be used to pass binary values such
as images.
For LDAP_MOD_ADD modifications, the given values are added to the
entry, creating the attribute if necessary.
For LDAP_MOD_DELETE modifications, the given values are deleted
from the entry, removing the attribute if no values remain. If
the entire attribute is to be deleted, the mod_vals field should
be set to NULL.
For LDAP_MOD_REPLACE modifications, the attribute will have
the listed values after the modification, having been created
if necessary, or removed if the mod_vals field is NULL. All
modifications are performed in the order in which they are
listed.
The ldap_modify_ext() function initiates an asynchronous modify
operation and returns the constant LDAP_SUCCESS if the request
was successfully sent, or another LDAP error code if not. See
Errors for more information about possible errors and how to
interpret them. If successful, ldap_modify_ext() places the
message id of the request in *msgidp. A subsequent call to ldap_
result() can be used to obtain the result of the modify.
Similar to ldap_modify_ext(), the ldap_modify() function
initiates an asynchronous modify operation and returns the
message id of the operation initiated. As for ldap_modify_ext(),
a subsequent call to ldap_result() can be used to obtain the
result of the modify. In case of error, ldap_modify() will return
-1, setting the session error parameters in the LDAP structure
appropriately.
The synchronous ldap_modify_ext_s() and ldap_modify_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 Errors for more information about possible errors and how to
interpret them.
The ldap_modify_ext() and ldap_modify_ext_s() functions support
LDAPv3 server controls and client controls.
12 – Modifying Name
In LDAP Version 2, the ldap_modrdn() and ldap_modrdn_s()
functions were used to change the name of an LDAP entry. They
could only be used to change the least significant component of
a name (the RDN or relative distinguished name). LDAPv3 provides
the Modify DN protocol operation that allows more general name
change access. The ldap_rename() and ldap_rename_s() functions
are used to change the name of an entry, and the use of the ldap_
modrdn() and ldap_modrdn_s() functions is deprecated.
int ldap_rename(
LDAP *ld,
const char *dn,
const char *newrdn,
const char *newparent,
int deleteoldrdn,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_rename_s(
LDAP *ld,
const char *dn,
const char *newrdn,
const char *newparent,
int deleteoldrdn,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
Use of the following functions is deprecated.
int ldap_modrdn(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
int ldap_modrdn_s(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
Parameters are as follows:
ld The session handle.
dn The name of the entry whose DN is to be changed.
newrdn The new RDN to give the entry.
newparent The new parent, or superior entry. If this
parameter is NULL, only the RDN of the entry is
changed. The root DN may be specified by passing
a zero length string, "". The newparent parameter
should always be NULL when using Version 2 of the
LDAP protocol; otherwise the server's behavior is
undefined.
deleteoldrdn This parameter only has meaning on the rename
functions if newrdn is different than the old
RDN. It is a boolean value. If it is non-zero,
it indicates that the old RDN value(s) should
be removed. If it is zero, it indicates that
the old RDN value(s) should be retained as non-
distinguished values of the entry.
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_rename() call
succeeds.
The ldap_rename() function initiates an asynchronous modify DN
operation and returns the constant LDAP_SUCCESS if the request
was successfully sent, or another LDAP error code if not. See
Errors for more information about possible errors and how to
interpret them. If successful, ldap_rename() places the DN
message id of the request in *msgidp. A subsequent call to ldap_
result() can be used to obtain the result of the rename.
The synchronous ldap_rename_s() returns 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 Errors
for more information about possible errors and how to interpret
them.
The ldap_rename() and ldap_rename_s() functions both support
LDAPv3 server controls and client controls.
13 – Adding Entry
The following functions are used to add entries to the LDAP
directory. There are four variations.
int ldap_add_ext(
LDAP *ld,
const char *dn,
LDAPMod **attrs,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_add_ext_s(
LDAP *ld,
const char *dn,
LDAPMod **attrs,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_add(
LDAP *ld,
const char *dn,
LDAPMod **attrs
);
int ldap_add_s(
LDAP *ld,
const char *dn,
LDAPMod **attrs
);
Parameters are as follows:
ld The session handle.
dn The name of the entry to add.
attrs The entry's attributes, specified using the
LDAPMod structure defined for ldap_modify(). The
mod_type and mod_vals fields should be filled in.
The mod_op field is ignored unless ORed with the
constant LDAP_MOD_BVALUES, used to select the mod_
bvalues case of the mod_vals union.
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_add_ext() call
succeeds.
Note that the parent of the entry being added must already exist
or the parent must be empty (that is, equal to the root DN) for
an add to succeed.
The ldap_add_ext() function initiates an asynchronous add
operation and returns either the constant LDAP_SUCCESS if the
request was successfully sent or another LDAP error code if not.
See Errors for more information about possible errors and how to
interpret them. If successful, ldap_add_ext() places the message
id of the request in *msgidp. A subsequent call to ldap_result()
can be used to obtain the result of the add.
Similar to ldap_add_ext(), the ldap_add() function initiates
an asynchronous add operation and returns the message id of the
operation initiated. As for ldap_add_ext(), a subsequent call
to ldap_result() can be used to obtain the result of the add.
In case of error, ldap_add() will return -1, setting the session
error parameters in the LDAP structure appropriately.
The synchronous ldap_add_ext_s() and ldap_add_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 Errors for more information about
possible errors and how to interpret them.
The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3
server controls and client controls.
14 – Deleting Entry
The following functions are used to delete a leaf entry from the
LDAP directory. There are four variations.
int ldap_delete_ext(
LDAP *ld,
const char *dn,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_delete_ext_s(
LDAP *ld,
const char *dn,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_delete(
LDAP *ld,
const char *dn
);
int ldap_delete_s(
LDAP *ld,
const char *dn
);
Parameters are as follows:
ld The session handle.
dn The name of the entry to delete.
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_delete_ext() call
succeeds.
Note that the entry to delete must be a leaf entry (that is, it
must have no children). Deletion of entire subtrees in a single
operation is not supported by LDAP.
The ldap_delete_ext() function initiates an asynchronous delete
operation and returns either the constant LDAP_SUCCESS if the
request was successfully sent or another LDAP error code if not.
See Errors for more information about possible errors and how
to interpret them. If successful, ldap_delete_ext() places the
message id of the request in *msgidp. A subsequent call to ldap_
result() can be used to obtain the result of the delete.
Similar to ldap_delete_ext(), the ldap_delete() function
initiates an asynchronous delete operation and returns the
message id of the operation initiated. As for ldap_delete_ext(),
a subsequent call to ldap_result() can be used to obtain the
result of the delete. In case of error, ldap_delete() will return
-1, setting the session error parameters in the LDAP structure
appropriately.
The synchronous ldap_delete_ext_s() and ldap_delete_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 Errors for more information
about possible errors and how to interpret them.
The ldap_delete_ext() and ldap_delete_ext_s() functions support
LDAPv3 server controls and client controls.
15 – Extensions
The ldap_extended_operation() and ldap_extended_operation_s()
functions allow extended LDAP operations to be passed to the
server, providing a general protocol extensibility mechanism.
int ldap_extended_operation(
LDAP *ld,
const char *requestoid,
const struct berval *request data,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_extended_operation_s(
LDAP *ld,
const char *requestoid,
const struct berval *request data,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
char **retoidp,
struct berval **retdatap
);
Parameters are as follows:
ld The session handle.
requestoid The dotted-OID text string naming the request.
requestdata The arbitrary data required by the operation (if
NULL, no data is sent to the server).
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_extended_operation()
call succeeds.
retoidp Pointer to a character string that will be set
to an allocated, dotted- OID text string returned
by the server. This string should be disposed of
using the ldap_memfree() function. If no OID was
returned, *retoidp is set to NULL.
retdatap Pointer to a berval structure pointer that will be
set to an allocated copy of the data returned by
the server. This struct berval should be disposed
of using ber_bvfree(). If no data is returned,
*retdatap is set to NULL.
The ldap_extended_operation() function initiates an asynchronous
extended operation and returns either the constant LDAP_SUCCESS
if the request was successfully sent or another LDAP error code
if not. See Errors for more information about possible errors and
how to interpret them. If successful, ldap_extended_operation()
places the message id of the request in *msgidp. A subsequent
call to ldap_result() can be used to obtain the result of the
extended operation which can be passed to ldap_parse_extended_
result() to obtain the OID and data contained in the response.
The synchronous ldap_extended_operation_s() function returns
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 Errors for more information about possible errors
and how to interpret them. The retoid and retdata parameters are
filled in with the OID and data from the response. If no OID or
data was returned, these parameters are set to NULL.
The ldap_extended_operation() and ldap_extended_operation_
s() functions both support LDAPv3 server controls and client
controls.
16 – Abandoning
The following calls are used to abandon an operation in progress:
int ldap_abandon_ext(
LDAP *ld,
int msgid,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_abandon(
LDAP *ld,
int msgid
);
Parameters are as follows:
ld The session handle.
msgid The message id of the request to be abandoned.
serverctrls List of LDAP server controls.
clientctrls List of client controls.
The ldap_abandon_ext() function abandons the operation with
message id msgid and returns either the constant LDAP_SUCCESS
if the abandon was successful or another LDAP error code if not.
See Errors for more information about possible errors and how to
interpret them.
The ldap_abandon() function is identical to ldap_abandon_ext()
except that it does not accept client or server controls and it
returns zero if the abandon was successful, -1 otherwise and does
not support LDAPv3 server controls or client controls.
After a successful call to ldap_abandon() or ldap_abandon_ext(),
results with the given message id are never returned from a
subsequent call to ldap_result(). There is no server response
to LDAP abandon operations.
17 – Results
The ldap_result() function is used to obtain the result of a
previous asynchronously initiated operation. Note that depending
on how it is called, ldap_result() may actually return a list or
"chain" of result messages. Once a chain of messages has been
returned to the caller, it is no longer tied in any caller-
visible way to the LDAP request that produced it. Therefore,
a chain of messages returned by calling ldap_result() or by
calling a synchronous search function will never be affected
by subsequent LDAP API calls (except for ldap_msgfree(), which is
used to dispose of a chain of messages).
The ldap_msgfree() function frees the result messages (possibly
an entire chain of messages) obtained from a previous call to
ldap_result() or from a call to a synchronous search function.
The ldap_msgtype() function returns the type of an LDAP message.
The ldap_msgid() function returns the message ID of an LDAP
message.
int ldap_result(
LDAP *ld,
int msgid,
int all,
struct timeval *timeout,
LDAPMessage **res
);
int ldap_msgfree( LDAPMessage *res );
int ldap_msgtype( LDAPMessage *res );
int ldap_msgid( LDAPMessage *res );
Parameters are as follows:
ld The session handle.
msgid The message id of the operation whose results are
to be returned, or the constant LDAP_RES_ANY (-1)
if any result is desired.
all Specifies how many messages will be retrieved in
a single call to ldap_result(). This parameter
only has meaning for search results. Pass the
constant LDAP_MSG_ONE (0x00) to retrieve one
message at a time. Pass LDAP_MSG_ALL (0x01) to
request that all results of a search be received
before returning all results in a single chain.
Pass LDAP_MSG_RECEIVED (0x02) to indicate that all
results retrieved so far should be returned in the
result chain.
timeout A timeout specifying how long to wait for results
to be returned. A NULL value causes ldap_result()
to block until results are available. A timeout
value of zero seconds specifies a polling
behavior.
res For ldap_result(), a result parameter that will
contain the result(s) of the operation. For ldap_
msgfree(), the result chain to be freed, obtained
from a previous call to ldap_result(), ldap_
search_s(), or ldap_search_st().
Upon successful completion, ldap_result() returns the type of the
first result returned in the res parameter. This will be one of
the following constants.
LDAP_RES_BIND (0x61)
LDAP_RES_SEARCH_ENTRY (0x64)
LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3
LDAP_RES_SEARCH_RESULT (0x65)
LDAP_RES_MODIFY (0x67)
LDAP_RES_ADD (0x69)
LDAP_RES_DELETE (0x6B)
LDAP_RES_MODDN (0x6D)
LDAP_RES_COMPARE (0x6F)
LDAP_RES_EXTENDED (0x78) -- new in LDAPv3
The ldap_result() function returns 0 if the timeout expired and
-1 if an error occurs, in which case the error parameters of the
LDAP session handle will be set accordingly.
The ldap_msgfree() function frees the result structure pointed to
by res and returns the type of the message it freed.
The ldap_msgtype() function returns the type of the LDAP message
it is passed as a parameter. The type will be one of the types
listed above, or -1 on error.
The ldap_msgid() function returns the message ID associated with
the LDAP message passed as a parameter.
18 – Errors
The following calls are used to extract information from results
and handle errors returned by other LDAP API functions. Note that
ldap_parse_sasl_bind_result() and ldap_parse_extended_result()
must typically be used in addition to ldap_parse_result() to
retrieve all the result information from SASL bind and extended
operations, respectively.
int ldap_parse_result(
LDAP *ld,
LDAPMessage *res,
int *errcodep,
char **matcheddnp,
char **errmsgp,
char ***referralsp,
LDAPControl ***serverctrlsp,
int freeit
);
int ldap_parse_sasl_bind_result(
LDAP *ld,
LDAPMessage *res,
struct berval **servercredp,
int freeit
);
int ldap_parse_extended_result(
LDAP *ld,
LDAPMessage *res,
char **resultoidp,
struct berval **resultdata,
int freeit
);
char *ldap_err2string( int err );
The use of the following functions is deprecated.
int ldap_result2error(
LDAP *ld,
LDAPMessage *res,
int freeit
);
void ldap_perror( LDAP *ld, const char *msg );
Parameters are as follows:
ld The session handle.
res The result of an LDAP operation as returned by
ldap_result() or one of the synchronous API
operation calls.
errcodep This result parameter will be filled in with the
LDAP error code field from the LDAPMessage result.
This is the indication from the server of the
outcome of the operation. NULL may be passed to
ignore this field.
matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT,
this result parameter will be filled in with a
DN indicating how much of the name in the request
was recognized. NULL may be passed to ignore this
field. The matched DN string should be freed by
calling ldap_memfree().
errmsgp This result parameter will be filled in with the
contents of the error message field from the
LDAPMessage result. The error message string
should be freed by calling ldap_memfree(). NULL
may be passed to ignore this field.
referralsp This result parameter will be filled in with
the contents of the referrals field from the
LDAPMessage result, indicating zero or more
alternate LDAP servers where the request should
be retried. The referrals array should be freed by
calling ldap_value_free(). NULL may be passed to
ignore this field.
serverctrlsp This result parameter will be filled in with an
allocated array of controls copied out of the
LDAPMessage result. The control array should be
freed by calling ldap_controls_free().
freeit A boolean that determines whether or not the res
parameter is disposed of. Pass any non-zero value
to have these functions free res after extracting
the requested information. This option is provided
as a convenience; you can also use ldap_msgfree()
to free the result later. If freeit is non-zero,
the entire chain of messages represented by res is
disposed of.
servercredp For SASL bind results, 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.
resultoidp For extended results, this result parameter
will be filled in with the dotted-OID text
representation of the name of the extended
operation response. This string should be disposed
of by calling ldap_memfree(). NULL may be passed
to ignore this field.
resultdatap For extended results, this result parameter will
be filled in with a pointer to a struct berval
containing the data in the extended operation
response. It should be disposed of by calling ber_
bvfree(). NULL may be passed to ignore this field.
err For ldap_err2string(), an LDAP error code, as
returned by ldap_parse_result() or another LDAP
API call.
Additional parameters for the deprecated functions are not
described. See RFC 1823 for more information.
All three of the ldap_parse_*_result() functions skip over
messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_
REFERENCE when looking for a result message to parse. They return
either the constant LDAP_SUCCESS if the result was successfully
parsed or another LDAP error code if not. Note that the LDAP
error code that indicates the outcome of the operation performed
by the server is placed in the errcodep ldap_parse_result()
parameter. If a chain of messages that contains more than one
result message is passed to these functions, they always operate
on the first result in the chain.
The ldap_err2string() function is used to convert a numeric LDAP
error code, as returned by either one of the three ldap_parse_*_
result() functions or one of the synchronous API operation calls,
into an informative zero-terminated character string message
describing the error. It returns a pointer to static data.
18.1 – Stepping Through a List of Results
The ldap_first_message() and ldap_next_message() functions are
used to step through the list of messages in a result chain
returned by ldap_result(). For search operations, the result
chain may actually include referral messages, entry messages,
and result messages. The ldap_count_messages() function is used
to count the number of messages returned. The ldap_msgtype()
function can be used to distinguish between the different message
types.
LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
LDAPMessage *ldap_next_message ( LDAP *ld, LDAPMesage *msg );
int ldap_count_messages( LDAP *ld, LDAPMessage *res );
Parameters are as follows:
ld The session handle.
res The result chain, as obtained by a call to one of the
synchronous search functions or ldap_result().
msg The message returned by a previous call to ldap_first_
message() or ldap_next_message().
The ldap_first_message() and ldap_next_message() functions will
return NULL when no more messages exist in the result set to be
returned. NULL is also returned if an error occurs while stepping
through the entries, in which case the error parameters in the
session handle ld will be set to indicate the error.
The ldap_count_messages() function returns the number of messages
contained in a chain of results. It can also be used to count
the number of messages that remain in a chain if called with a
message, entry, or reference returned by ldap_first_message(),
ldap_next_message(), ldap_first_entry(), ldap_next_entry(),
ldap_first_reference(), ldap_next_reference().
19 – Search Results
The following calls are used to parse the entries and references
returned by ldap_search(). These results are returned in an
opaque structure that should only be accessed by calling the
functions. Functions are provided to step through the entries
and references returned, step through the attributes of an entry,
retrieve the name of an entry, and retrieve the values associated
with a given attribute in an entry.
19.1 – Stepping Through a List of Entries
The ldap_first_entry() and ldap_next_entry() functions are
used to step through and retrieve the list of entries from a
search result chain. The ldap_first_reference() and ldap_next_
reference() functions are used to step through and retrieve the
list of continuation references from a search result chain. The
ldap_count_entries() function is used to count the number of
entries returned. The ldap_count_references() function is used to
count the number of references returned.
LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
int ldap_count_entries( LDAP *ld, LDAPMessage *res );
int ldap_count_references( LDAP *ld, LDAPMessage *res );
Parameters are as follows:
ld The session handle.
res The search result, as obtained by a call to one of the
synchronous search functions or ldap_result().
entry The entry returned by a previous call to ldap_first_
entry() or ldap_next_entry().
The ldap_first_entry() and ldap_next_entry() functions will
return NULL when no more entries or references exist in the
result set to be returned. NULL is also returned if an error
occurs while stepping through the entries, in which case the
error parameters in the session handle ld will be set to indicate
the error.
The ldap_count_entries() function returns the number of entries
contained in a chain of entries. It can also be used to count
the number of entries that remain in a chain if called with a
message, entry or reference returned by ldap_first_message(),
ldap_next_message(), ldap_first_entry(), ldap_next_entry(),
ldap_first_reference(), ldap_next_reference().
The ldap_count_references() function returns the number of
references contained in a chain of search results. It can also be
used to count the number of references that remain in a chain.
19.2 – Stepping Through the Attributes of an Entry
The ldap_first_attribute() and ldap_next_attribute() calls are
used to step through the list of attribute types returned with an
entry.
char *ldap_first_attribute(
LDAP *ld,
LDAPMessage *entry,
BerElement **ptr
);
char *ldap_next_attribute(
LDAP *ld,
LDAPMessage *entry,
BerElement *ptr
);
void ldap_memfree( char *mem );
Parameters are as follows:
ld The session handle.
entry The entry whose attributes are to be stepped through, as
returned by ldap_first_entry() or ldap_next_entry().
ptr In ldap_first_attribute(), the address of a pointer used
internally to keep track of the current position in the
entry. In ldap_next_attribute(), the pointer returned by a
previous call to ldap_first_attribute().
mem A pointer to memory allocated by the LDAP library, such
as the attribute type names returned by ldap_first_
attribute() and ldap_next_attribute(), or the DN returned
by ldap_get_dn().
The ldap_first_attribute() and ldap_next_attribute() functions
will return NULL when the end of the attributes is reached, or
if there is an error, in which case the error parameters in the
session handle ld will be set to indicate the error.
Both functions return a pointer to an allocated buffer containing
the current attribute name. This should be freed when no longer
in use by calling ldap_memfree().
The ldap_first_attribute() function will allocate and return in
ptr a pointer to a BerElement used to keep track of the current
position. This pointer should be passed in subsequent calls to
ldap_next_attribute() to step through the entry's attributes.
After a set of calls to ldap_first_attribute() and ldap_next_
attribute(), if ptr is non-NULL, it should be freed by calling
ber_free(ptr, 0). Note that it is very important to pass the
second parameter as 0 (zero) in this call, since the buffer
associated with the BerElement does not point to separately
allocated memory.
The attribute type names returned are suitable for passing in a
call to ldap_get_values() to retrieve the associated values.
19.3 – Retrieving the Values of an Attribute
The ldap_get_values() and ldap_get_values_len() functions are
used to retrieve the values of a given attribute from an entry.
The ldap_count_values() and ldap_count_values_len() functions
are used to count the returned values. The ldap_value_free() and
ldap_value_free_len() functions are used to free the values.
char **ldap_get_values(
LDAP *ld,
LDAPMessage *entry,
char *attr
);
struct berval **ldap_get_values_len(
LDAP *ld,
LDAPMessage *entry,
char *attr
);
int ldap_count_values( char **vals )
int ldap_count_values_len( struct berval **vals );
void ldap_value_free( char **vals );
void ldap_value_free_len( struct berval **vals );
Parameters are as follows:
ld The session handle.
entry The entry from which to retrieve values, as returned by
ldap_first_entry() or ldap_next_entry().
attr The attribute whose values are to be retrieved, as returned
by ldap_first_attribute() or ldap_next_attribute(), or a
caller- supplied string (for example, "mail").
vals The values returned by a previous call to ldap_get_
values() or ldap_get_values_len().
Two forms of the various calls are provided. The first form is
only suitable for use with non-binary character string data. The
second _len form is used with any kind of data.
The ldap_get_values() and ldap_get_values_len() functions return
NULL if no values are found for attr or if an error occurs.
The ldap_count_values() and ldap_count_values_len() functions
return -1 if an error occurs such as the vals parameter being
invalid.
Note that the values returned are dynamically allocated and
should be freed by calling either ldap_value_free() or ldap_
value_free_len() when no longer in use.
19.4 – Retrieving the Name of an Entry
The ldap_get_dn() function is used to retrieve the name of an
entry. The ldap_explode_dn() and ldap_explode_rdn() functions
are used to break up a name into its component parts. The ldap_
dn2ufn() function is used to convert the name into a more user-
friendly format.
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
char **ldap_explode_dn( const char *dn, int notypes );
char **ldap_explode_rdn( const char *rdn, int notypes );
char *ldap_dn2ufn( const char *dn );
Parameters are as follows:
ld The session handle.
entry The entry whose name is to be retrieved, as returned by
ldap_first_entry() or ldap_next_entry().
dn The dn to explode, such as returned by ldap_get_dn().
rdn The rdn to explode, such as returned in the components
of the array returned by ldap_explode_dn().
notypes A boolean parameter, if non-zero indicating that the DN
or RDN components should have their type information
stripped off (i.e., "cn=Babs" would become "Babs").
The ldap_get_dn() function will return NULL if there is some
error parsing the dn, setting error parameters in the session
handle ld to indicate the error. It returns a pointer to newly
allocated space that the caller should free by calling ldap_
memfree() when it is no longer in use.
The ldap_explode_dn() function returns a NULL-terminated char
* array containing the RDN components of the DN supplied, with
or without types as indicated by the notypes parameter. The
components are returned in the order they appear in the dn. The
array returned should be freed when it is no longer in use by
calling ldap_value_free().
The ldap_explode_rdn() function returns a NULL-terminated char
* array containing the components of the RDN supplied, with
or without types as indicated by the notypes parameter. The
components are returned in the order they appear in the rdn.
The array returned should be freed when it is no longer in use by
calling ldap_value_free().
The ldap_dn2ufn() function converts the DN into the user friendly
format. The UFN returned is newly allocated space that should be
freed by a call to ldap_memfree() when no longer in use.
19.5 – Retrieving Controls from an Entry
The ldap_get_entry_controls() function is used to extract LDAP
controls from an entry.
int ldap_get_entry_controls(
LDAP *ld,
LDAPMessage *entry,
LDAPControl ***serverctrlsp
);
Parameters are as follows:
ld The session handle.
entry The entry to extract controls from, as returned by
ldap_first_entry() or ldap_next_entry().
serverctrlsp This result parameter will be filled in with an
allocated array of controls copied out of entry.
The control array should be freed by calling
ldap_controls_free(). If serverctrlsp is NULL,
no controls are returned.
The ldap_get_entry_controls() function returns an LDAP error code
that indicates whether the reference could be successfully parsed
(LDAP_SUCCESS if all goes well).
19.6 – Parsing References
The ldap_parse_reference() function is used to extract referrals
and controls from a SearchResultReference message.
int ldap_parse_reference(
LDAP *ld,
LDAPMessage *ref,
char ***referralsp,
LDAPControl ***serverctrlsp,
int freeit
);
Parameters are as follows:
ld The session handle.
ref The reference to parse, as returned by ldap_
result(), ldap_first_reference(), or ldap_next_
reference().
referralsp This result parameter will be filled in with an
allocated array of character strings. The elements
of the array are the referrals (typically LDAP
URLs) contained in ref. The array should be freed
when no longer in used by calling ldap_value_
free(). If referralsp is NULL, the referral URLs
are not returned.
serverctrlsp This result parameter will be filled in with an
allocated array of controls copied out of ref.
The control array should be freed by calling
ldap_controls_free(). If serverctrlsp is NULL,
no controls are returned.
freeit A boolean that determines whether or not the ref
parameter is disposed of. Pass any non-zero value
to have these functions free ref after extracting
the requested information. This option is provided
as a convenience; you can also use ldap_msgfree()
to free the result later.
The ldap_parse_reference() function returns an LDAP error code
that indicates whether the reference could be successfully parsed
(LDAP_SUCCESS if all goes well).
20 – Encoded ASN.1
LDAP contains functions that may be used to encode and decode
BER-encoded ASN.1 values, which are often used inside of control
and extension values.
The following additional integral types are defined for use in
manipulation of BER encoded ASN.1 values:
typedef unsigned long ber_tag_t; /* for BER tags */
typedef long ber_int_t; /* for BER ints, enums, and Booleans */
With the exceptions of two new functions, ber_flatten() and ber_
init(), these functions are compatible with the University of
Michigan LDAP 3.3 implementation of BER.
typedef struct berval {
ber_len_t bv_len;
char *bv_val;
} BerValue;
A struct berval contains a sequence of bytes and an indication
of its length. The bv_val is not null terminated. A bv_len must
always be a nonnegative number. Applications may allocate their
own berval structures.
typedef struct berelement {
/* opaque */
} BerElement;
The BerElement structure contains not only a copy of the encoded
value, but also state information used in encoding or decoding.
Applications cannot allocate their own BerElement structures.
The internal state is neither thread-specific nor locked, so
two threads should not manipulate the same BerElement value
simultaneously.
A single BerElement value cannot be used for both encoding and
decoding.
void ber_bvfree( struct berval *bv );
The ber_bvfree() function frees a berval returned from this
API. Both the bv->bv_val string and the berval itself are freed.
Applications should not use ber_bvfree() with bervals which the
application has allocated.
void ber_bvecfree ( struct berval **bv );
The ber_bvecfree() function frees an array of bervals returned
from this API. Each of the bervals in the array are freed using
ber_bvfree(), then the array itself is freed.
struct berval *ber_bvdup (struct berval *bv );
The ber_bvdup() function returns a copy of a berval. The bv_val
field in the returned berval points to a different area of memory
as the bv_val field in the argument berval. The null pointer is
returned on error (for example, out of memory).
void ber_free ( BerElement *ber, int fbuf );
The ber_free() function frees a BerElement which is returned from
the API calls ber_alloc_t() or ber_init(). Each BerElement must
be freed by the caller. The second argument fbuf should always
be set to 1 to ensure that the internal buffer used by the BER
functions is freed as well as the BerElement container itself.
20.1 – Encoding
The following is an example of encoding:
BerElement *ber_alloc_t(int options);
The ber_alloc_t() function constructs and returns BerElement.
The null pointer is returned on error. The options field contains
a bitwise-or of options which are to be used when generating
the encoding of this BerElement. One option is defined and must
always be supplied:
#define LBER_USE_DER 0x01
When this option is present, lengths will always be encoded
in the minimum number of octets. Note that this option does
not cause values of sets and sequences to be rearranged in
tag and byte order, so these functions are not sufficient for
generating DER output as defined in X.509 and X.680. If the
caller takes responsibility for ordering values of sets and
sequences correctly, DER output as defined in X.509 and X.680
can be produced.
Unrecognized option bits are ignored.
The BerElement returned by ber_alloc_t() is initially empty.
Calls to ber_printf() will append bytes to the end of the
BerElement.
int ber_printf(BerElement *ber, char *fmt, ... )
The ber_printf() function is used to encode a BER element in
much the same way that sprintf() works. One important difference,
though, is that state information is kept in the BER argument so
that multiple calls can be made to ber_printf() to append to the
end of the BER element. BER must be a pointer to a BerElement
returned by ber_alloc_t(). The ber_printf() function interprets
and formats its arguments according to the format string fmt.
The ber_printf() function returns -1 if there is an error during
encoding and a positive number if successful. As with sprintf(),
each character in fmt refers to an argument to ber_printf().
The format string can contain the following format characters:
t Tag. The next argument is a ber_tag_t specifying the tag
to override the next element to be written to the ber. This
works across calls. The value must contain the tag class,
constructed bit, and tag value. The tag value must fit in
a single octet (tag value is less than 32). For example, a
tag of "[3]" for a constructed type is 0xA3.
b Boolean. The next argument is a ber_int_t, containing
either 0 for FALSE or 0xff for TRUE. A boolean element
is output. If this format character is not preceded by the
't' format modifier, the tag 0x01 is used for the element.
e Enumerated. The next argument is a ber_int_t, containing
the enumerated value in the host's byte order. An
enumerated element is output. If this format character
is not preceded by the 't' format modifier, the tag 0x0A is
used for the element.
i Integer. The next argument is a ber_int_t, containing the
integer in the host's byte order. An integer element is
output. If this format character is not preceded by the 't'
format modifier, the tag 0x02 is used for the element.
B Bitstring. The next two arguments are a char * pointer
to the start of the bitstring, followed by a ber_len_t
containing the number of bits in the bitstring. A bitstring
element is output, in primitive form. If this format
character is not preceded by the 't' format modifier, the
tag 0x03 is used for the element.
n Null. No argument is required. An ASN.1 NULL element is
output. If this format character is not preceded by the 't'
format modifier, the tag 0x05 is used for the element.
o Octet string. The next two arguments are a char *, followed
by a ber_len_t with the length of the string. The string
may contain null bytes and need not by zero-terminated.
An octet string element is output, in primitive form. If
this format character is not preceded by the 't' format
modifier, the tag 0x04 is used for the element.
s Octet string. The next argument is a char * pointing
to a zero-terminated string. An octet string element
in primitive form is output, which does not include
the trailing '\0' byte. If this format character is not
preceded by the 't' format modifier, the tag 0x04 is used
for the element.
v Several octet strings. The next argument is a char **,
an array of char * pointers to zero-terminated strings.
The last element in the array must be a null pointer. The
octet strings do not include the leading SEQUENCE OF octet
strings. The 't' format modifier cannot be used with this
format character.
V Several octet strings. A NULL-terminated array of struct
berval *'s is supplied. Note that a construct like '{V}'
is required to get an actual SEQUENCE OF octet strings.
The 't' format modifier cannot be used with this format
character.
{ Begin sequence. No argument is required. If this format
character is not preceded by the 't' format modifier, the
tag 0x30 is used.
} End sequence. No argument is required. The 't' format
modifier cannot be used with this format character.
[ Begin set. No argument is required. If this format
character is not preceded by the 't' format modifier, the
tag 0x31 is used.
] End set. No argument is required. The 't' format modifier
cannot be used with this format character.
Each use of a '{' format character must be matched by a '}'
character, either later in the format string, or in the format
string of a subsequent call to ber_printf() for that BerElement.
The same applies to the '[' and ']'.
Sequences and sets nest, and implementations of this API must
maintain internal state to be able to properly calculate the
lengths.
int ber_flatten (BerElement *ber, struct berval **bvPtr);
The ber_flatten() function allocates a struct berval whose
contents are a BER encoding taken from the ber argument. The
bvPtr pointer points to the returned berval, which must be freed
using ber_bvfree(). This function returns 0 on success and -1 on
error.
The ber_flatten() API call is not present in U-M LDAP 3.3.
The use of ber_flatten() on a BerElement in which all '{' and '}'
format modifiers have not been properly matched is an error (that
is, -1 will be returned by ber_flatten() if this situation is
exists).
20.2 – Decoding
The following two symbols are available to applications.
#define LBER_ERROR 0xffffffffL
#define LBER_DEFAULT 0xffffffffL
BerElement *ber_init (struct berval *bv);
The ber_init() function constructs a BerElement and returns a new
BerElement containing a copy of the data in the bv argument. The
ber_init() function returns the null pointer on error.
ber_tag_t ber_scanf (BerElement *ber, char *fmt, ... );
The ber_scanf() function is used to decode a BER element in much
the same way that sscanf() works. One important difference,
though, is that some state information is kept with the ber
argument so that multiple calls can be made to ber_scanf() to
sequentially read from the BER element. The ber argument must
be a pointer to a BerElement returned by ber_init(). The ber_
scanf() function interprets function the bytes according to
the format string fmt, and stores the results in its additional
arguments. The ber_scanf() function returns LBER_ERROR on error,
and a different value on success.
The format string contains conversion specifications which are
used to direct the interpretation of the BER element. The format
string can contain the following characters:
a Octet string. A char ** argument should be supplied. Memory
is allocated, filled with the contents of the octet string,
null- terminated, and the pointer to the string is stored
in the argument. The returned value must be freed using
ldap_memfree(). The tag of the element must indicate the
primitive form (constructed strings are not supported) but
is otherwise ignored and discarded during the decoding.
This format cannot be used with octet strings which could
contain null bytes.
O Octet string. A struct berval ** argument should be
supplied, which upon return points to a allocated struct
berval containing the octet string and its length. The
ber_bvfree() function must be called to free the allocated
memory. The tag of the element must indicate the primitive
form (constructed strings are not supported) but is
otherwise ignored during the decoding.
b Boolean. A pointer to a ber_int_t should be supplied. The
value stored will be 0 for FALSE or nonzero for TRUE. The
tag of the element must indicate the primitive form but is
otherwise ignored during the decoding.
e Enumerated value stored will be in host byte order. The
tag of the element must indicate the primitive form but is
otherwise ignored during the decoding. The ber_scanf()
function will return an error if the enumerated value
cannot be stored in a ber_int_t.
i Integer. A pointer to a ber_int_t should be supplied. The
value stored will be in host byte order. The tag of the
element must indicate the primitive form but is otherwise
ignored during the decoding. The ber_scanf() function will
return an error if the integer cannot be stored in a ber_
int_t.
B Bitstring. A char ** argument should be supplied which
will point to the allocated bits, followed by a ber_len_t *
argument, which will point to the length (in bits) of the
bit-string returned. The ldap_memfree() function must be
called to free the bit-string. The tag of the element must
indicate the primitive form (constructed bitstrings are not
supported) but is otherwise ignored during the decoding.
n Null. No argument is required. The element is simply
skipped if it is recognized as a zero-length element. The
tag is ignored.
v Several octet strings. A char *** argument should be
supplied, which upon return points to a allocated null-
terminated array of char *'s containing the octet strings.
NULL is stored if the sequence is empty. The ldap_
memfree() function must be called to free each element
of the array and the array itself. The tag of the sequence
and of the octet strings are ignored.
V Several octet strings (which could contain null bytes).
A struct berval *** should be supplied, which upon
return points to a allocated null-terminated array of
struct berval *'s containing the octet strings and their
lengths. NULL is stored if the sequence is empty. The ber_
bvecfree() function can be called to free the allocated
memory. The tag of the sequence and of the octet strings
are ignored.
x Skip element. The next element is skipped. No argument is
required.
{ Begin sequence. No argument is required. The initial
sequence tag and length are skipped.
} End sequence. No argument is required.
[ Begin set. No argument is required. The initial set tag and
length are skipped.
] End set. No argument is required.
ber_tag_t ber_peek_tag (BerElement *ber, ber_len_t *lenPtr);
The ber_peek_tag() function returns the tag of the next element
to be parsed in the BerElement argument. The length of this
element is stored in the *lenPtr argument. LBER_DEFAULT is
returned if there is no further data to be read. The ber argument
is not modified.
ber_tag_t ber_skip_tag (BerElement *ber, ber_len_t *lenPtr);
The ber_skip_tag() function is similar to ber_peek_tag(), except
that the state pointer in the BerElement argument is advanced
past the first tag and length, and is pointed to the value part
of the next element. This function should only be used with
constructed types and situations when a BER encoding is used as
the value of an OCTET STRING. The length of the value is stored
in *lenPtr.
ber_tag_t ber_first_element(BerElement *ber,
ber_len_t *lenPtr, char **opaquePtr);
ber_tag_t ber_next_element (BerElement *ber,
ber_len_t *lenPtr, char *opaque);
The ber_first_element() and ber_next_element() functions are
used to traverse a SET, SET OF, SEQUENCE or SEQUENCE OF data
value. The ber_first_element() function calls ber_skip_tag(),
stores internal information in *lenPtr and *opaquePtr, and calls
ber_peek_tag() for the first element inside the constructed
value. LBER_DEFAULT is returned if the constructed value is
empty. The ber_next_element() function positions the state at the
start of the next element in the constructed type. LBER_DEFAULT
is returned if there are no further values.
The len and opaque values should not be used by applications
other than as arguments to ber_next_element(). (Refer to the VSI
OpenVMS Utility Routines Manual for an example of this usage.)
21 – Using SSL
Secure Sockets Layer (SSL) is the open standard security protocol
for the secure transfer of sensitive information over the
Internet.
You can establish SSL on an LDAP session if the server supports
such sessions. SSL uses X.509 public key technology to provide
the following security functions:
o Integrity and confidentiality of the LDAP dialog
This is the most common use of SSL. The bytes sent over the
wire are encrypted.
o Authentication of the client
Some servers use SSL to authenticate the client and make
access control decisions based on the client identity. In
this case, the client must have access to its private key and
its certificate. The client certificate subject is a DN.
o Authentication of the server
It might be important for the client to verify the identity
of the server to which it is talking. In this case, the client
must have access to the appropriate certification authority
(CA) public keys.
There are several versions of SSL: SSLv2 (2.0), SSLv3 (3.0), and
TLSv1 (3.1). TLS is the latest Internet standard. It does not
require the use of RSA algorithms. Usually the client specifies
the highest version it supports, and the server negotiates
downward, if necessary. The client library supports all the
versions listed here.
You can establish SSL over LDAP two different ways:
o LDAPS
This older, de facto standard uses a separate TCP/IP port
(usually 636) specifically for SSL over LDAP. In this case,
the second parameter to the ldap_tls_start() function must be
set to zero.
o StartTLS
This proposed Internet standard uses a regular LDAP port
(usually 389) and requires the client to request the use
of SSL. In this case, the second parameter to the ldap_tls_
start() function must be set to 1.
21.1 – SSL Certificate Options
The following session-handle options are specific to SSL and can
be set by the ldap_set_option() function:
o LDAP_OPT_TLS_CERT_REQUIRED (0x7001) void *
Set to LDAP_OPT_ON if the client library requires a server
certificate to be present the next time the ldap_tls_start()
function is called. The default value is LDAP_OPT_OFF; a
server certificate is not required.
o LDAP_OPT_TLS_VERIFY_REQUIRED (0x7002) void *
Set to LDAP_OPT_ON if the client library requires that a
server certificate path be validated the next time the ldap_
tls_start() function is called. The default value is LDAP_OPT_
OFF; the server certificate, if any, is not verified.
o LDAP_OPT_TLS_CERT_FILE (0x7003) char *
Set to the name of a file containing the client's certificate
for use by the ldap_tls_start() function.
o LDAP_OPT_TLS_PKEY_FILE (0x7004) char *
Set to the name of a file containing the client's private key
for use by the ldap_tls_start() function.
o LDAP_OPT_TLS_CA_FILE (0x7005) char *
Set to the name of a file containing CA public keys used for
validation of the server by the ldap_tls_start() function.
o LDAP_OPT_TLS_CA_PATH (0x7006) char *
Set to the name of a directory on disk containing CA public
key files used for validation of the server by the ldap_tls_
start() function.
o LDAP_OPT_TLS_VERSION (0x7007) int *
Set to the desired SSL protocol version. This option takes one
of the following values:
1: TLSv1 only
20: SSLv2 only
23: SSLv2 or SSLv3
30: SSLv3 only (default)
31: TLSv1 only
If LDAP_OPT_TLS_VERIFY_REQUIRED is set to ON, either the LDAP_
OPT_TLS_CA_FILE or the LDAP_OPT_TLS_CA_PATH option must be set.
If client authentication is required, both LDAP_OPT_TLS_CERT_FILE
and LDAP_OPT_TLS_PKEY_FILE must be set.
21.2 – Obtaining a Key Pair
In order for TLS to authenticate a client, the client must have
a private key and a certificate. Obtain these from either a
Certification Authority or a self-sign program. A self-sign
program is included in the Open Source Security for OpenVMS
product.