pkg://openldap2.3-doc-2.3.41-2mdv2008.1.i586.rpm:966057/
usr/
share/
doc/
openldap2.3-doc/
drafts/draft-ietf-ldapext-ldap-c-api-xx.txt
info downloads
Network Working Group M. Smith, Editor
INTERNET-DRAFT Netscape Communications Corp.
Intended Category: Standards Track T. Howes
Obsoletes: RFC 1823 Loudcloud, Inc.
Expires: May 2001 A. Herron
Microsoft Corp.
M. Wahl
Sun Microsystems, Inc.
A. Anantha
Microsoft Corp.
17 November 2000
The C LDAP Application Program Interface
<draft-ietf-ldapext-ldap-c-api-05.txt>
1. Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and its
working groups. Note that other groups may also distribute working
documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This draft document will be submitted to the RFC Editor as a Standards
Track document. Distribution of this memo is unlimited. Technical dis-
cussion of this document will take place on the IETF LDAP Extension
Working Group mailing list <ietf-ldapext@netscape.com>. Please send
editorial comments directly to the authors.
Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
Please see the Copyright section near the end of this document for more
information.
Expires: May 2001 [Page 1]
C LDAP API C LDAP Application Program Interface 17 November 2000
2. Introduction
This document defines a C language application program interface (API)
to the Lightweight Directory Access Protocol (LDAP). This document
replaces the previous definition of this API, defined in RFC 1823,
updating it to include support for features found in version 3 of the
LDAP protocol. New extended operation functions were added to support
LDAPv3 features such as controls. In addition, other LDAP API changes
were made to support information hiding and thread safety.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119[1].
The C LDAP API is designed to be powerful, yet simple to use. It defines
compatible synchronous and asynchronous interfaces to LDAP to suit a
wide variety of applications. This document gives a brief overview of
the LDAP model, then an overview of how the API is used by an applica-
tion program to obtain LDAP information. The API calls are described in
detail, followed by appendices that provide example code demonstrating
use of the API, the namespace consumed by the API, a summary of require-
ments for API extensions, known incompatibilities with RFC 1823, and a
list of changes made since the last revision of this document.
3. Table of Contents
1. Status of this Memo............................................1
2. Introduction...................................................2
3. Table of Contents..............................................2
4. Overview of the LDAP Model.....................................4
5. Overview of LDAP API Use and General Requirements..............4
6. Header Requirements............................................6
7. Common Data Structures and Types...............................7
8. Memory Handling Overview.......................................9
9. Retrieving Information About the API Implementation............9
9.1. Retrieving Information at Compile Time......................10
9.2. Retrieving Information During Execution.....................11
10. Result Codes...................................................14
11. Performing LDAP Operations.....................................16
11.1. Initializing an LDAP Session................................16
11.2. LDAP Session Handle Options.................................17
11.3. Working With Controls.......................................23
11.3.1. A Client Control That Governs Referral Processing........24
11.4. Authenticating to the directory.............................25
11.5. Closing the session.........................................27
11.6. Searching...................................................28
11.7. Reading an Entry............................................32
Expires: May 2001 [Page 2]
C LDAP API C LDAP Application Program Interface 17 November 2000
11.8. Listing the Children of an Entry............................32
11.9. Comparing a Value Against an Entry..........................33
11.10. Modifying an entry..........................................35
11.11. Modifying the Name of an Entry..............................37
11.12. Adding an entry.............................................39
11.13. Deleting an entry...........................................41
11.14. Extended Operations.........................................43
12. Abandoning An Operation........................................44
13. Obtaining Results and Peeking Inside LDAP Messages.............45
14. Handling Errors and Parsing Results............................47
15. Stepping Through a List of Results.............................51
16. Parsing Search Results.........................................51
16.1. Stepping Through a List of Entries or References............52
16.2. Stepping Through the Attributes of an Entry.................53
16.3. Retrieving the Values of an Attribute.......................54
16.4. Retrieving the name of an entry.............................55
16.5. Retrieving controls from an entry...........................56
16.6. Parsing References..........................................57
17. Encoded ASN.1 Value Manipulation...............................58
17.1. BER Data Structures and Types...............................58
17.2. Memory Disposal and Utility Functions.......................60
17.3. Encoding....................................................60
17.4. Encoding Example............................................63
17.5. Decoding....................................................64
17.6. Decoding Example............................................67
18. Security Considerations........................................70
19. Acknowledgements...............................................70
20. Copyright......................................................70
21. Bibliography...................................................71
22. Authors' Addresses.............................................72
23. Appendix A - Sample C LDAP API Code............................73
24. Appendix B - Namespace Consumed By This Specification..........74
25. Appendix C - Summary of Requirements for API Extensions........75
25.1. Compatibility...............................................75
25.2. Style.......................................................75
25.3. Dependence on Externally Defined Types......................75
25.4. Compile Time Information....................................76
25.5. Runtime Information.........................................76
25.6. Values Used for Session Handle Options......................76
26. Appendix D - Known Incompatibilities with RFC 1823.............76
26.1. Opaque LDAP Structure.......................................76
26.2. Additional Result Codes.....................................77
26.3. Freeing of String Data with ldap_memfree()..................77
26.4. Changes to ldap_result()....................................77
26.5. Changes to ldap_first_attribute() and ldap_next_attribute...77
26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......78
26.7. Changes to the berval structure.............................78
26.8. API Specification Clarified.................................78
Expires: May 2001 [Page 3]
C LDAP API C LDAP Application Program Interface 17 November 2000
26.9. Deprecated Functions........................................78
27. Appendix E - Data Types and Legacy Implementations.............79
28. Appendix F - Changes Made Since Last Document Revision.........80
28.1. API Changes.................................................80
28.2. Editorial Changes and Clarifications........................81
4. Overview of the LDAP Model
LDAP is the lightweight directory access protocol, described in [2] and
[3]. It can provide a lightweight frontend to the X.500 directory [4],
or a stand-alone service. In either mode, LDAP is based on a client-
server model in which 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 infor-
mation about some object (e.g., 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 attri-
bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
values behave during directory operations (e.g., is case significant
during comparisons).
Entries may be organized in a tree structure, usually based on politi-
cal, geographical, and 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 "cn=Barbara Jensen,
o=University of Michigan, c=US". The DN format used by LDAP is defined
in [5].
Operations are provided to authenticate, search for and retrieve infor-
mation, modify information, and add and delete entries from the tree.
The next sections give an overview of how the API is used and detailed
descriptions of the LDAP API calls that implement all of these func-
tions.
5. Overview of LDAP API Use and General Requirements
An application generally uses the C LDAP API in four simple steps.
Expires: May 2001 [Page 4]
C LDAP API C LDAP Application Program Interface 17 November 2000
1. 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.
2. Authenticate to the LDAP server. The ldap_sasl_bind() function
and friends support a variety of authentication methods.
3. Perform some LDAP operations and obtain some results.
ldap_search() and friends return results which can be parsed by
ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc.
4. Close the session. The ldap_unbind() function closes the connec-
tion.
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 rou-
tines return an indication of the outcome of the operation (e.g, the
constant LDAP_SUCCESS or some other result code). The asynchronous rou-
tines make available to the caller the message id of the operation ini-
tiated. 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(). Note that
there is no requirement that an LDAP API implementation not block when
handling asynchronous API functions; the term "asynchronous" as used in
this document refers to the fact that the sending of LDAP requests can
be separated from the receiving of LDAP responses.
Results and errors are returned in an opaque structure called LDAPMes-
sage. Routines are provided to parse this structure, step through
entries and attributes returned, etc. Routines are also provided to
interpret errors. Later sections of this document describe these rou-
tines in more detail.
LDAP version 3 servers can return referrals and references to other
servers. By default, implementations of this API will attempt to follow
referrals automatically for the application. This behavior can be dis-
abled globally (using the ldap_set_option() call) or on a per-request
basis through the use of a client control.
All DN and string attribute values passed into or produced by this C
LDAP API are represented using the character set of the underlying LDAP
protocol version in use. When this API is used with LDAPv3, DN and
string values are represented as UTF-8[6] characters. When this API is
used with LDAPv2, the US-ASCII[7] or T.61[7] character set are used.
Future documents MAY specify additional APIs supporting other character
sets.
Expires: May 2001 [Page 5]
C LDAP API C LDAP Application Program Interface 17 November 2000
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 LDAP version 3 features will need to
use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
switch to version 3.
Unless otherwise indicated, conformant implementations of this specifi-
cation MUST implement all of the C LDAP API functions as described in
this document, and they MUST use the function prototypes, macro defini-
tions, and types defined in this document.
Note that this API is designed for use in environments where the 'int'
type is at least 32 bits in size.
6. Header Requirements
To promote portability of applications, the following requirements are
imposed on the headers used by applications to access the services of
this API:
Name and Inclusion
Applications only need to include a single header named ldap.h
to access all of the API services described in this document.
Therefore, the following C source program MUST compile and exe-
cute without errors:
#include <ldap.h>
int
main()
{
return 0;
}
The ldap.h header MAY include other implementation-specific
headers.
Implementations SHOULD also provide a header named lber.h to facilitate
development of applications desiring compatibility with older LDAP
implementations. The lber.h header MAY be empty. Old applications that
include lber.h in order to use BER facilities will need to include
ldap.h.
Idempotence
All headers SHOULD be idempotent; that is, if they are included
more than once the effect is as if they had only been included
Expires: May 2001 [Page 6]
C LDAP API C LDAP Application Program Interface 17 November 2000
once.
Must Be Included Before API Is Used
An application MUST include the ldap.h header before referencing
any of the function or type definitions described in this API
specification.
Mutual Independence
Headers SHOULD be mutually independent with minimal dependence
on system or any other headers.
Use of the 'const' Keyword
This API specification is defined in terms of ISO C[8]. It
makes use of function prototypes and the 'const' keyword. The
use of 'const' in this specification is limited to simple, non-
array function parameters to avoid forcing applications to
declare parameters and variables that accept return values from
LDAP API functions as 'const.' Implementations specifically
designed to be used with non-ISO C translators SHOULD provide
function declarations without prototypes or function prototypes
without specification of 'const' arguments.
Definition of 'struct timeval'
This API specification uses the 'struct timeval' type. Imple-
mentations of this API MUST ensure that the struct timeval type
is by default defined as a consequence of including the ldap.h
header. Because struct timeval is usually defined in one or
more system headers, it is possible for header conflicts to
occur if ldap.h also defines it or arranges for it to be defined
by including another header. Therefore, applications MAY want
to arrange for struct timeval to be defined before they include
ldap.h. To support this, the ldap.h header MUST NOT itself
define struct timeval if the preprocessor symbol
LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h is included.
7. Common Data Structures and Types
Data structures and types that are common to several LDAP API functions
are defined here:
typedef struct ldap LDAP;
typedef struct ldapmsg LDAPMessage;
typedef struct berelement BerElement;
typedef <impl_len_t> ber_len_t;
Expires: May 2001 [Page 7]
C LDAP API C LDAP Application Program Interface 17 November 2000
typedef struct berval {
ber_len_t bv_len;
char *bv_val;
} BerValue;
struct timeval {
<impl_sec_t> tv_sec;
<impl_usec_t> tv_usec;
};
The LDAP structure is an opaque data type that represents an LDAP ses-
sion Typically this corresponds to a connection to a single server, but
it MAY encompass several server connections in the face of LDAPv3 refer-
rals.
The LDAPMessage structure is an opaque data type that is used to return
entry, reference, result, and error information. An LDAPMessage struc-
ture can represent the beginning of a list, or chain of messages that
consists of a series of entries, references, and result messages as
returned by LDAP operations such as search. LDAP API functions such as
ldap_parse_result() that operate on message chains that can contain more
than one result message always operate on the first result message in
the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
section of this document for more information.
The BerElement structure is an opaque data type that is used to hold
data and state information about encoded data. It is described in more
detail in the section "Encoded ASN.1 Value Manipulation" later in this
document.
The `ber_len_t' type is an unsigned integral data type that is large
enough to contain the length of the largest piece of data supported by
the API implementation. The `<impl_len_t>' in the `ber_len_t' typedef
MUST be replaced with an appropriate type. The width (number of signi-
ficant bits) of `ber_len_t' MUST be at least 32 and no larger than that
of `unsigned long'. See the appendix "Data Types and Legacy Implementa-
tions" for additional considerations.
The BerValue 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:
Expires: May 2001 [Page 8]
C LDAP API C LDAP Application Program Interface 17 November 2000
tv_sec Seconds component of time interval.
tv_usec Microseconds component of time interval.
Note that because the struct timeval definition typically is derived
from a system header, the types used for the tv_sec and tv_usec com-
ponents are implementation-specific integral types. Therefore,
`<impl_sec_t>' and `<impl_usec_t>' in the struct timeval definition MUST
be replaced with appropriate types. See the earlier section "Header
Requirements" for more information on struct timeval.
8. Memory Handling Overview
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. The correct "free" function to
call is documented in each section of this document where a function
that allocates memory is described.
Memory that is allocated through means outside of the C LDAP API MUST
NOT be disposed of using a function provided by this API.
If a pointer value passed to one of the C LDAP API "free" functions is
NULL, graceful failure (i.e, ignoring of the NULL pointer) MUST occur.
The complete list of "free" functions that are used to dispose of allo-
cated memory is:
ber_bvecfree()
ber_bvfree()
ber_free()
ldap_control_free()
ldap_controls_free()
ldap_memfree()
ldap_msgfree()
ldap_value_free()
ldap_value_free_len()
9. Retrieving Information About the API Implementation
Applications developed to this specification need to be able to deter-
mine information about the particular API implementation they are using
both at compile time and during execution.
Expires: May 2001 [Page 9]
C LDAP API C LDAP Application Program Interface 17 November 2000
9.1. Retrieving Information at Compile Time
All conformant implementations MUST include the following five defini-
tions in a header so compile time tests can be done by LDAP software
developers:
#define LDAP_API_VERSION level
#define LDAP_VERSION_MIN min-version
#define LDAP_VERSION_MAX max-version
#define LDAP_VENDOR_NAME "vend-name"
#define LDAP_VENDOR_VERSION vend-version
where:
"level" is replaced with the RFC number given to this C LDAP API
specification when it is published as a standards track RFC.
min-version is replaced with the lowest LDAP protocol version sup-
ported by the implementation.
max-version is replaced with the highest LDAP protocol version sup-
ported by the implementation. This SHOULD be 3.
"vend-name" is replaced with a text string that identifies the
party that supplies the API implementation.
"vend-version" is a supplier-specific version number multiplied
times 100.
Note that the LDAP_VENDOR_NAME macro SHOULD be defined as "" if no ven-
dor name is available and the LDAP_VENDOR_VERSION macro SHOULD be
defined as 0 if no vendor-specific version information is available.
For example, if this specification is published as RFC 88888, Netscape
Communication's version 4.0 implementation that supports LDAPv2 and v3
might include macro definitions like these:
#define LDAP_API_VERSION 88888 /* RFC 88888 compliant */
#define LDAP_VERSION_MIN 2
#define LDAP_VERSION_MAX 3
#define LDAP_VENDOR_NAME "Netscape Communications Corp."
#define LDAP_VENDOR_VERSION 400 /* version 4.0 */
and application code can test the C LDAP API version level using a
construct such as this one:
#if (LDAP_API_VERSION >= 88888)
/* use features supported in RFC 88888 or later */
Expires: May 2001 [Page 10]
C LDAP API C LDAP Application Program Interface 17 November 2000
#endif
Until such time as this document is published as an RFC, implementations
SHOULD use the value 2000 plus the revision number of this draft for
LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION
for revision 05 of this draft is 2005.
Documents that extend this specification SHOULD define a macro of the
form:
#define LDAP_API_FEATURE_x level
where "x" is replaced with a name (textual identifier) for the feature
and "level" is replaced with the number of the RFC that specifies the
API extension. The name SHOULD NOT begin with the string "X_".
For example, if C LDAP API extensions for Transport Layer Security [9]
were published in RFC 99999, that RFC might require conformant implemen-
tations to define a macro like this:
#define LDAP_API_FEATURE_TLS 99999
Private or experimental API extensions SHOULD be indicated by defining a
macro of this same form where "x" (the extension's name) begins with the
string "X_" and "level" is replaced with a integer number that is
specific to the extension.
It is RECOMMENDED that private or experimental API extensions use only
the following prefixes for macros, types, and function names:
LDAP_X_
LBER_X_
ldap_x_
ber_x_
and that these prefixes not be used by standard extensions.
9.2. Retrieving Information During Execution
The ldap_get_option() call (described in greater detail later in this
document) can be used during execution in conjunction with an option
parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic
information about the API and about the specific implementation being
used. The ld parameter to ldap_get_option() can be either NULL or a
valid LDAP session handle which was obtained by calling ldap_init().
The optdata parameter to ldap_get_option() SHOULD be the address of an
LDAPAPIInfo structure which is defined as follows:
Expires: May 2001 [Page 11]
C LDAP API C LDAP Application Program Interface 17 November 2000
typedef struct ldapapiinfo {
int ldapai_info_version; /* version of this struct (1) */
int ldapai_api_version; /* revision of API supported */
int ldapai_protocol_version; /* highest LDAP version supported */
char **ldapai_extensions; /* names of API extensions */
char *ldapai_vendor_name; /* name of supplier */
int ldapai_vendor_version; /* supplier-specific version times 100 */
} LDAPAPIInfo;
In addition, API implementations MUST include the following macro defin-
ition:
#define LDAP_API_INFO_VERSION 1
Note that the ldapai_info_version field of the LDAPAPIInfo structure
SHOULD be set to the value LDAP_API_INFO_VERSION (1) before calling
ldap_get_option() so that it can be checked for consistency. All other
fields are set by the ldap_get_option() function.
The members of the LDAPAPIInfo structure are:
ldapai_info_version
A number that identifies the version of the LDAPAPIInfo struc-
ture. This SHOULD be set to the value LDAP_API_INFO_VERSION
(1) before calling ldap_get_option(). If the value received
is not recognized by the API implementation, the
ldap_get_option() function sets ldapai_info_version to a valid
value that would be recognized, sets the ldapai_api_version to
the correct value, and returns an error without filling in any
of the other fields in the LDAPAPIInfo structure.
ldapai_api_version
A number that matches that assigned to the C LDAP API RFC sup-
ported by the API implementation. This SHOULD match the value
of the LDAP_API_VERSION macro defined earlier.
ldapai_protocol_version
The highest LDAP protocol version supported by the implementa-
tion. For example, if LDAPv3 is the highest version supported
then this field will be set to 3.
ldapai_vendor_name
A zero-terminated string that contains the name of the party
that produced the LDAP API implementation. This field may be
set to NULL if no name is available. If non-NULL, the caller
is responsible for disposing of the memory occupied by passing
this pointer to ldap_memfree() which is described later in
this document. This value SHOULD match the value of the
Expires: May 2001 [Page 12]
C LDAP API C LDAP Application Program Interface 17 November 2000
LDAP_VENDOR_NAME macro described earlier in this document.
ldapai_vendor_version
An implementation-specific version number multiplied by 100.
For example, if the implementation version is 4.0 then this
field will be set to 400. If no version information is avail-
able, this field will be set to 0. This value SHOULD match
the value of the LDAP_VENDOR_VERSION macro described earlier
in this document.
ldapai_extensions
A NULL-terminated array of character strings that lists the
names of the API extensions supported by the LDAP API imple-
mentation. These names will typically match the textual iden-
tifiers that appear in the "x" portion of the
LDAP_API_FEATURE_x macros described above, although the pre-
cise value MUST be defined by documents that specify C LDAP
API extensions. If no API extensions are supported, this
field will be set to NULL. The caller is responsible for
disposing of the memory occupied by this array by passing it
to ldap_value_free() which is described later in this docu-
ment. To retrieve more information about a particular exten-
sion, the ldap_get_option() call can be used with an option
parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt-
data parameter to the ldap_get_option() SHOULD be the address
of an LDAPAPIFeatureInfo structure which is defined as fol-
lows:
typedef struct ldap_apifeature_info {
int ldapaif_info_version; /* version of this struct (1) */
char *ldapaif_name; /* name of supported feature */
int ldapaif_version; /* revision of supported feature */
} LDAPAPIFeatureInfo;
In addition, API implementations MUST include the following
macro definition:
#define LDAP_FEATURE_INFO_VERSION 1
Note that the ldapaif_info_version field of the LDAPAPI-
FeatureInfo structure SHOULD be set to the value
LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field
SHOULD be set to the extension name string as described below
before ldap_get_option() is called. The call will fill in the
ldapaif_version field of the LDAPAPIFeatureInfo structure.
The members of the LDAPAPIFeatureInfo structure are:
Expires: May 2001 [Page 13]
C LDAP API C LDAP Application Program Interface 17 November 2000
ldapaif_info_version
A number that identifies the version of the LDAPAPI-
FeatureInfo structure. This SHOULD be set to the value
LDAP_FEATURE_INFO_VERSION (1) before calling
ldap_get_option(). If the value received is not recognized
by the API implementation, the ldap_get_option() function
sets ldapaif_info_version to a valid value that would be
recognized and returns an error without filling in the
ldapaif_version field in the LDAPAPIFeatureInfo structure.
ldapaif_name
The name of an extension, as returned in the
ldapai_extensions array of the LDAPAPIInfo structure and as
specified in the document that describes the extension.
ldapaif_version
This field will be set as a result of calling
ldap_get_option(). It is a number that matches that
assigned to the C LDAP API extension RFC supported for this
extension. For private or experimental API extensions, the
value is extension-specific. In either case, the value of
ldapaxi_ext_version SHOULD be identical to the value of the
LDAP_API_FEATURE_x macro defined for the extension
(described above).
10. Result Codes
Many of the LDAP API routines return result codes, some of which indi-
cate local API errors and some of which are LDAP resultCodes that are
returned by servers. All of the result codes are non-negative integers.
Supported result 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
Expires: May 2001 [Page 14]
C LDAP API C LDAP Application Program Interface 17 November 2000
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 CLDAP
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)
Expires: May 2001 [Page 15]
C LDAP API C LDAP Application Program Interface 17 November 2000
11. Performing LDAP Operations
This section describes each LDAP operation API call in detail. Most
functions take a "session handle," a pointer to an LDAP structure con-
taining per-connection information. Many routines return results in an
LDAPMessage structure. These structures and others are described as
needed below.
11.1. Initializing an LDAP Session
ldap_init() 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 routine is deprecated:
LDAP *ldap_open(
const char *hostname,
int portno
);
Unlike ldap_init(), ldap_open() attempts to make a server connection
before returning to the caller. A more complete description can be
found in RFC 1823.
Parameters are:
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 MAY include a port number
which is separated from the host itself with a colon (:) char-
acter. The hosts will be tried in the order listed, stopping
with the first one to which a successful connection is made.
Note: A suitable representation for including a literal IPv6[10]
address in the hostname parameter is desired, but has not yet been
determined or implemented in practice.
portno Contains the TCP port number to connect to. The default LDAP
port of 389 can be obtained by supplying the value zero (0) or
the macro LDAP_PORT (389). If a host includes a port number
then this parameter is ignored.
Expires: May 2001 [Page 16]
C LDAP API C LDAP Application Program Interface 17 November 2000
ldap_init() and ldap_open() both return a "session handle," a pointer to
an opaque structure that MUST be passed to subsequent calls pertaining
to the session. These routines return NULL if the session cannot be ini-
tialized 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 LDAPv2 server, one of the LDAP bind calls
described below SHOULD be completed before other operations can be per-
formed 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 routines described in the next section.
11.2. LDAP Session Handle Options
The LDAP session handle returned by ldap_init() is a pointer to an
opaque data type representing an LDAP session. In RFC 1823 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.
In the interest of insulating callers from inevitable changes to this
structure, these aspects of the session are now accessed through a pair
of accessor functions, described below.
ldap_get_option() is used to access the current value of various
session-wide parameters. ldap_set_option() 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.
Note that if automatic referral following is enabled (the default), any
connections created during the course of following referrals will
inherit the options associated with the session that sent the original
request that caused the referrals to be returned.
int ldap_get_option(
LDAP *ld,
int option,
void *outvalue
);
int ldap_set_option(
LDAP *ld,
int option,
const void *invalue
Expires: May 2001 [Page 17]
C LDAP API C LDAP Application Program Interface 17 November 2000
);
#define LDAP_OPT_ON (<impl_void_star_value>)
#define LDAP_OPT_OFF ((void *)0)
LDAP_OPT_ON MUST be defined as a non-null pointer to void; that is,
<impl_void_star_value> MUST be replaced with a non-null pointer to
void, e.g., one could use:
#define LDAP_OPT_ON ((void *)1)
if that value is safe to use on the architecture where the API is
implemented.
Parameters are:
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 indi-
cated meanings. After the constant the actual hexadecimal value
of the constant is listed in parentheses.
LDAP_OPT_API_INFO (0x00)
Type for invalue parameter: not applicable (option is READ-ONLY)
Type for outvalue parameter: LDAPAPIInfo *
Description:
Used to retrieve some basic information about the LDAP API
implementation at execution time. See the section "Retriev-
ing Information About the API Implementation" above for more
information. This option is READ-ONLY and cannot be set.
LDAP_OPT_DEREF (0x02)
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description:
Determines how aliases are handled during search. It SHOULD
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 are dereferenced during the search but not when
locating the base object of the search. The
Expires: May 2001 [Page 18]
C LDAP API C LDAP Application Program Interface 17 November 2000
LDAP_DEREF_FINDING value means aliases are dereferenced when
locating the base object but not during the search. The
default value for this option is LDAP_DEREF_NEVER.
LDAP_OPT_SIZELIMIT (0x03)
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description:
A limit on the number of entries to return from a search. A
value of LDAP_NO_LIMIT (0) means no limit. The default value
for this option is LDAP_NO_LIMIT.
LDAP_OPT_TIMELIMIT (0x04)
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description:
A limit on the number of seconds to spend on a search. A
value of LDAP_NO_LIMIT (0) means no limit. The default value
for this option is LDAP_NO_LIMIT. This value is passed to
the server in the search request only; it does not affect how
long the C LDAP API implementation itself will wait locally
for search results. Note that the timeout parameter passed
to the ldap_search_ext_s() or ldap_result() functions can be
used to specify a limit on how long the API implementation
will wait for results.
LDAP_OPT_REFERRALS (0x08)
Type for invalue parameter: void * (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 or not. It MAY be set to
one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-
NULL pointer value passed to ldap_set_option() enables this
option. When reading the current setting using
ldap_get_option(), a zero value means OFF and any non-zero
value means ON. By default, this option is ON.
LDAP_OPT_RESTART (0x09)
Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
Type for outvalue parameter: int *
Expires: May 2001 [Page 19]
C LDAP API C LDAP Application Program Interface 17 November 2000
Description:
Determines whether LDAP I/O operations are automatically res-
tarted if they abort prematurely. It MAY be set to one of the
constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer
value passed to ldap_set_option() enables this option. When
reading the current setting using ldap_get_option(), a zero
value means OFF and any non-zero value means ON. This option
is useful if an LDAP I/O operation can be interrupted prema-
turely, for example by a timer going off, or other interrupt.
By default, this option is OFF.
LDAP_OPT_PROTOCOL_VERSION (0x11)
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description:
This option indicates the version of the LDAP protocol used
when communicating with the primary LDAP server. It SHOULD be
one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3).
If no version is set the default is LDAP_VERSION2 (2).
LDAP_OPT_SERVER_CONTROLS (0x12)
Type for invalue parameter: LDAPControl **
Type for outvalue parameter: LDAPControl ***
Description:
A default list of LDAP server controls to be sent with each
request. See the Working With Controls section below.
LDAP_OPT_CLIENT_CONTROLS (0x13)
Type for invalue parameter: LDAPControl **
Type for outvalue parameter: LDAPControl ***
Description:
A default list of client controls that affect the LDAP ses-
sion. See the Working With Controls section below.
LDAP_OPT_API_FEATURE_INFO (0x15)
Type for invalue parameter: not applicable (option is READ-ONLY)
Type for outvalue parameter: LDAPAPIFeatureInfo *
Description:
Used to retrieve version information about LDAP API extended
features at execution time. See the section "Retrieving
Expires: May 2001 [Page 20]
C LDAP API C LDAP Application Program Interface 17 November 2000
Information About the API Implementation" above for more
information. This option is READ-ONLY and cannot be set.
LDAP_OPT_HOST_NAME (0x30)
Type for invalue parameter: char *
Type for outvalue parameter: char **
Description:
The host name (or list of hosts) for the primary LDAP server.
See the definition of the hostname parameter to ldap_init()
for the allowed syntax. Note that if the portno parameter
passed to ldap_init() is a value other than 0 or 389
(LDAP_PORT), this value SHOULD include a string like
":portno" after each hostname or IP address that did not have
one in the original hostname parameter that was passed to
ldap_init(). For example, if this hostname value was passed
to ldap_init():
"ldap.example.com:389 ldap2.example.com"
and the portno parameter passed to ldap_init() was 6389, then
the value returned for the LDAP_OPT_HOST_NAME option SHOULD
be:
"ldap.example.com:389 ldap2.example.com:6389"
LDAP_OPT_RESULT_CODE (0x31)
Type for invalue parameter: int *
Type for outvalue parameter: int *
Description:
The most recent local (API generated) or server returned LDAP
result code that occurred for this session.
LDAP_OPT_ERROR_STRING (0x32)
Type for invalue parameter: char *
Type for outvalue parameter: char **
Description:
The message returned with the most recent LDAP error that
occurred for this session.
LDAP_OPT_MATCHED_DN (0x33)
Type for invalue parameter: char *
Expires: May 2001 [Page 21]
C LDAP API C LDAP Application Program Interface 17 November 2000
Type for outvalue parameter: char **
Description:
The matched DN value 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 LDAPCon-
trol **, a copy of the 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(), depending on
the type of data returned.
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 data associated with invalue is copied by the
API implementation to allow callers of the API to dispose of or
otherwise change their copy of the data after a successful call
to ldap_set_option(). If a value passed for invalue is invalid
or cannot b
