home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc1823 < prev    next >
Text File  |  1995-08-08  |  41KB  |  1,236 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           T. Howes
  8. Request for Comments: 1823                                      M. Smith
  9. Category: Informational                          University of  Michigan
  10.                                                              August 1995
  11.  
  12.  
  13.                  The LDAP Application Program Interface
  14.  
  15. Status of this Memo
  16.  
  17.    This memo provides information for the Internet community.  This memo
  18.    does not specify an Internet standard of any kind.  Distribution of
  19.    this memo is unlimited.
  20.  
  21. 1.  Introduction
  22.  
  23.    This document defines a C language application program interface to
  24.    the lightweight directory access protocol (LDAP). The LDAP API is
  25.    designed to be powerful, yet simple to use. It defines compatible
  26.    synchronous and asynchronous interfaces to LDAP to suit a wide
  27.    variety of applications.  This document gives a brief overview of the
  28.    LDAP model, then an overview of how the API is used by an application
  29.    program to obtain LDAP information.  The API calls are described in
  30.    detail, followed by an appendix that provides some example code
  31.    demonstrating the use of the API.
  32.  
  33. 2.  Overview of the LDAP Model
  34.  
  35.    LDAP is the lightweight directory access protocol, described in [2]
  36.    and [7]. It can provide a lightweight frontend to the X.500 directory
  37.    [1], or a stand-alone service. In either mode, LDAP is based on a
  38.    client-server model in which a client makes a TCP connection to an
  39.    LDAP server, over which it sends requests and receives responses.
  40.  
  41.    The LDAP information model is based on the entry, which contains
  42.    information about some object (e.g., a person).  Entries are composed
  43.    of attributes, which have a type and one or more values. Each
  44.    attribute has a syntax that determines what kinds of values are
  45.    allowed in the attribute (e.g., ASCII characters, a jpeg photograph,
  46.    etc.) and how those values behave during directory operations (e.g.,
  47.    is case significant during comparisons).
  48.  
  49.    Entries are organized in a tree structure, usually based on
  50.    political, geographical, and organizational boundaries. Each entry is
  51.    uniquely named relative to its sibling entries by its relative
  52.    distinguished name (RDN) consisting of one or more distinguished
  53.    attribute values from the entry.  At most one value from each
  54.    attribute may be used in the RDN.  For example, the entry for the
  55.  
  56.  
  57.  
  58. Howes & Smith                Informational                      [Page 1]
  59.  
  60. RFC 1823                        LDAP API                     August 1995
  61.  
  62.  
  63.    person Babs Jensen might be named with the "Barbara Jensen" value
  64.    from the commonName attribute. A globally unique name for an entry,
  65.    called a distinguished name or DN, is constructed by concatenating
  66.    the sequence of RDNs from the root of the tree down to the entry. For
  67.    example, if Babs worked for the University of Michigan, the DN of her
  68.    U-M entry might be "cn=Barbara Jensen, o=University of Michigan,
  69.    c=US". The DN format used by LDAP is defined in [4].
  70.  
  71.    Operations are provided to authenticate, search for and retrieve
  72.    information, modify information, and add and delete entries from the
  73.    tree.  The next sections give an overview of how the API is used and
  74.    detailed descriptions of the LDAP API calls that implement all of
  75.    these functions.
  76.  
  77. 3.  Overview of LDAP API Use
  78.  
  79.    An application generally uses the LDAP API in four simple steps.
  80.  
  81.    o    Open a connection to an LDAP server. The ldap_open() call
  82.         returns a handle to the connection, allowing multiple
  83.         connections to be open at once.
  84.  
  85.    o    Authenticate to the LDAP server and/or the X.500 DSA. The
  86.         ldap_bind() call and friends support a variety of
  87.         authentication methods.
  88.  
  89.    o    Perform some LDAP operations and obtain some results.
  90.         ldap_search() and friends return results which can be parsed
  91.         by ldap_result2error(), ldap_first_entry(), ldap_next_entry(),
  92.         etc.
  93.  
  94.    o    Close the connection. The ldap_unbind() call closes the
  95.         connection.
  96.  
  97.    Operations can be performed either synchronously or asynchronously.
  98.    Synchronous calls end in _s. For example, a synchronous search can be
  99.    completed by calling ldap_search_s(). An asynchronous search can be
  100.    initiated by calling ldap_search(). All synchronous routines return
  101.    an indication of the outcome of the operation (e.g, the constant
  102.    LDAP_SUCCESS or some other error code).  The asynchronous routines
  103.    return the message id of the operation initiated. This id can be used
  104.    in subsequent calls to ldap_result() to obtain the result(s) of the
  105.    operation.  An asynchronous operation can be abandoned by calling
  106.    ldap_abandon().
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Howes & Smith                Informational                      [Page 2]
  115.  
  116. RFC 1823                        LDAP API                     August 1995
  117.  
  118.  
  119.    Results and errors are returned in an opaque structure called
  120.    LDAPMessage.  Routines are provided to parse this structure, step
  121.    through entries and attributes returned, etc. Routines are also
  122.    provided to interpret errors. The next sections describe these
  123.    routines in more detail.
  124.  
  125. 4.  Calls for performing LDAP operations
  126.  
  127.    This section describes each LDAP operation API call in detail. All
  128.    calls take a "connection handle", a pointer to an LDAP structure
  129.    containing per-connection information.  Many routines return results
  130.    in an LDAPMessage structure. These structures and others are
  131.    described as needed below.
  132.  
  133. 4.1.  Opening a connection
  134.  
  135.    ldap_open() opens a connection to the LDAP server.
  136.  
  137.               typedef struct ldap {
  138.                       /* ... opaque parameters ... */
  139.                       int     ld_deref;
  140.                       int     ld_timelimit;
  141.                       int     ld_sizelimit;
  142.                       int     ld_errno;
  143.                       char    *ld_matched;
  144.                       char    *ld_error;
  145.                       /* ... opaque parameters ... */
  146.               } LDAP;
  147.  
  148.               LDAP *ldap_open( char *hostname, int portno );
  149.  
  150.       Parameters are:
  151.  
  152.       hostname Contains a space-separated list of hostnames or dotted
  153.                strings representing the IP address of hosts running an
  154.                LDAP server to connect to. The hosts are tried in the
  155.                order listed, stopping with the first one to which a
  156.                successful connection is made;
  157.  
  158.       portno   contains the TCP port number to which to connect. The
  159.                default LDAP port can be obtained by supplying the
  160.                constant LDAP_PORT.
  161.  
  162.    ldap_open() returns a "connection handle", a pointer to an LDAP
  163.    structure that should be passed to subsequent calls pertaining to the
  164.    connection. It returns NULL if the connection cannot be opened. One
  165.    of the ldap_bind calls described below must be completed before other
  166.    operations can be performed on the connection.
  167.  
  168.  
  169.  
  170. Howes & Smith                Informational                      [Page 3]
  171.  
  172. RFC 1823                        LDAP API                     August 1995
  173.  
  174.  
  175.    The calling program should assume nothing about the order of the
  176.    fields in the LDAP structure. There may be other fields in the
  177.    structure for internal library use. The fields shown above are
  178.    described as needed in the description of other calls below.
  179.  
  180. 4.2.  Authenticating to the directory
  181.  
  182.    ldap_bind() and friends are used to authenticate to the directory.
  183.  
  184.            int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
  185.  
  186.            int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
  187.  
  188.            int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );
  189.  
  190.            int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );
  191.  
  192.            int ldap_kerberos_bind( LDAP *ld, char *dn );
  193.  
  194.            int ldap_kerberos_bind_s( LDAP *ld, char *dn );
  195.  
  196.    Parameters are:
  197.  
  198.    ld     The connection handle;
  199.  
  200.    dn     The name of the entry to bind as;
  201.  
  202.    cred   The credentials with which to authenticate;
  203.  
  204.    method One of LDAP_AUTH_SIMPLE, LDAP_AUTH_KRBV41, or
  205.           LDAP_AUTH_KRBV42, indicating the authentication method to use;
  206.  
  207.    passwd For ldap_simple_bind(), the password to compare to the entry's
  208.           userPassword attribute;
  209.  
  210.    There are three types of bind calls, providing simple authentication,
  211.    kerberos authentication, and general routines to do either one. In
  212.    the case of Kerberos version 4 authentication using the general
  213.    ldap_bind() routines, the credentials are ignored, as the routines
  214.    assume a valid ticket granting ticket already exists which can be
  215.    used to retrieve the appropriate service tickets.
  216.  
  217.    Synchronous versions of the routines have names that end in _s.
  218.    These routines return the result of the bind operation, either the
  219.    constant LDAP_SUCCESS if the operation was successful, or another
  220.    LDAP error code if it was not. See the section below on error
  221.    handling for more information about possible errors and how to
  222.    interpret them.
  223.  
  224.  
  225.  
  226. Howes & Smith                Informational                      [Page 4]
  227.  
  228. RFC 1823                        LDAP API                     August 1995
  229.  
  230.  
  231.    Asynchronous versions of these routines return the message id of the
  232.    bind operation initiated. A subsequent call to ldap_result(),
  233.    described below, can be used to obtain the result of the bind. In
  234.    case of error, these routines will return -1, setting the ld_errno
  235.    field in the LDAP structure appropriately.
  236.  
  237.    Note that no other operations over the connection should be attempted
  238.    before a bind call has successfully completed. Subsequent bind calls
  239.    can be used to re-authenticate over the same connection.
  240.  
  241. 4.3.  Closing the connection
  242.  
  243.    ldap_unbind() is used to unbind from the directory and close the
  244.    connection.
  245.  
  246.            int ldap_unbind( LDAP *ld );
  247.  
  248.    Parameters are:
  249.  
  250.       ld   The connection handle.
  251.  
  252.    ldap_unbind() works synchronously, unbinding from the directory,
  253.    closing the connection, and freeing up the ld structure before
  254.    returning. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error
  255.    code if the request cannot be sent to the LDAP server).  After a call
  256.    to ldap_unbind(), the ld connection handle is invalid.
  257.  
  258. 4.4.  Searching
  259.  
  260.    ldap_search() and friends are used to search the LDAP directory,
  261.    returning a requested set of attributes for each entry matched.
  262.    There are three variations.
  263.  
  264.            struct timeval {
  265.                    long    tv_sec;
  266.                    long    tv_usec;
  267.            };
  268.            int ldap_search(
  269.                    LDAP    *ld,
  270.                    char    *base,
  271.                    int     scope,
  272.                    char    *filter,
  273.                    char    *attrs[],
  274.                    int     attrsonly
  275.            );
  276.            int ldap_search_s(
  277.                    LDAP            *ld,
  278.                    char            *base,
  279.  
  280.  
  281.  
  282. Howes & Smith                Informational                      [Page 5]
  283.  
  284. RFC 1823                        LDAP API                     August 1995
  285.  
  286.  
  287.                    int             scope,
  288.                    char            *filter,
  289.                    char            *attrs[],
  290.                    int             attrsonly,
  291.                    LDAPMessage     **res
  292.            );
  293.            int ldap_search_st(
  294.                    LDAP            *ld,
  295.                    char            *base,
  296.                    int             scope,
  297.                    char            *filter,
  298.                    char            *attrs[],
  299.                    int             attrsonly,
  300.                    struct timeval  *timeout,
  301.                    LDAPMessage     **res
  302.            );
  303.  
  304.    Parameters are:
  305.  
  306.    ld        The connection handle;
  307.  
  308.    base      The dn of the entry at which to start the search;
  309.  
  310.    scope     One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or
  311.              LDAP_SCOPE_SUBTREE, indicating the scope of the search;
  312.  
  313.    filter    A character string as described in RFC 1558 [3],
  314.              representing the search filter;
  315.  
  316.    attrs     A NULL-terminated array of strings indicating which
  317.              attributes to return for each matching entry. Passing
  318.              NULL for this parameter causes all available attributes
  319.              to be retrieved;
  320.  
  321.    attrsonly A boolean value that should be zero if both attribute
  322.              types and values are to be returned, non-zero if only
  323.              types are wanted;
  324.  
  325.    timeout   For the ldap_search_st() call, this specifies the local
  326.              search timeout value;
  327.  
  328.    res       For the synchronous calls, this is a result parameter
  329.              which will contain the results of the search upon
  330.              completion of the call.
  331.  
  332.    There are three fields in the ld connection handle which control how
  333.    the search is performed. They are:
  334.  
  335.  
  336.  
  337.  
  338. Howes & Smith                Informational                      [Page 6]
  339.  
  340. RFC 1823                        LDAP API                     August 1995
  341.  
  342.  
  343.    ld_sizelimit A limit on the number of entries to return from the
  344.                 search. A value of zero means no limit;
  345.  
  346.    ld_timelimit A limit on the number of seconds to spend on the search.
  347.                 A value of zero means no limit;
  348.  
  349.    ld_deref     One of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING,
  350.                 LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, specifying
  351.                 how aliases should be handled during the search. The
  352.                 LDAP_DEREF_SEARCHING value means aliases should be
  353.                 dereferenced during the search but not when locating
  354.                 the base object of the search. The LDAP_DEREF_FINDING
  355.                 value means aliases should be dereferenced when
  356.                 locating the base object but not during the search.
  357.  
  358.    An asynchronous search is initiated by calling ldap_search(). It
  359.    returns the message id of the initiated search. The results of the
  360.    search can be obtained by a subsequent call to ldap_result().  The
  361.    results can be parsed by the result parsing routines described in
  362.    detail later.  In case of error, -1 is returned and the ld_errno
  363.    field in the LDAP structure is set appropriately.
  364.  
  365.    A synchronous search is performed by calling ldap_search_s() or
  366.    ldap_search_st(). The routines are identical, except that
  367.    ldap_search_st() takes an additional parameter specifying a timeout
  368.    for the search.  Both routines return an indication of the result of
  369.    the search, either LDAP_SUCCESS or some error indication (see Error
  370.    Handling below).  The entries returned from the search (if any) are
  371.    contained in the res parameter. This parameter is opaque to the
  372.    caller.  Entries, attributes, values, etc., should be extracted by
  373.    calling the parsing routines described below. The results contained
  374.    in res should be freed when no longer in use by calling
  375.    ldap_msgfree(), described later.
  376.  
  377. 4.5.  Reading an entry
  378.  
  379.    LDAP does not support a read operation directly. Instead, this
  380.    operation is emulated by a search with base set to the DN of the
  381.    entry to read, scope set to LDAP_SCOPE_BASE, and filter set to
  382.    "(objectclass=*)". attrs contains the list of attributes to return.
  383.  
  384. 4.6.  Listing the children of an entry
  385.  
  386.    LDAP does not support a list operation directly. Instead, this
  387.    operation is emulated by a search with base set to the DN of the
  388.    entry to list, scope set to LDAP_SCOPE_ONELEVEL, and filter set to
  389.    "(objectclass=*)". attrs contains the list of attributes to return
  390.    for each child entry.
  391.  
  392.  
  393.  
  394. Howes & Smith                Informational                      [Page 7]
  395.  
  396. RFC 1823                        LDAP API                     August 1995
  397.  
  398.  
  399. 4.7.  Modifying an entry
  400.  
  401.    The ldap_modify() and ldap_modify_s() routines are used to modify an
  402.    existing LDAP entry.
  403.  
  404.            typedef struct ldapmod {
  405.                    int             mod_op;
  406.                    char            *mod_type;
  407.                    union {
  408.                            char            **modv_strvals;
  409.                            struct berval   **modv_bvals;
  410.                    } mod_vals;
  411.            } LDAPMod;
  412.            #define mod_values      mod_vals.modv_strvals
  413.            #define mod_bvalues     mod_vals.modv_bvals
  414.  
  415.            int ldap_modify( LDAP *ld, char *dn, LDAPMod *mods[] );
  416.  
  417.            int ldap_modify_s( LDAP *ld, char *dn, LDAPMod *mods[] );
  418.  
  419.    Parameters are:
  420.  
  421.    ld       The connection handle;
  422.  
  423.    dn       The name of the entry to modify;
  424.  
  425.    mods     A NULL-terminated array of modifications to make to the
  426.             entry.
  427.  
  428.    The fields in the LDAPMod structure have the following meanings:
  429.  
  430.    mod_op   The modification operation to perform. It should be one of
  431.             LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. This
  432.             field also indicates the type of values included in the
  433.             mod_vals union. It is ORed with LDAP_MOD_BVALUES to select
  434.             the mod_bvalues form. Otherwise, the mod_values form is
  435.             used;
  436.  
  437.    mod_type The type of the attribute to modify;
  438.  
  439.    mod_vals The values (if any) to add, delete, or replace. Only one of
  440.             the mod_values or mod_bvalues variants should be used,
  441.             selected by ORing the mod_op field with the constant
  442.             LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
  443.             zero-terminated strings and mod_bvalues is a NULL-terminated
  444.             array of berval structures that can be used to pass binary
  445.             values such as images.
  446.  
  447.  
  448.  
  449.  
  450. Howes & Smith                Informational                      [Page 8]
  451.  
  452. RFC 1823                        LDAP API                     August 1995
  453.  
  454.  
  455.    For LDAP_MOD_ADD modifications, the given values are added to the
  456.    entry, creating the attribute if necessary.  For LDAP_MOD_DELETE
  457.    modifications, the given values are deleted from the entry, removing
  458.    the attribute if no values remain.  If the entire attribute is to be
  459.    deleted, the mod_vals field should be set to NULL.  For
  460.    LDAP_MOD_REPLACE modifications, the attribute will have the listed
  461.    values after the modification, having been created if necessary.  All
  462.    modifications are performed in the order in which they are listed.
  463.  
  464.    ldap_modify_s() returns the LDAP error code  resulting  from the
  465.    modify  operation.   This  code  can  be interpreted by ldap_perror()
  466.    and friends.
  467.  
  468.    ldap_modify() returns the message id of the request it initiates, or
  469.    -1 on error.  The result of the operation can be obtained by calling
  470.    ldap_result().
  471.  
  472. 4.8.  Modifying the RDN of an entry
  473.  
  474.    The ldap_modrdn() and ldap_modrdn_s() routines are used to change the
  475.    name of an LDAP entry.
  476.  
  477.            int ldap_modrdn(
  478.                    LDAP    *ld,
  479.                    char    *dn,
  480.                    char    *newrdn,
  481.                    int     deleteoldrdn
  482.            );
  483.            int ldap_modrdn_s(
  484.                    LDAP    *ld,
  485.                    char    *dn,
  486.                    char    *newrdn,
  487.                    int     deleteoldrdn
  488.            );
  489.  
  490.    Parameters are:
  491.  
  492.    ld            The connection handle;
  493.  
  494.    dn            The name of the entry whose RDN is to be changed;
  495.  
  496.    newrdn        The new RDN to give the entry;
  497.  
  498.    deleteoldrdn  A boolean value, if non-zero indicating that the old
  499.                  RDN value(s) should be removed, if zero indicating that
  500.                  the old RDN value(s) should be retained as non-
  501.                  distinguished values of the entry.
  502.  
  503.  
  504.  
  505.  
  506. Howes & Smith                Informational                      [Page 9]
  507.  
  508. RFC 1823                        LDAP API                     August 1995
  509.  
  510.  
  511.    The ldap_modrdn_s() routine is synchronous, returning the LDAP error
  512.    code indicating the outcome of the operation.
  513.  
  514.    The ldap_modrdn() routine is asynchronous, returning the message id
  515.    of the operation it initiates, or -1 in case of trouble. The result
  516.    of the operation can be obtained by calling ldap_result().
  517.  
  518. 4.9.  Adding an entry
  519.  
  520.    ldap_add() and ldap_add_s() are used to add entries to the LDAP
  521.    directory.
  522.  
  523.            int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] );
  524.  
  525.            int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] );
  526.  
  527.    Parameters are:
  528.  
  529.    ld    The connection handle;
  530.  
  531.    dn    The name of the entry to add;
  532.  
  533.    attrs The entry's attributes, specified using the LDAPMod structure
  534.          defined for ldap_modify(). The mod_type and mod_vals fields
  535.          should be filled in.  The mod_op field is ignored unless ORed
  536.          with the constant LDAP_MOD_BVALUES, used to select the
  537.          mod_bvalues case of the mod_vals union.
  538.  
  539.    Note that the parent of the entry must already exist.
  540.  
  541.    ldap_add_s() is synchronous, returning the LDAP error code indicating
  542.    the outcome of the operation.
  543.  
  544.    ldap_add() is asynchronous, returning the message id of the operation
  545.    it initiates, or -1 in case of trouble. The result of the operation
  546.    can be obtained by calling ldap_result().
  547.  
  548. 4.10.  Deleting an entry
  549.  
  550.    ldap_delete() and ldap_delete_s() are used to delete entries from the
  551.    LDAP directory.
  552.  
  553.            int ldap_delete( LDAP *ld, char *dn );
  554.  
  555.            int ldap_delete_s( LDAP *ld, char *dn );
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Howes & Smith                Informational                     [Page 10]
  563.  
  564. RFC 1823                        LDAP API                     August 1995
  565.  
  566.  
  567.    Parameters are:
  568.  
  569.    ld       The connection handle;
  570.  
  571.    dn       The name of the entry to delete.
  572.  
  573.    Note that the entry to delete must be a leaf entry (i.e., it must
  574.    have no children). Deletion of entire subtrees is not supported by
  575.    LDAP.
  576.  
  577.    ldap_delete_s() is synchronous, returning the LDAP error code
  578.    indicating the outcome of the operation.
  579.  
  580.    ldap_delete() is asynchronous, returning the message id of the
  581.    operation it initiates, or -1 in case of trouble. The result of the
  582.    operation can be obtained by calling ldap_result().
  583.  
  584. 5.  Calls for abandoning an operation
  585.  
  586.    ldap_abandon() is used to abandon an operation in progress.
  587.  
  588.            int ldap_abandon( LDAP *ld, int msgid );
  589.  
  590.    ldap_abandon() abandons the operation with message id msgid. It
  591.    returns zero if the abandon was successful, -1 otherwise. After a
  592.    successful call to ldap_abandon(), results with the given message id
  593.    are never returned from a call to ldap_result().
  594.  
  595. 6.  Calls for obtaining results
  596.  
  597.    ldap_result() is used to obtain the result of a previous
  598.    asynchronously initiated operation. ldap_msgfree() frees the results
  599.    obtained from a previous call to ldap_result(), or a synchronous
  600.    search routine.
  601.  
  602.            int ldap_result(
  603.                    LDAP            *ld,
  604.                    int             msgid,
  605.                    int             all,
  606.                    struct timeval  *timeout,
  607.                    LDAPMessage     **res
  608.            );
  609.  
  610.            int ldap_msgfree( LDAPMessage *res );
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618. Howes & Smith                Informational                     [Page 11]
  619.  
  620. RFC 1823                        LDAP API                     August 1995
  621.  
  622.  
  623.    Parameters are:
  624.  
  625.    ld       The connection handle;
  626.  
  627.    msgid    The message id of the operation whose results are to be
  628.             returned, or the constant LDAP_RES_ANY if any result is
  629.             desired;
  630.  
  631.    all      A boolean parameter that only has meaning for search
  632.             results. If non-zero it indicates that all results of a
  633.             search should be retrieved before any are returned. If zero,
  634.             search results (entries) will be returned one at a time as
  635.             they arrive;
  636.  
  637.    timeout  A timeout specifying how long to wait for results to be
  638.             returned.  A NULL value causes ldap_result() to block until
  639.             results are available.  A timeout value of zero second
  640.             specifies a polling behavior;
  641.  
  642.    res      For ldap_result(), a result parameter that will contain the
  643.             result(s) of the operation. For ldap_msgfree(), the result
  644.             chain to be freed, obtained from a previous call to
  645.             ldap_result() or ldap_search_s() or ldap_search_st().
  646.  
  647.    Upon successful completion, ldap_result() returns the type of the
  648.    result returned in the res parameter. This will be one of the
  649.    following constants.
  650.  
  651.              LDAP_RES_BIND
  652.              LDAP_RES_SEARCH_ENTRY
  653.              LDAP_RES_SEARCH_RESULT
  654.              LDAP_RES_MODIFY
  655.              LDAP_RES_ADD
  656.              LDAP_RES_DELETE
  657.              LDAP_RES_MODRDN
  658.              LDAP_RES_COMPARE
  659.  
  660.    ldap_result() returns 0 if the timeout expired and -1 if an error
  661.    occurs, in which case the ld_errno field of the ld structure will be
  662.    set accordingly.
  663.  
  664.    ldap_msgfree() frees the result structure pointed to be res and
  665.    returns the type of the message it freed.
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674. Howes & Smith                Informational                     [Page 12]
  675.  
  676. RFC 1823                        LDAP API                     August 1995
  677.  
  678.  
  679. 7.  Calls for error handling
  680.  
  681.    The following calls are used to interpret errors returned by other
  682.    LDAP API routines.
  683.  
  684.            int ldap_result2error(
  685.                    LDAP            *ld,
  686.                    LDAPMessage     *res,
  687.                    int             freeit
  688.            );
  689.  
  690.            char *ldap_err2string( int err );
  691.  
  692.            void ldap_perror( LDAP *ld, char *msg );
  693.  
  694.    Parameters are:
  695.  
  696.    ld       The connection handle;
  697.  
  698.    res      The result of an LDAP operation as returned by ldap_result()
  699.             or one of the synchronous API operation calls;
  700.  
  701.    freeit   A boolean parameter indicating whether the res parameter
  702.             should be freed (non-zero) or not (zero);
  703.  
  704.    err      An LDAP error code, as returned by ldap_result2error() or
  705.             one of the synchronous API operation calls;
  706.  
  707.    msg      A message to be displayed before the LDAP error message.
  708.  
  709.    ldap_result2error() is used to convert the LDAP result message
  710.    obtained from ldap_result(), or the res parameter returned by one of
  711.    the synchronous API operation calls, into a numeric LDAP error code.
  712.    It also parses the ld_matched and ld_error portions of the result
  713.    message and puts them into the connection handle information. All the
  714.    synchronous operation routines call ldap_result2error() before
  715.    returning, ensuring that these fields are set correctly. The relevant
  716.    fields in the connection structue are:
  717.  
  718.    ld_matched In the event of an LDAP_NO_SUCH_OBJECT error return, this
  719.               parameter contains the extent of the DN matched;
  720.  
  721.    ld_error   This parameter contains the error message sent in the
  722.               result by the LDAP server.
  723.  
  724.    ld_errno   The LDAP error code indicating the outcome of the
  725.               operation. It is one of the following constants:
  726.  
  727.  
  728.  
  729.  
  730. Howes & Smith                Informational                     [Page 13]
  731.  
  732. RFC 1823                        LDAP API                     August 1995
  733.  
  734.  
  735.            LDAP_SUCCESS
  736.            LDAP_OPERATIONS_ERROR
  737.            LDAP_PROTOCOL_ERROR
  738.            LDAP_TIMELIMIT_EXCEEDED
  739.            LDAP_SIZELIMIT_EXCEEDED
  740.            LDAP_COMPARE_FALSE
  741.            LDAP_COMPARE_TRUE
  742.            LDAP_STRONG_AUTH_NOT_SUPPORTED
  743.            LDAP_STRONG_AUTH_REQUIRED
  744.            LDAP_NO_SUCH_ATTRIBUTE
  745.            LDAP_UNDEFINED_TYPE
  746.            LDAP_INAPPROPRIATE_MATCHING
  747.            LDAP_CONSTRAINT_VIOLATION
  748.            LDAP_TYPE_OR_VALUE_EXISTS
  749.            LDAP_INVALID_SYNTAX
  750.            LDAP_NO_SUCH_OBJECT
  751.            LDAP_ALIAS_PROBLEM
  752.            LDAP_INVALID_DN_SYNTAX
  753.            LDAP_IS_LEAF
  754.            LDAP_ALIAS_DEREF_PROBLEM
  755.            LDAP_INAPPROPRIATE_AUTH
  756.            LDAP_INVALID_CREDENTIALS
  757.            LDAP_INSUFFICIENT_ACCESS
  758.            LDAP_BUSY
  759.            LDAP_UNAVAILABLE
  760.            LDAP_UNWILLING_TO_PERFORM
  761.            LDAP_LOOP_DETECT
  762.            LDAP_NAMING_VIOLATION
  763.            LDAP_OBJECT_CLASS_VIOLATION
  764.            LDAP_NOT_ALLOWED_ON_NONLEAF
  765.            LDAP_NOT_ALLOWED_ON_RDN
  766.            LDAP_ALREADY_EXISTS
  767.            LDAP_NO_OBJECT_CLASS_MODS
  768.            LDAP_RESULTS_TOO_LARGE
  769.            LDAP_OTHER
  770.            LDAP_SERVER_DOWN
  771.            LDAP_LOCAL_ERROR
  772.            LDAP_ENCODING_ERROR
  773.            LDAP_DECODING_ERROR
  774.            LDAP_TIMEOUT
  775.            LDAP_AUTH_UNKNOWN
  776.            LDAP_FILTER_ERROR
  777.            LDAP_USER_CANCELLED
  778.            LDAP_PARAM_ERROR
  779.            LDAP_NO_MEMORY
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786. Howes & Smith                Informational                     [Page 14]
  787.  
  788. RFC 1823                        LDAP API                     August 1995
  789.  
  790.  
  791.    ldap_err2string() is used to convert a numeric LDAP error code, as
  792.    returned by ldap_result2error() or one of the synchronous API
  793.    operation calls, into an informative NULL-terminated character string
  794.    message describing the error.  It returns a pointer to static data.
  795.  
  796.    ldap_perror() is used to print the message supplied in msg, followed
  797.    by an indication of the error contained in the ld_errno field of the
  798.    ld connection handle, to standard error.
  799.  
  800. 8.  Calls for parsing search entries
  801.  
  802.    The following calls are used to parse the entries returned by
  803.    ldap_search() and friends. These entries are returned in an opaque
  804.    structure that should only be accessed by calling the routines
  805.    described below. Routines are provided to step through the entries
  806.    returned, step through the attributes of an entry, retrieve the name
  807.    of an entry, and retrieve the values associated with a given
  808.    attribute in an entry.
  809.  
  810. 8.1.  Stepping through a set of entries
  811.  
  812.    The ldap_first_entry() and ldap_next_entry() routines are used to
  813.    step through a set of entries in a search result.
  814.    ldap_count_entries() is used to count the number of entries returned.
  815.  
  816.            LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
  817.  
  818.            LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
  819.  
  820.            int ldap_count_entries( LDAP *ld, LDAPMessage *res );
  821.  
  822.    Parameters are:
  823.  
  824.    ld     The connection handle;
  825.  
  826.    res    The search result, as obtained by a call to one of the syn-
  827.           chronous search routines or ldap_result();
  828.  
  829.    entry  The entry returned by a previous call to ldap_first_entry() or
  830.           ldap_next_entry().
  831.  
  832.    ldap_first_entry() and ldap_next_entry() will return NULL when no
  833.    more entries exist to be returned. NULL is also returned if an error
  834.    occurs while stepping through the entries, in which case the ld_errno
  835.    field of the ld connection handle will be set to indicate the error.
  836.  
  837.    ldap_count_entries() returns the number of entries contained in a
  838.    chain of entries. It can also be used to count the number of entries
  839.  
  840.  
  841.  
  842. Howes & Smith                Informational                     [Page 15]
  843.  
  844. RFC 1823                        LDAP API                     August 1995
  845.  
  846.  
  847.    that remain in a chain if called with an entry returned by
  848.    ldap_first_entry() or ldap_next_entry().
  849.  
  850. 8.2.  Stepping through the attributes of an entry
  851.  
  852.    The ldap_first_attribute() and ldap_next_attribute() calls are used
  853.    to step through the list of attribute types returned with an entry.
  854.  
  855.            char *ldap_first_attribute(
  856.                    LDAP            *ld,
  857.                    LDAPMessage     *entry,
  858.                    void            **ptr
  859.            );
  860.            char *ldap_next_attribute(
  861.                    LDAP            *ld,
  862.                    LDAPMessage     *entry,
  863.                    void            *ptr
  864.            );
  865.  
  866.    Parameters are:
  867.  
  868.    ld     The connection handle;
  869.  
  870.    entry  The entry whose attributes are to be stepped through, as
  871.           returned by ldap_first_entry() or ldap_next_entry();
  872.  
  873.    ptr    In ldap_first_attribute(), the address of a pointer used
  874.           internally to keep track of the current position in the entry.
  875.           In ldap_next_attribute(), the pointer returned by a previous
  876.           call to ldap_first_attribute().
  877.  
  878.    ldap_first_attribute() and ldap_next_attribute() will return NULL
  879.    when the end of the attributes is reached, or if there is an error,
  880.    in which case the ld_errno field in the ld connection handle will be
  881.    set to indicate the error.
  882.  
  883.    Both routines return a pointer to a per-connection buffer containing
  884.    the current attribute name. This should be treated like static data.
  885.    ldap_first_attribute() will allocate and return in ptr a pointer to a
  886.    BerElement used to keep track of the current position. This pointer
  887.    should be passed in subsequent calls to ldap_next_attribute() to step
  888.    through the entry's attributes.
  889.  
  890.    The attribute names returned are suitable for passing in a call to
  891.    ldap_get_values() and friends to retrieve the associated values.
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898. Howes & Smith                Informational                     [Page 16]
  899.  
  900. RFC 1823                        LDAP API                     August 1995
  901.  
  902.  
  903. 8.3.  Retrieving the values of an attribute
  904.  
  905.    ldap_get_values() and ldap_get_values_len() are used to retrieve the
  906.    values of a given attribute from an entry. ldap_count_values() and
  907.    ldap_count_values_len() are used to count the returned values.
  908.    ldap_value_free() and ldap_value_free_len() are used to free the
  909.    values.
  910.  
  911.            typedef struct berval {
  912.                    unsigned long   bv_len;
  913.                    char            *bv_val;
  914.            };
  915.  
  916.            char **ldap_get_values(
  917.                    LDAP            *ld,
  918.                    LDAPMessage     *entry,
  919.                    char            *attr
  920.            );
  921.  
  922.            struct berval **ldap_get_values_len(
  923.                    LDAP            *ld,
  924.                    LDAPMessage     *entry,
  925.                    char            *attr
  926.            );
  927.  
  928.            int ldap_count_values( char **vals );
  929.  
  930.            int ldap_count_values_len( struct berval **vals );
  931.  
  932.            int ldap_value_free( char **vals );
  933.  
  934.            int ldap_value_free_len( struct berval **vals );
  935.  
  936.    Parameters are:
  937.  
  938.    ld     The connection handle;
  939.  
  940.    entry  The entry from which to retrieve values, as returned by
  941.           ldap_first_entry() or ldap_next_entry();
  942.  
  943.    attr   The attribute whose values are to be retrieved, as returned by
  944.           ldap_first_attribute() or ldap_next_attribute(), or a caller-
  945.           supplied string (e.g., "mail");
  946.  
  947.    vals   The values returned by a previous call to ldap_get_values() or
  948.           ldap_get_values_len().
  949.  
  950.  
  951.  
  952.  
  953.  
  954. Howes & Smith                Informational                     [Page 17]
  955.  
  956. RFC 1823                        LDAP API                     August 1995
  957.  
  958.  
  959.    Two forms of the various calls are provided. The first form is only
  960.    suitable for use with non-binary character string data only. The
  961.    second _len form is used with any kind of data.
  962.  
  963.    Note that the values returned are malloc'ed and should be freed by
  964.    calling either ldap_value_free() or ldap_value_free_len() when no
  965.    longer in use.
  966.  
  967. 8.4.  Retrieving the name of an entry
  968.  
  969.    ldap_get_dn() is used to retrieve the name of an entry.
  970.    ldap_explode_dn() is used to break up the name into its component
  971.    parts. ldap_dn2ufn() is used to convert the name into a more "user
  972.    friendly" format.
  973.  
  974.            char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
  975.  
  976.            char **ldap_explode_dn( char *dn, int notypes );
  977.  
  978.            char *ldap_dn2ufn( char *dn );
  979.  
  980.    Parameters are:
  981.  
  982.    ld      The connection handle;
  983.  
  984.    entry   The entry whose name is to be retrieved, as returned by
  985.            ldap_first_entry() or ldap_next_entry();
  986.  
  987.    dn      The dn to explode, as returned by ldap_get_dn();
  988.  
  989.    notypes A boolean parameter, if non-zero indicating that the dn com-
  990.            ponents should have their type information stripped off
  991.            (i.e., "cn=Babs" would become "Babs").
  992.  
  993.    ldap_get_dn() will return NULL if there is some error parsing the dn,
  994.    setting ld_errno in the ld connection handle to indicate the error.
  995.    It returns a pointer to malloc'ed space that the caller should free
  996.    by calling free() when it is no longer in use.  Note the format of
  997.    the DNs returned is given by [4].
  998.  
  999.    ldap_explode_dn() returns a char * array containing the RDN
  1000.    components of the DN supplied, with or without types as indicated by
  1001.    the notypes parameter. The array returned should be freed when it is
  1002.    no longer in use by calling ldap_value_free().
  1003.  
  1004.    ldap_dn2ufn() converts the DN into the user friendly format described
  1005.    in [5]. The UFN returned is malloc'ed space that should be freed by a
  1006.    call to free() when no longer in use.
  1007.  
  1008.  
  1009.  
  1010. Howes & Smith                Informational                     [Page 18]
  1011.  
  1012. RFC 1823                        LDAP API                     August 1995
  1013.  
  1014.  
  1015. 9.  Security Considerations
  1016.  
  1017.    LDAP supports minimal security during connection authentication.
  1018.  
  1019. 10.  Acknowledgements
  1020.  
  1021.    This material is based upon work supported by the National Science
  1022.    Foundation under Grant No. NCR-9416667.
  1023.  
  1024. 11.  Bibliography
  1025.  
  1026.    [1] The Directory: Selected Attribute Syntaxes.  CCITT,
  1027.        Recommendation X.520.
  1028.  
  1029.    [2] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The String
  1030.        Representation of Standard Attribute Syntaxes", University of
  1031.        Michigan, ISODE Consortium, Performance Systems International,
  1032.        NeXor Ltd., RFC 1778, March 1995.
  1033.  
  1034.    [3] Howes, T., "A String Representation of LDAP Search Filters", RFC
  1035.        1558, University of Michigan, December 1993.
  1036.  
  1037.    [4] Kille, S., "A String Representation of Distinguished Names", RFC
  1038.        1779, ISODE Consortium, March 1995.
  1039.  
  1040.    [5] Kille, S., "Using the OSI Directory to Achieve User Friendly
  1041.        Naming",  RFC 1781, ISODE Consortium, March 1995.
  1042.  
  1043.    [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer, "Kerberos
  1044.        Authentication and Authorization System", MIT Project Athena
  1045.        Documentation Section  E.2.1, December 1987
  1046.  
  1047.    [7] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access
  1048.        Protocol," RFC 1777, Performance Systems International,
  1049.        University of Michigan, ISODE Consortium, March 1995.
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066. Howes & Smith                Informational                     [Page 19]
  1067.  
  1068. RFC 1823                        LDAP API                     August 1995
  1069.  
  1070.  
  1071. 12.  Authors' Addresses
  1072.  
  1073.        Tim Howes
  1074.        University of Michigan
  1075.        ITD Research Systems
  1076.        535 W William St.
  1077.        Ann Arbor, MI 48103-4943
  1078.        USA
  1079.  
  1080.        Phone: +1 313 747-4454
  1081.        EMail: tim@umich.edu
  1082.  
  1083.  
  1084.        Mark Smith
  1085.        University of Michigan
  1086.        ITD Research Systems
  1087.        535 W William St.
  1088.        Ann Arbor, MI 48103-4943
  1089.        USA
  1090.  
  1091.        Phone: +1 313 764-2277
  1092.        EMail: mcs@umich.edu
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122. Howes & Smith                Informational                     [Page 20]
  1123.  
  1124. RFC 1823                        LDAP API                     August 1995
  1125.  
  1126.  
  1127. 13.  Appendix A - Sample LDAP API Code
  1128.  
  1129.    #include <ldap.h>
  1130.  
  1131.    main()
  1132.    {
  1133.            LDAP            *ld;
  1134.            LDAPMessage     *res, *e;
  1135.            int             i;
  1136.            char            *a, *dn;
  1137.            void            *ptr;
  1138.            char            **vals;
  1139.  
  1140.            /* open a connection */
  1141.            if ( (ld = ldap_open( "dotted.host.name", LDAP_PORT ))
  1142.                    == NULL )
  1143.                    exit( 1 );
  1144.  
  1145.            /* authenticate as nobody */
  1146.            if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
  1147.                    ldap_perror( ld, "ldap_simple_bind_s" );
  1148.                    exit( 1 );
  1149.            }
  1150.  
  1151.            /* search for entries with cn of "Babs Jensen",
  1152.                    return all attrs  */
  1153.            if ( ldap_search_s( ld, "o=University of Michigan, c=US",
  1154.                LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
  1155.                != LDAP_SUCCESS ) {
  1156.                    ldap_perror( ld, "ldap_search_s" );
  1157.                    exit( 1 );
  1158.            }
  1159.  
  1160.            /* step through each entry returned */
  1161.            for ( e = ldap_first_entry( ld, res ); e != NULL;
  1162.                e = ldap_next_entry( ld, e ) ) {
  1163.                    /* print its name */
  1164.                    dn = ldap_get_dn( ld, e );
  1165.                    printf( "dn: %s0, dn );
  1166.                    free( dn );
  1167.  
  1168.                    /* print each attribute */
  1169.                    for ( a = ldap_first_attribute( ld, e, &ptr );
  1170.                            a != NULL;
  1171.                        a = ldap_next_attribute( ld, e, ptr ) ) {
  1172.                            printf( "attribute: %s0, a );
  1173.  
  1174.                            /* print each value */
  1175.  
  1176.  
  1177.  
  1178. Howes & Smith                Informational                     [Page 21]
  1179.  
  1180. RFC 1823                        LDAP API                     August 1995
  1181.  
  1182.  
  1183.                            vals = ldap_get_values( ld, e, a );
  1184.                            for ( i = 0; vals[i] != NULL; i++ ) {
  1185.                                    printf( "value: %s0, vals[i] );
  1186.                            }
  1187.                            ldap_value_free( vals );
  1188.                    }
  1189.            }
  1190.            /* free the search results */
  1191.            ldap_msgfree( res );
  1192.  
  1193.            /* close and free connection resources */
  1194.            ldap_unbind( ld );
  1195.    }
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234. Howes & Smith                Informational                     [Page 22]
  1235.  
  1236.