The LDAP Application Program Interface
RFC 1823

Document Type RFC - Informational (August 1995; No errata)
Was draft-howes-ldap-app (individual)
Last updated 2013-03-02
Stream Legacy
Formats plain text html pdf htmlized bibtex
Stream Legacy state (None)
Consensus Boilerplate Unknown
RFC Editor Note (None)
IESG IESG state RFC 1823 (Informational)
Telechat date
Responsible AD (None)
Send notices to (None)
Network Working Group                                           T. Howes
Request for Comments: 1823                                      M. Smith
Category: Informational                          University of  Michigan
                                                             August 1995

                 The LDAP Application Program Interface

Status of this Memo

   This memo provides information for the Internet community.  This memo
   does not specify an Internet standard of any kind.  Distribution of
   this memo is unlimited.

1.  Introduction

   This document defines a C language application program interface to
   the lightweight directory access protocol (LDAP). The 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 application
   program to obtain LDAP information.  The API calls are described in
   detail, followed by an appendix that provides some example code
   demonstrating the use of the API.

2.  Overview of the LDAP Model

   LDAP is the lightweight directory access protocol, described in [2]
   and [7]. It can provide a lightweight frontend to the X.500 directory
   [1], 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
   information 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 attribute (e.g., ASCII characters, a jpeg photograph,
   etc.) and how those values behave during directory operations (e.g.,
   is case significant during comparisons).

   Entries are organized in a tree structure, usually based on
   political, 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

Howes & Smith                Informational                      [Page 1]
RFC 1823                        LDAP API                     August 1995

   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 root of the tree down to the entry. 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 [4].

   Operations are provided to authenticate, search for and retrieve
   information, 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 functions.

3.  Overview of LDAP API Use

   An application generally uses the LDAP API in four simple steps.

   o    Open a connection to an LDAP server. The ldap_open() call
        returns a handle to the connection, allowing multiple
        connections to be open at once.

   o    Authenticate to the LDAP server and/or the X.500 DSA. The
        ldap_bind() call and friends support a variety of
        authentication methods.

   o    Perform some LDAP operations and obtain some results.
        ldap_search() and friends return results which can be parsed
        by ldap_result2error(), ldap_first_entry(), ldap_next_entry(),
        etc.

   o    Close the connection. The ldap_unbind() call closes the
        connection.

   Operations can be performed either synchronously or asynchronously.
   Synchronous calls 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 routines return
   an indication of the outcome of the operation (e.g, the constant
   LDAP_SUCCESS or some other error code).  The asynchronous routines
   return 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().

Howes & Smith                Informational                      [Page 2]
RFC 1823                        LDAP API                     August 1995

   Results and errors are returned in an opaque structure called
   LDAPMessage.  Routines are provided to parse this structure, step
Show full document text