rfc1823.txt

中、英文RFC文档大全打包下载完全版 .

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
   through entries and attributes returned, etc. Routines are also
   provided to interpret errors. The next sections describe these
   routines in more detail.

4.  Calls for performing LDAP operations

   This section describes each LDAP operation API call in detail. All
   calls take a "connection handle", a pointer to an LDAP structure
   containing per-connection information.  Many routines return results
   in an LDAPMessage structure. These structures and others are
   described as needed below.

4.1.  Opening a connection

   ldap_open() opens a connection to the LDAP server.

              typedef struct ldap {
                      /* ... opaque parameters ... */
                      int     ld_deref;
                      int     ld_timelimit;
                      int     ld_sizelimit;
                      int     ld_errno;
                      char    *ld_matched;
                      char    *ld_error;
                      /* ... opaque parameters ... */
              } LDAP;

              LDAP *ldap_open( char *hostname, int portno );

      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. The hosts are tried in the
               order listed, stopping with the first one to which a
               successful connection is made;

      portno   contains the TCP port number to which to connect. The
               default LDAP port can be obtained by supplying the
               constant LDAP_PORT.

   ldap_open() returns a "connection handle", a pointer to an LDAP
   structure that should be passed to subsequent calls pertaining to the
   connection. It returns NULL if the connection cannot be opened. One
   of the ldap_bind calls described below must be completed before other
   operations can be performed on the connection.



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


   The calling program should assume nothing about the order of the
   fields in the LDAP structure. There may be other fields in the
   structure for internal library use. The fields shown above are
   described as needed in the description of other calls below.

4.2.  Authenticating to the directory

   ldap_bind() and friends are used to authenticate to the directory.

           int ldap_bind( LDAP *ld, char *dn, char *cred, int method );

           int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );

           int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );

           int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );

           int ldap_kerberos_bind( LDAP *ld, char *dn );

           int ldap_kerberos_bind_s( LDAP *ld, char *dn );

   Parameters are:

   ld     The connection handle;

   dn     The name of the entry to bind as;

   cred   The credentials with which to authenticate;

   method One of LDAP_AUTH_SIMPLE, LDAP_AUTH_KRBV41, or
          LDAP_AUTH_KRBV42, indicating the authentication method to use;

   passwd For ldap_simple_bind(), the password to compare to the entry's
          userPassword attribute;

   There are three types of bind calls, providing simple authentication,
   kerberos authentication, and general routines to do either one. In
   the case of Kerberos version 4 authentication using the general
   ldap_bind() routines, the credentials are ignored, as the routines
   assume a valid ticket granting ticket already exists which can be
   used to retrieve the appropriate service tickets.

   Synchronous versions of the routines have names that end in _s.
   These routines return the result of the bind operation, either the
   constant LDAP_SUCCESS if the operation was successful, or another
   LDAP error code if it was not. See the section below on error
   handling for more information about possible errors and how to
   interpret them.



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


   Asynchronous versions of these routines return the message id of the
   bind operation initiated. A subsequent call to ldap_result(),
   described below, can be used to obtain the result of the bind. In
   case of error, these routines will return -1, setting the ld_errno
   field in the LDAP structure appropriately.

   Note that no other operations over the connection should be attempted
   before a bind call has successfully completed. Subsequent bind calls
   can be used to re-authenticate over the same connection.

4.3.  Closing the connection

   ldap_unbind() is used to unbind from the directory and close the
   connection.

           int ldap_unbind( LDAP *ld );

   Parameters are:

      ld   The connection handle.

   ldap_unbind() works synchronously, unbinding from the directory,
   closing the connection, and freeing up the ld structure before
   returning. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error
   code if the request cannot be sent to the LDAP server).  After a call
   to ldap_unbind(), the ld connection handle is invalid.

4.4.  Searching

   ldap_search() and friends are used to search the LDAP directory,
   returning a requested set of attributes for each entry matched.
   There are three variations.

           struct timeval {
                   long    tv_sec;
                   long    tv_usec;
           };
           int ldap_search(
                   LDAP    *ld,
                   char    *base,
                   int     scope,
                   char    *filter,
                   char    *attrs[],
                   int     attrsonly
           );
           int ldap_search_s(
                   LDAP            *ld,
                   char            *base,



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


                   int             scope,
                   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:

   ld        The connection handle;

   base      The dn of the entry at which to start the search;

   scope     One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or
             LDAP_SCOPE_SUBTREE, indicating the scope of the search;

   filter    A character string as described in RFC 1558 [3],
             representing the search filter;

   attrs     A NULL-terminated array of strings indicating which
             attributes to return for each matching entry. Passing
             NULL for this parameter causes all available attributes
             to be retrieved;

   attrsonly A boolean value that should be zero if both attribute
             types and values are to be returned, non-zero if only
             types are wanted;

   timeout   For the ldap_search_st() call, this specifies the local
             search timeout value;

   res       For the synchronous calls, this is a result parameter
             which will contain the results of the search upon
             completion of the call.

   There are three fields in the ld connection handle which control how
   the search is performed. They are:




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


   ld_sizelimit A limit on the number of entries to return from the
                search. A value of zero means no limit;

   ld_timelimit A limit on the number of seconds to spend on the search.
                A value of zero means no limit;

   ld_deref     One of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING,
                LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, 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.

   An asynchronous search is initiated by calling ldap_search(). It
   returns the message id of the initiated search. The results of the
   search can be obtained by a subsequent call to ldap_result().  The
   results can be parsed by the result parsing routines described in
   detail later.  In case of error, -1 is returned and the ld_errno
   field in the LDAP structure is set appropriately.

   A synchronous search is performed by calling ldap_search_s() or
   ldap_search_st(). The routines are identical, except that
   ldap_search_st() takes an additional parameter specifying a timeout
   for the search.  Both routines return an indication of the result of
   the search, either LDAP_SUCCESS or some error indication (see Error
   Handling below).  The entries returned from the search (if any) are
   contained in the res parameter. This parameter is opaque to the
   caller.  Entries, attributes, values, etc., should be extracted by
   calling the parsing routines described below. The results contained
   in res should be freed when no longer in use by calling
   ldap_msgfree(), described later.

4.5.  Reading 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=*)". attrs contains the list of attributes to return.

4.6.  Listing the children of an entry

   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=*)". attrs contains the list of attributes to return
   for each child entry.



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


4.7.  Modifying an entry

   The ldap_modify() and ldap_modify_s() routines are used to modify an
   existing LDAP entry.

           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