Network Working Group M. Smith, Editor INTERNET-DRAFT Netscape Communications Corp. Intended Category: Standards Track T. Howes Obsoletes: RFC 1823 Netscape Communications Corp. Expires: 7 February 1999 A. Herron Microsoft Corp. C. Weider Microsoft Corp. M. Wahl Critical Angle, Inc. A. Anantha Microsoft Corp. 7 August 1998 The C LDAP Application Program Interface 1. Status of this Memo 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 . Please send editorial comments directly to the authors. This document is an Internet-Draft. 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." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), or ftp.isi.edu (US West Coast). Copyright (C) The Internet Society (1998). All Rights Reserved. Please see the Copyright section near the end of this document for more information. Expires: 7 February 1999 [Page 1] C LDAP API The C LDAP Application Program Interface 7 August 1998 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 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 an appendix that provides some example code demon- strating the use of the API. 3. Table of Contents 1. Status of this Memo............................................1 2. Introduction...................................................2 3. Table of Contents..............................................2 4. Overview of the LDAP Model.....................................3 5. Overview of LDAP API Use.......................................4 6. Common Data Structures.........................................5 7. Retrieving Information About the API Implementation............6 7.1. Retrieving Information at Compile Time......................6 7.2. Retrieving Information During Execution.....................7 8. LDAP Error Codes...............................................9 9. Performing LDAP Operations.....................................10 9.1. Initializing an LDAP Session................................10 9.2. LDAP Session Handle Options.................................11 9.3. Working with controls.......................................15 9.4. Authenticating to the directory.............................16 9.5. Closing the session.........................................19 9.6. Searching...................................................19 9.7. Reading an Entry............................................23 9.8. Listing the Children of an Entry............................23 9.9. Comparing a Value Against an Entry..........................23 9.10. Modifying an entry..........................................25 9.11. Modifying the Name of an Entry..............................28 9.12. Adding an entry.............................................30 9.13. Deleting an entry...........................................31 9.14. Extended Operations.........................................33 10. Abandoning An Operation........................................34 11. Obtaining Results and Peeking Inside LDAP Messages.............35 12. Handling Errors and Parsing Results............................37 Expires: 7 February 1999 [Page 2] C LDAP API The C LDAP Application Program Interface 7 August 1998 13. Stepping Through a List of Results.............................40 14. Parsing Search Results.........................................41 14.1. Stepping Through a List of Entries..........................41 14.2. Stepping Through the Attributes of an Entry.................42 14.3. Retrieving the Values of an Attribute.......................43 14.4. Retrieving the name of an entry.............................44 14.5. Retrieving controls from an entry...........................45 14.6. Parsing References..........................................46 15. Encoded ASN.1 Value Manipulation...............................47 15.1. General.....................................................47 15.2. Encoding....................................................48 15.3. Encoding Example............................................51 15.4. Decoding....................................................52 15.5. Decoding Example............................................54 16. Security Considerations........................................56 17. Acknowledgements...............................................57 18. Copyright......................................................57 19. Bibliography...................................................58 20. Authors' Addresses.............................................58 21. Appendix A - Sample LDAP API Code..............................59 22. Appendix B - Namespace Consumed By This Specification..........61 23. Appendix C - Outstanding Issues................................61 23.1. Support for multithreaded applications......................61 23.2. Using Transport Layer Security (TLS)........................62 23.3. Client control for chasing referrals........................62 23.4. Potential confusion between hostname:port and IPv6 addresses62 23.5. Need to track SASL API standardization efforts..............62 23.6. Support for character sets other than UTF-8?................62 23.7. LDAP Session Handle Options.................................62 23.8. Re-bind function is not sufficiently general purpose........63 23.9. LDAP C API extension mechanism should be clearly specified..63 24. Appendix D - Changes Made Since Last Document Revision.........63 24.1. API Changes.................................................63 24.2. Editorial changes...........................................64 4. Overview of the LDAP Model LDAP is the lightweight directory access protocol, described in [2] and [6]. 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 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 Expires: 7 February 1999 [Page 3] C LDAP API The C LDAP Application Program Interface 7 August 1998 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 [4]. 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 An application generally uses the C LDAP API in four simple steps. - Initialize an LDAP session with a primary LDAP server. The ldap_init() function returns a handle to the session, allowing mul- tiple connections to be open at once. - Authenticate to the LDAP server. The ldap_bind() function and friends support a variety of authentication methods. - 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. - 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 Expires: 7 February 1999 [Page 4] C LDAP API The C LDAP Application Program Interface 7 August 1998 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 error 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(). 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 may return referrals to other servers. By default, implementations of this API will attempt to follow referrals automatically for the application. This behavior can be disabled glo- bally (using the ldap_set_option() call) or on a per-request basis through the use of a client control. As in the LDAPv3 protocol itself, all DNs and string values that are passed into or produced by the C LDAP API are represented as UTF-8[10] characters. Some LDAP API implementations may support other character sets, but the mechanisms used are not currently specified in this docu- ment. 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. 6. Common Data Structures Some data structures that are common to several LDAP API functions are defined here: typedef struct ldap LDAP; typedef struct ldapmsg LDAPMessage; struct berval { unsigned long bv_len; char *bv_val; }; struct timeval { Expires: 7 February 1999 [Page 5] C LDAP API The C LDAP Application Program Interface 7 August 1998 long tv_sec; long 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 may 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 may 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 berval structure is used to represent arbitrary binary data and its fields have the following meanings: bv_len Length of data in bytes. bv_val A pointer to the data itself. The timeval structure is used to represent an interval of time and its fields have the following meanings: tv_sec Seconds component of time interval. tv_usec Microseconds component of time interval. 7. 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. 7.1. Retrieving Information at Compile Time All conformant implementations MUST include the following definition in a header file so compile time tests can be done by LDAP software developers: Expires: 7 February 1999 [Page 6] C LDAP API The C LDAP Application Program Interface 7 August 1998 #define LDAP_API_VERSION level where "level" is replaced with the RFC number given to this LDAP C API specification when it is published as a standards track RFC. For exam- ple, if this specification is published as RFC 88888, conformant imple- mentations will include a macro definition like this: #define LDAP_API_VERSION 88888 and application code can test the LDAP C API version level using a construct such as this one: #if (LDAP_API_VERSION > 88888) /* use features supported in RFC 88888 or later */ #endif 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 LDAP C 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 may 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. 7.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() MUST be the address of an Expires: 7 February 1999 [Page 7] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAPAPIInfo structure which is defined as follows: typedef struct ldapapiinfo { int ldapai_info_version; /* version of LDAPAPIInfo (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 *ldapi_vendor_name; /* name of supplier */ int ldapai_vendor_version; /* supplier-specific version times 100 */ } LDAPAPIInfo; Note that the ldapai_info_version field of the LDAPAPIInfo MUST be set to the value 1 before calling ldap_get_option(). 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 MUST be set to the value 1 before calling ldap_get_option(). ldapai_api_version A number that matches that assigned to the LDAP C 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_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 LDAP C API extensions. If no API extensions are supported, this field will be set to NULL. The caller is reponsible for disposing of the memory occupied by this array by passing it to ldap_value_free() which is described later in this docu- ment. ldapi_vendor_name A zero-terminated string that contains the name of the party that produced the LDAP API implementation. This field may be Expires: 7 February 1999 [Page 8] C LDAP API The C LDAP Application Program Interface 7 August 1998 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. 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. 8. LDAP Error Codes Many of the LDAP API routines return LDAP error codes, some of which indicate local errors and some of which may be returned by servers. All of the LDAP error codes returned will be positive integers. Supported error codes are (hexadecimal values are given in parentheses after the constant): LDAP_SUCCESS (0x00) LDAP_OPERATIONS_ERROR (0x01) LDAP_PROTOCOL_ERROR (0x02) LDAP_TIMELIMIT_EXCEEDED (0x03) LDAP_SIZELIMIT_EXCEEDED (0x04) LDAP_COMPARE_FALSE (0x05) LDAP_COMPARE_TRUE (0x06) LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) LDAP_STRONG_AUTH_REQUIRED (0x08) LDAP_REFERRAL (0x0a) -- new in LDAPv3 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3 LDAP_NO_SUCH_ATTRIBUTE (0x10) LDAP_UNDEFINED_TYPE (0x11) LDAP_INAPPROPRIATE_MATCHING (0x12) LDAP_CONSTRAINT_VIOLATION (0x13) LDAP_TYPE_OR_VALUE_EXISTS (0x14) LDAP_INVALID_SYNTAX (0x15) LDAP_NO_SUCH_OBJECT (0x20) LDAP_ALIAS_PROBLEM (0x21) LDAP_INVALID_DN_SYNTAX (0x22) LDAP_IS_LEAF (0x23) -- not used in LDAPv3 LDAP_ALIAS_DEREF_PROBLEM (0x24) LDAP_INAPPROPRIATE_AUTH (0x30) LDAP_INVALID_CREDENTIALS (0x31) LDAP_INSUFFICIENT_ACCESS (0x32) Expires: 7 February 1999 [Page 9] C LDAP API The C LDAP Application Program Interface 7 August 1998 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) 9. Performing LDAP Operations This section describes each LDAP operation API call in detail. All func- tions take a "session handle," a pointer to an LDAP structure containing per-connection information. Many routines return results in an LDAPMes- sage structure. These structures and others are described as needed below. 9.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( Expires: 7 February 1999 [Page 10] C LDAP API The C LDAP Application Program Interface 7 August 1998 char *hostname, int portno ); Use of the following routine is deprecated. 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. Each hostname in the list can include an optional port number which is separated from the host itself with a colon (:) character. The hosts are tried in the order listed, stopping with the first one to which a successful connection is made. Note that only ldap_open() attempts to make the connec- tion before returning to the caller. ldap_init() does not con- nect to the LDAP server. portno Contains the TCP port number to connect to. The default LDAP port of 389 can be obtained by supplying the constant LDAP_PORT. If a host includes a port number then this parame- ter is ignored. ldap_init() and ldap_open() both return a "session handle," a pointer to an opaque structure that should 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 must be completed before other operations can be performed on the session. LDAPv3 does not require that a bind operation be completed before other operations can be performed. The calling program can set various attributes of the session by calling the routines described in the next section. 9.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. Formerly, this data type was a structure exposed to the caller, and various fields in the Expires: 7 February 1999 [Page 11] C LDAP API The C LDAP Application Program Interface 7 August 1998 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. int ldap_get_option( LDAP *ld, int option, void *outvalue ); int ldap_set_option( LDAP *ld, int option, void *invalue ); 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_DESC (0x01) Type for invalue parameter: not applicable (option is READ-ONLY) Type for outvalue parameter: int * Description: The underlying socket descriptor corresponding to the primary LDAP connection. This option is READ-ONLY and cannot be set. LDAP_OPT_DEREF (0x02) Type for invalue parameter: int * Expires: 7 February 1999 [Page 12] C LDAP API The C LDAP Application Program Interface 7 August 1998 Type for outvalue parameter: int * Description: Determines how aliases are handled during search. It can have one of the following values: LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value means aliases should be dereferenced during the search but not when locating the base object of the search. The LDAP_DEREF_FINDING value means aliases should be dereferenced when locating the base object but not during the search. LDAP_OPT_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. 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 LDAP_OPT_REFERRALS (0x08) Type for invalue parameter: int (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 can be set to one of the constants LDAP_OPT_ON (1) or LDAP_OPT_OFF (0). LDAP_OPT_RESTART (0x09) Type for invalue parameter: int (LDAP_OPT_ON or LDAP_OPT_OFF) Type for outvalue parameter: int * Description: Determines whether LDAP I/O operations should automatically be restarted if they abort prematurely. It should be set to Expires: 7 February 1999 [Page 13] C LDAP API The C LDAP Application Program Interface 7 August 1998 one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. This option is useful if an LDAP I/O operation may be interrupted prema- turely, for example by a timer going off, or other interrupt. 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 must be one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3). If no version is set the default is LDAP_VERSION2 (2). LDAP_OPT_SERVER_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 Using 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 Using Controls section below. LDAP_OPT_HOST_NAME (0x30) Type for invalue parameter: char * Type for outvalue parameter: char ** Description: The host name (or list of host) for the primary LDAP server. LDAP_OPT_ERROR_NUMBER (0x31) Type for invalue parameter: int * Type for outvalue parameter: int * Description: The code of the most recent LDAP error that occurred for this Expires: 7 February 1999 [Page 14] C LDAP API The C LDAP Application Program Interface 7 August 1998 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. 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 pointer to data that is associated with the LDAP session ld is returned; there is no need to dispose of the memory by calling ldap_memfree() or ldap_controls_free(). invalue A pointer to the value the option is to be given. The actual type of this parameter depends on the setting of the option parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be given for options that have on or off settings. Both ldap_get_option() and ldap_set_option() return 0 if successful and -1 if an error occurs. 9.3. Working with controls LDAPv3 operations can be extended through the use of controls. Controls may be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls. The LDAP API also supports a client-side extension mechanism through the use of client controls. These controls affect the behavior of the LDAP API only and are never sent to a server. A common data structure is used to represent both types of controls: typedef struct ldapcontrol { char *ldctl_oid; struct berval ldctl_value; char ldctl_iscritical; } LDAPControl, *PLDAPControl; The fields in the ldapcontrol structure have the following meanings: ldctl_oid The control type, represented as a string. Expires: 7 February 1999 [Page 15] C LDAP API The C LDAP Application Program Interface 7 August 1998 ldctl_value The data associated with the control (if any). To specify a zero-length value, set ldctl_value.bv_len to zero and ldctl_value.bv_val to a zero-length string. To indicate that no data is associated with the con- trol, set ldctl_value.bv_val to NULL. ldctl_iscritical Indicates whether the control is critical of not. If this field is non-zero, the operation will only be car- ried out if the control is recognized by the server and/or client. Some LDAP API calls allocate an ldapcontrol structure or a NULL- terminated array of ldapcontrol structures. The following routines can be used to dispose of a single control or an array of controls: void ldap_control_free( LDAPControl *ctrl ); void ldap_controls_free( LDAPControl **ctrls ); A set of controls that affect the entire session can be set using the ldap_set_option() function (see above). A list of controls can also be passed directly to some LDAP API calls such as ldap_search_ext(), in which case any controls set for the session through the use of ldap_set_option() are ignored. Control lists are represented as a NULL- terminated array of pointers to ldapcontrol structures. Server controls are defined by LDAPv3 protocol extension documents; for example, a control has been proposed to support server-side sorting of search results [7]. No client controls are defined by this document but they may be defined in future revisions or in any document that extends this API. 9.4. Authenticating to the directory The following functions are used to authenticate an LDAP client to an LDAP directory server. The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do general and extensible authentication over LDAP through the use of the Simple Authentication Security Layer [8]. The routines both take the dn to bind as, the method to use, as a dotted-string representation of an OID identifying the method, and a struct berval holding the credentials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to request simple authentication, or the simplified routines ldap_simple_bind() or ldap_simple_bind_s() can be used. int ldap_sasl_bind( Expires: 7 February 1999 [Page 16] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAP *ld, char *dn, char *mechanism, struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_sasl_bind_s( LDAP *ld, char *dn, char *mechanism, struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, struct berval **servercredp ); int ldap_simple_bind( LDAP *ld, char *dn, char *passwd ); int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd ); The use of the following routines is deprecated: int ldap_bind( LDAP *ld, char *dn, char *cred, int method ); int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method ); int ldap_kerberos_bind( LDAP *ld, char *dn ); int ldap_kerberos_bind_s( LDAP *ld, char *dn ); Parameters are: ld The session handle. dn The name of the entry to bind as. mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple Expires: 7 February 1999 [Page 17] C LDAP API The C LDAP Application Program Interface 7 August 1998 authentication, or a text string identifying the SASL method. cred The credentials with which to authenticate. Arbitrary credentials can be passed using this parameter. The format and content of the credentials depends on the setting of the mechanism parameter. passwd For ldap_simple_bind(), the password to compare to the entry's userPassword attribute. serverctrls List of LDAP server controls. clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_sasl_bind() call succeeds. servercredp This result parameter will be filled in with the creden- tials passed back by the server for mutual authentication, if given. An allocated berval structure is returned that should be disposed of by calling ber_bvfree(). NULL may be passed to ignore this field. Additional parameters for the deprecated routines are not described. Interested readers are referred to RFC 1823. The ldap_sasl_bind() function initiates an asynchronous bind operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_sasl_bind() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the bind. The ldap_simple_bind() function initiates a simple asynchronous bind operation and returns the message id of the operation initiated. A sub- sequent call to ldap_result(), described below, can be used to obtain the result of the bind. In case of error, ldap_simple_bind() will return -1, setting the session error parameters in the LDAP structure appropri- ately. The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more informa- tion about possible errors and how to interpret them. Expires: 7 February 1999 [Page 18] C LDAP API The C LDAP Application Program Interface 7 August 1998 Note that if an LDAPv2 server is contacted, no other operations over the connection should be attempted before a bind call has successfully com- pleted. Subsequent bind calls can be used to re-authenticate over the same con- nection, and multistep SASL sequences can be accomplished through a sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). 9.5. Closing the session The following functions are used to unbind from the directory, close the connection, and dispose of the session handle. int ldap_unbind( LDAP *ld ); int ldap_unbind_s( LDAP *ld ); Parameters are: ld The session handle. ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding from the directory, closing the connection, and freeing up the ld struc- ture before returning. There is no server response to an unbind opera- tion. 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() or ldap_unbind_s(), the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld. 9.6. Searching The following functions are used to search the LDAP directory, returning a requested set of attributes for each entry matched. There are five variations. int ldap_search_ext( LDAP *ld, char *base, int scope, char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeout, Expires: 7 February 1999 [Page 19] C LDAP API The C LDAP Application Program Interface 7 August 1998 int sizelimit, int *msgidp ); int ldap_search_ext_s( LDAP *ld, char *base, int scope, char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeout, int sizelimit, LDAPMessage **res ); int ldap_search( LDAP *ld, char *base, int scope, char *filter, char **attrs, int attrsonly ); int ldap_search_s( LDAP *ld, char *base, 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 ); Expires: 7 February 1999 [Page 20] C LDAP API The C LDAP Application Program Interface 7 August 1998 Parameters are: ld The session handle. base The dn of the entry at which to start the search. scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the search. filter A character string as described in [3], representing the search filter. The value NULL can be passed to indicate that the filter "(objectclass=*)" which matches all entries should be used. attrs A NULL-terminated array of strings indicating which attri- butes to return for each matching entry. Passing NULL for this parameter causes all available user attributes to be retrieved. The special constant string LDAP_NO_ATTRS ("1.1") can be used as the only in the array to indicate that no attribute types should be returned by the server. The special constant string LDAP_ALL_USER_ATTRS ("*") can be used in the attrs array along with the names of some operational attributes to indicate that all user attributes plus the listed operational attributes should be returned. attrsonly A boolean value that should be zero if both attribute types and values are to be returned, non-zero if only types are wanted. timeout For the ldap_search_st() function, this specifies the local search timeout value (if it is NULL, the timeout is infin- ite). For the ldap_search_ext() and ldap_search_ext_s() functions, this specifies both the local search timeout value and the operation time limit that is sent to the server within the search request. For the ldap_search_ext() and ldap_search_ext_s() functions, pass- ing a NULL value for timeout causes the global default timeout stored in the LDAP session handle to be used (set by using ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter). sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls, this is a limit on the number of entries to return from the search. A value of LDAP_NO_LIMIT (0) means no limit. res For the synchronous calls, this is a result parameter which will contain the results of the search upon completion of Expires: 7 February 1999 [Page 21] C LDAP API The C LDAP Application Program Interface 7 August 1998 the call. serverctrls List of LDAP server controls. clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_search_ext() call succeeds. There are three options in the session handle ld which potentially affect how the search is performed. They are: LDAP_OPT_SIZELIMIT A limit on the number of entries to return from the search. A value of LDAP_NO_LIMIT (0) means no limit. Note that the value from the session handle is ignored when using the ldap_search_ext() or ldap_search_ext_s() functions. LDAP_OPT_TIMELIMIT A limit on the number of seconds to spend on the search. A value of LDAP_NO_LIMIT (0) means no limit. Note that the value from the session handle is ignored when using the ldap_search_ext() or ldap_search_ext_s() functions. LDAP_OPT_DEREF One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS (0x03), specifying how aliases should be handled during the search. The LDAP_DEREF_SEARCHING value means aliases should be dereferenced during the search but not when locating the base object of the search. The LDAP_DEREF_FINDING value means aliases should be dereferenced when locating the base object but not during the search. The ldap_search_ext() function initiates an asynchronous search opera- tion and returns the constant LDAP_SUCCESS if the request was success- fully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_search_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the results from the search. These results can be parsed using the result parsing routines described in detail later. Similar to ldap_search_ext(), the ldap_search() function initiates an asynchronous search operation and returns the message id of the opera- tion initiated. As for ldap_search_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the Expires: 7 February 1999 [Page 22] C LDAP API The C LDAP Application Program Interface 7 August 1998 bind. In case of error, ldap_search() will return -1, setting the ses- sion error parameters in the LDAP structure appropriately. The synchronous ldap_search_ext_s(), ldap_search_s(), and ldap_search_st() functions all return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about possible errors and how to interpret them. Entries returned from the search (if any) are contained in the res parameter. This parameter is opaque to the caller. Entries, attri- butes, 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. The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 server controls, client controls, and allow varying size and time limits to be easily specified for each search operation. The ldap_search_st() function is identical to ldap_search_s() except that it takes an addi- tional parameter specifying a local timeout for the search. The local search timeout is used to limit the amount of time the API implementa- tion will wait for a search to complete. After the local search timeout expires, the API implementation will send an abandon operation to abort the search operation. 9.7. 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=*)" or NULL. attrs contains the list of attributes to return. 9.8. 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=*)" or NULL. attrs contains the list of attributes to return for each child entry. 9.9. Comparing a Value Against an Entry The following routines are used to compare a given attribute value assertion against an LDAP entry. There are four variations: int ldap_compare_ext( LDAP *ld, char *dn, Expires: 7 February 1999 [Page 23] C LDAP API The C LDAP Application Program Interface 7 August 1998 char *attr, struct berval *bvalue LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_compare_ext_s( LDAP *ld, char *dn, char *attr, struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_compare( LDAP *ld, char *dn, char *attr, char *value ); int ldap_compare_s( LDAP *ld, char *dn, char *attr, char *value ); Parameters are: ld The session handle. dn The name of the entry to compare against. attr The attribute to compare against. bvalue The attribute value to compare against those found in the given entry. This parameter is used in the extended rou- tines and is a pointer to a struct berval so it is possible to compare binary values. value A string attribute value to compare against, used by the ldap_compare() and ldap_compare_s() functions. Use ldap_compare_ext() or ldap_compare_ext_s() if you need to compare binary values. Expires: 7 February 1999 [Page 24] C LDAP API The C LDAP Application Program Interface 7 August 1998 serverctrls List of LDAP server controls. clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_compare_ext() call succeeds. The ldap_compare_ext() function initiates an asynchronous compare opera- tion and returns the constant LDAP_SUCCESS if the request was success- fully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_compare_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the compare. Similar to ldap_compare_ext(), the ldap_compare() function initiates an asynchronous compare operation and returns the message id of the opera- tion initiated. As for ldap_compare_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the bind. In case of error, ldap_compare() will return -1, setting the ses- sion error parameters in the LDAP structure appropriately. The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both return the result of the operation, either the 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 pos- sible errors and how to interpret them. The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 server controls and client controls. 9.10. Modifying an entry The following routines are used to modify an existing LDAP entry. There are four variations: typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals Expires: 7 February 1999 [Page 25] C LDAP API The C LDAP Application Program Interface 7 August 1998 int ldap_modify_ext( LDAP *ld, char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_modify_ext_s( LDAP *ld, char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_modify( LDAP *ld, char *dn, LDAPMod **mods ); int ldap_modify_s( LDAP *ld, char *dn, LDAPMod **mods ); Parameters are: ld The session handle. dn The name of the entry to modify. mods A NULL-terminated array of modifications to make to the entry. serverctrls List of LDAP server controls. clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_modify_ext() call succeeds. The fields in the LDAPMod structure have the following meanings: mod_op The modification operation to perform. It should be one of Expires: 7 February 1999 [Page 26] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or LDAP_MOD_REPLACE (0x02). This field also indicates the type of values included in the mod_vals union. It is logi- cally ORed with LDAP_MOD_BVALUES (0x80) to select the mod_bvalues form. Otherwise, the mod_values form is used. mod_type The type of the attribute to modify. mod_vals The values (if any) to add, delete, or replace. Only one of the mod_values or mod_bvalues variants should be used, selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of zero-terminated strings and mod_bvalues is a NULL- terminated array of berval structures that can be used to pass binary values such as images. For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary. For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the attribute if no values remain. If the entire attri- bute is to be deleted, the mod_vals field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary, or removed if the mod_vals field is NULL. All modifications are performed in the order in which they are listed. The ldap_modify_ext() function initiates an asynchronous modify opera- tion and returns the constant LDAP_SUCCESS if the request was success- fully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_modify_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the modify. Similar to ldap_modify_ext(), the ldap_modify() function initiates an asynchronous modify operation and returns the message id of the opera- tion initiated. As for ldap_modify_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the modify. In case of error, ldap_modify() will return -1, setting the ses- sion error parameters in the LDAP structure appropriately. The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about pos- sible errors and how to interpret them. Expires: 7 February 1999 [Page 27] C LDAP API The C LDAP Application Program Interface 7 August 1998 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 server controls and client controls. 9.11. Modifying the Name of an Entry In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to change the name of an LDAP entry. They could only be used to change the least significant component of a name (the RDN or relative distinguished name). LDAPv3 provides the Modify DN protocol operation that allows more general name change access. The ldap_rename() and ldap_rename_s() rou- tines are used to change the name of an entry, and the use of the ldap_modrdn() and ldap_modrdn_s() routines is deprecated. int ldap_rename( LDAP *ld, char *dn, char *newrdn, char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_rename_s( LDAP *ld, char *dn, char *newrdn, char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls ); Use of the following routines is deprecated. int ldap_modrdn( LDAP *ld, char *dn, char *newrdn, int deleteoldrdn ); int ldap_modrdn_s( LDAP *ld, char *dn, char *newrdn, int deleteoldrdn Expires: 7 February 1999 [Page 28] C LDAP API The C LDAP Application Program Interface 7 August 1998 ); Parameters are: ld The session handle. dn The name of the entry whose DN is to be changed. newrdn The new RDN to give the entry. newparent The new parent, or superior entry. If this parameter is NULL, only the RDN of the entry is changed. The root DN may be specified by passing a zero length string, "". The newparent parameter should always be NULL when using ver- sion 2 of the LDAP protocol; otherwise the server's behavior is undefined. deleteoldrdn This parameter only has meaning on the rename routines if newrdn is different than the old RDN. It is a boolean value, if non-zero indicating that the old RDN value(s) should be removed, if zero indicating that the old RDN value(s) should be retained as non-distinguished values of the entry. serverctrls List of LDAP server controls. clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_rename() call succeeds. The ldap_rename() function initiates an asynchronous modify DN operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_rename() places the DN message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the rename. The synchronous ldap_rename_s() returns the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about possible errors and how to interpret them. The ldap_rename() and ldap_rename_s() functions both support LDAPv3 server controls and client controls. Expires: 7 February 1999 [Page 29] C LDAP API The C LDAP Application Program Interface 7 August 1998 9.12. Adding an entry The following functions are used to add entries to the LDAP directory. There are four variations: int ldap_add_ext( LDAP *ld, char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_add_ext_s( LDAP *ld, char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_add( LDAP *ld, char *dn, LDAPMod **attrs ); int ldap_add_s( LDAP *ld, char *dn, LDAPMod **attrs ); Parameters are: ld The session handle. dn The name of the entry to add. attrs The entry's attributes, specified using the LDAPMod struc- ture defined for ldap_modify(). The mod_type and mod_vals fields should be filled in. The mod_op field is ignored unless ORed with the constant LDAP_MOD_BVALUES, used to select the mod_bvalues case of the mod_vals union. serverctrls List of LDAP server controls. Expires: 7 February 1999 [Page 30] C LDAP API The C LDAP Application Program Interface 7 August 1998 clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_add_ext() call succeeds. Note that the parent of the entry being added must already exist or the parent must be empty (i.e., equal to the root DN) for an add to succeed. The ldap_add_ext() function initiates an asynchronous add operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the section below on error han- dling for more information about possible errors and how to interpret them. If successful, ldap_add_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the add. Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- chronous add operation and returns the message id of the operation ini- tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the add. In case of error, ldap_add() will return -1, setting the session error parameters in the LDAP structure appropriately. The synchronous ldap_add_ext_s() and ldap_add_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about possible errors and how to interpret them. The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server controls and client controls. 9.13. Deleting an entry The following functions are used to delete a leaf entry from the LDAP directory. There are four variations: int ldap_delete_ext( LDAP *ld, char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_delete_ext_s( Expires: 7 February 1999 [Page 31] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAP *ld, char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_delete( LDAP *ld, char *dn ); int ldap_delete_s( LDAP *ld, char *dn ); Parameters are: ld The session handle. dn The name of the entry to delete. serverctrls List of LDAP server controls. clientctrls List of client controls. msgidp This result parameter will be set to the message id of the request if the ldap_delete_ext() call succeeds. Note that the entry to delete must be a leaf entry (i.e., it must have no children). Deletion of entire subtrees in a single operation is not supported by LDAP. The ldap_delete_ext() function initiates an asynchronous delete opera- tion and returns the constant LDAP_SUCCESS if the request was success- fully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_delete_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the delete. Similar to ldap_delete_ext(), the ldap_delete() function initiates an asynchronous delete operation and returns the message id of the opera- tion initiated. As for ldap_delete_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the delete. In case of error, ldap_delete() will return -1, setting the ses- sion error parameters in the LDAP structure appropriately. Expires: 7 February 1999 [Page 32] C LDAP API The C LDAP Application Program Interface 7 August 1998 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about pos- sible errors and how to interpret them. The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 server controls and client controls. 9.14. Extended Operations The ldap_extended_operation() and ldap_extended_operation_s() routines allow extended LDAP operations to be passed to the server, providing a general protocol extensibility mechanism. int ldap_extended_operation( LDAP *ld, char *exoid, struct berval *exdata, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_extended_operation_s( LDAP *ld, char *exoid, struct berval *exdata, LDAPControl **serverctrls, LDAPControl **clientctrls, char **retoidp, struct berval **retdatap ); Parameters are: ld The session handle. requestoid The dotted-OID text string naming the request. requestdata The arbitrary data required by the operation (if NULL, no data is sent to the server). serverctrls List of LDAP server controls. clientctrls List of client controls. Expires: 7 February 1999 [Page 33] C LDAP API The C LDAP Application Program Interface 7 August 1998 msgidp This result parameter will be set to the message id of the request if the ldap_extended_operation() call succeeds. retoidp Pointer to a character string that will be set to an allo- cated, dotted-OID text string returned by the server. This string should be disposed of using the ldap_memfree() func- tion. If no OID was returned, *retoidp is set to NULL. retdatap Pointer to a berval structure pointer that will be set an allocated copy of the data returned by the server. This struct berval should be disposed of using ber_bvfree(). If no data is returned, *retdatap is set to NULL. The ldap_extended_operation() function initiates an asynchronous extended operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the sec- tion below on error handling for more information about possible errors and how to interpret them. If successful, ldap_extended_operation() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the extended operation which can be passed to ldap_parse_extended_result() to obtain the OID and data contained in the response. The synchronous ldap_extended_operation_s() function returns the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about possible errors and how to interpret them. The retoid and retdata parameters are filled in with the OID and data from the response. If no OID or data was returned, these parameters are set to NULL. The ldap_extended_operation() and ldap_extended_operation_s() functions both support LDAPv3 server controls and client controls. 10. Abandoning An Operation The following calls are used to abandon an operation in progress: int ldap_abandon_ext( LDAP *ld, int msgid, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_abandon( LDAP *ld, Expires: 7 February 1999 [Page 34] C LDAP API The C LDAP Application Program Interface 7 August 1998 int msgid ); ld The session handle. msgid The message id of the request to be abandoned. serverctrls List of LDAP server controls. clientctrls List of client controls. ldap_abandon_ext() abandons the operation with message id msgid and returns the constant LDAP_SUCCESS if the abandon was successful or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. ldap_abandon() is identical to ldap_abandon_ext() except that it does not accept client or server controls and it returns zero if the abandon was successful, -1 otherwise and does not support LDAPv3 server controls or client controls. After a successful call to ldap_abandon() or ldap_abandon_ext(), results with the given message id are never returned from a subsequent call to ldap_result(). There is no server response to LDAP abandon operations. 11. Obtaining Results and Peeking Inside LDAP Messages ldap_result() is used to obtain the result of a previous asynchronously initiated operation. Note that depending on how it is called, ldap_result() may actually return a list or "chain" of result messages. Once a chain of messages has been returned to the caller, it is no longer tied in any caller-visible way to the LDAP request that produced it. Therefore, a chain of messages returned by calling ldap_result() or by calling a synchronous search routine will never be affected by subse- quent LDAP API calls (except for ldap_msgfree() which is used to dispose of a chain of messages). ldap_msgfree() frees the result messages (possibly an entire chain of messages) obtained from a previous call to ldap_result() or from a call to a synchronous search routine. ldap_msgtype() returns the type of an LDAP message. ldap_msgid() returns the message ID of an LDAP message. int ldap_result( LDAP *ld, Expires: 7 February 1999 [Page 35] C LDAP API The C LDAP Application Program Interface 7 August 1998 int msgid, int all, struct timeval *timeout, LDAPMessage **res ); int ldap_msgfree( LDAPMessage *res ); int ldap_msgtype( LDAPMessage *res ); int ldap_msgid( LDAPMessage *res ); Parameters are: ld The session handle. msgid The message id of the operation whose results are to be returned, or the constant LDAP_RES_ANY (-1) if any result is desired. all Specifies how many messages will be retrieved in a single call to ldap_result(). This parameter only has meaning for search results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one message at a time. Pass LDAP_MSG_ALL (0x01) to request that all results of a search be received before returning all results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to indicate that all results retrieved so far should be returned in the result chain. timeout A timeout specifying how long to wait for results to be returned. A NULL value causes ldap_result() to block until results are available. A timeout value of zero seconds speci- fies a polling behavior. res For ldap_result(), a result parameter that will contain the result(s) of the operation. For ldap_msgfree(), the result chain to be freed, obtained from a previous call to ldap_result(), ldap_search_s(), or ldap_search_st(). Upon successful completion, ldap_result() returns the type of the first result returned in the res parameter. This will be one of the following constants. LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 LDAP_RES_SEARCH_RESULT (0x65) LDAP_RES_MODIFY (0x67) Expires: 7 February 1999 [Page 36] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAP_RES_ADD (0x69) LDAP_RES_DELETE (0x6B) LDAP_RES_MODDN (0x6D) LDAP_RES_COMPARE (0x6F) LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 ldap_result() returns 0 if the timeout expired and -1 if an error occurs, in which case the error parameters of the LDAP session handle will be set accordingly. ldap_msgfree() frees the result structure pointed to by res and returns the type of the message it freed. ldap_msgtype() returns the type of the LDAP message it is passed as a parameter. The type will be one of the types listed above, or -1 on error. ldap_msgid() returns the message ID associated with the LDAP message passed as a parameter. 12. Handling Errors and Parsing Results The following calls are used to extract information from results and handle errors returned by other LDAP API routines. Note that ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ- ically be used in addition to ldap_parse_result() to retrieve all the result information from SASL Bind and Extended Operations respectively. int ldap_parse_result( LDAP *ld, LDAPMessage *res, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ); int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res, struct berval **servercredp, int freeit ); int ldap_parse_extended_result( Expires: 7 February 1999 [Page 37] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAP *ld, LDAPMessage *res, char **resultoidp, struct berval **resultdata, int freeit ); char *ldap_err2string( int err ); The use of the following routines is deprecated. int ldap_result2error( LDAP *ld, LDAPMessage *res, int freeit ); void ldap_perror( LDAP *ld, char *msg ); Parameters are: ld The session handle. res The result of an LDAP operation as returned by ldap_result() or one of the synchronous API operation calls. errcodep This result parameter will be filled in with the LDAP error code field from the LDAPResult message. This is the indi- cation from the server of the outcome of the operation. NULL may be passed to ignore this field. matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result parameter will be filled in with a DN indicating how much of the name in the request was recognized. NULL may be passed to ignore this field. The matched DN string should be freed by calling ldap_memfree() which is described later in this document. errmsgp This result parameter will be filled in with the contents of the error message field from the LDAPResult message. The error message string should be freed by calling ldap_memfree() which is described later in this document. NULL may be passed to ignore this field. referralsp This result parameter will be filled in with the contents of the referrals field from the LDAPResult message, indi- cating zero or more alternate LDAP servers where the Expires: 7 February 1999 [Page 38] C LDAP API The C LDAP Application Program Interface 7 August 1998 request should be retried. The referrals array should be freed by calling ldap_value_free() which is described later in this document. NULL may be passed to ignore this field. serverctrlsp This result parameter will be filled in with an allocated array of controls copied out of the LDAPResult message. The control array should be freed by calling ldap_controls_free() which was described earlier. freeit A boolean that determines whether the res parameter is disposed of or not. Pass any non-zero value to have these routines free res after extracting the requested informa- tion. This is provided as a convenience; you can also use ldap_msgfree() to free the result later. If freeit is non-zero, the entire chain of messages represented by res is disposed of. servercredp For SASL bind results, this result parameter will be filled in with the credentials passed back by the server for mutual authentication, if given. An allocated berval struc- ture is returned that should be disposed of by calling ber_bvfree(). NULL may be passed to ignore this field. resultoidp For extended results, this result parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. This string should be disposed of by calling ldap_memfree(). NULL may be passed to ignore this field. resultdatap For extended results, this result parameter will be filled in with a pointer to a struct berval containing the data in the extended operation response. It should be disposed of by calling ber_bvfree(). NULL may be passed to ignore this field. err For ldap_err2string(), an LDAP error code, as returned by ldap_parse_result() or another LDAP API call. Additional parameters for the deprecated routines are not described. Interested readers are referred to RFC 1823. All three of the ldap_parse_*_result() routines skip over messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a result message to parse. They return the constant LDAP_SUCCESS if the result was successfully parsed and another LDAP error code if not. Note that the LDAP error code that indicates the outcome of the opera- tion performed by the server is placed in the errcodep ldap_parse_result() parameter. If a chain of messages that contains Expires: 7 February 1999 [Page 39] C LDAP API The C LDAP Application Program Interface 7 August 1998 more than one result message is passed to these routines they always operate on the first result in the chain. ldap_err2string() is used to convert a numeric LDAP error code, as returned by one of the three ldap_parse_*_result() routines, or one of the synchronous API operation calls, into an informative zero-terminated character string message describing the error. It returns a pointer to static data. 13. Stepping Through a List of Results The ldap_first_message() and ldap_next_message() routines are used to step through the list of messages in a result chain returned by ldap_result(). For search operations, the result chain may actually include referral messages, entry messages, and result messages. ldap_count_messages() is used to count the number of messages returned. The ldap_msgtype() function, described above, can be used to distinguish between the different message types. LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); int ldap_count_messages( LDAP *ld, LDAPMessage *res ); Parameters are: ld The session handle. res The result chain, as obtained by a call to one of the synchronous search routines or ldap_result(). msg The message returned by a previous call to ldap_first_message() or ldap_next_message(). ldap_first_message() and ldap_next_message() will return NULL when no more messages exist in the result set to be returned. NULL is also returned if an error occurs while stepping through the entries, in which case the error parameters in the session handle ld will be set to indi- cate the error. ldap_count_messages() returns the number of messages contained in a chain of results. It can also be used to count the number of messages that remain in a chain if called with a message, entry, or reference returned by ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). Expires: 7 February 1999 [Page 40] C LDAP API The C LDAP Application Program Interface 7 August 1998 14. Parsing Search Results The following calls are used to parse the entries and references returned by ldap_search() and friends. These results are returned in an opaque structure that should only be accessed by calling the routines described below. Routines are provided to step through the entries and references returned, step through the attributes of an entry, retrieve the name of an entry, and retrieve the values associated with a given attribute in an entry. 14.1. Stepping Through a List of Entries The ldap_first_entry() and ldap_next_entry() routines are used to step through and retrieve the list of entries from a search result chain. The ldap_first_reference() and ldap_next_reference() routines are used to step through and retrieve the list of continuation references from a search result chain. ldap_count_entries() is used to count the number of entries returned. ldap_count_references() is used to count the number of references returned. LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); int ldap_count_entries( LDAP *ld, LDAPMessage *res ); int ldap_count_references( LDAP *ld, LDAPMessage *res ); Parameters are: ld The session handle. res The search result, as obtained by a call to one of the synchro- nous search routines or ldap_result(). entry The entry returned by a previous call to ldap_first_entry() or ldap_next_entry(). ldap_first_entry() and ldap_next_entry() will return NULL when no more entries or references exist in the result set to be returned. NULL is also returned if an error occurs while stepping through the entries, in which case the error parameters in the session handle ld will be set to indicate the error. Expires: 7 February 1999 [Page 41] C LDAP API The C LDAP Application Program Interface 7 August 1998 ldap_count_entries() returns the number of entries contained in a chain of entries. It can also be used to count the number of entries that remain in a chain if called with a message, entry or reference returned by ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). ldap_count_references() returns the number of references contained in a chain of search results. It can also be used to count the number of references that remain in a chain. 14.2. Stepping Through the Attributes of an Entry The ldap_first_attribute() and ldap_next_attribute() calls are used to step through the list of attribute types returned with an entry. char *ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **ptr ); char *ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ptr ); void ldap_memfree( char *mem ); Parameters are: ld The session handle. entry The entry whose attributes are to be stepped through, as returned by ldap_first_entry() or ldap_next_entry(). ptr In ldap_first_attribute(), the address of a pointer used inter- nally to keep track of the current position in the entry. In ldap_next_attribute(), the pointer returned by a previous call to ldap_first_attribute(). mem A pointer to memory allocated by the LDAP library, such as the attribute type names returned by ldap_first_attribute() and ldap_next_attribute, or the DN returned by ldap_get_dn(). ldap_first_attribute() and ldap_next_attribute() will return NULL when the end of the attributes is reached, or if there is an error, in which Expires: 7 February 1999 [Page 42] C LDAP API The C LDAP Application Program Interface 7 August 1998 case the error parameters in the session handle ld will be set to indi- cate the error. Both routines return a pointer to an allocated buffer containing the current attribute name. This should be freed when no longer in use by calling ldap_memfree(). ldap_first_attribute() will allocate and return in ptr a pointer to a BerElement used to keep track of the current position. This pointer should be passed in subsequent calls to ldap_next_attribute() to step through the entry's attributes. After a set of calls to ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it should be freed by calling ber_free( ptr, 0 ). Note that it is very important to pass the second parameter as 0 (zero) in this call, since the buffer associated with the BerElement does not point to separately allocated memory. The attribute type names returned are suitable for passing in a call to ldap_get_values() and friends to retrieve the associated values. 14.3. Retrieving the Values of an Attribute ldap_get_values() and ldap_get_values_len() are used to retrieve the values of a given attribute from an entry. ldap_count_values() and ldap_count_values_len() are used to count the returned values. ldap_value_free() and ldap_value_free_len() are used to free the values. char **ldap_get_values( LDAP *ld, LDAPMessage *entry, char *attr ); struct berval **ldap_get_values_len( LDAP *ld, LDAPMessage *entry, char *attr ); int ldap_count_values( char **vals ); int ldap_count_values_len( struct berval **vals ); void ldap_value_free( char **vals ); void ldap_value_free_len( struct berval **vals ); Expires: 7 February 1999 [Page 43] C LDAP API The C LDAP Application Program Interface 7 August 1998 Parameters are: ld The session handle. entry The entry from which to retrieve values, as returned by ldap_first_entry() or ldap_next_entry(). attr The attribute whose values are to be retrieved, as returned by ldap_first_attribute() or ldap_next_attribute(), or a caller- supplied string (e.g., "mail"). vals The values returned by a previous call to ldap_get_values() or ldap_get_values_len(). Two forms of the various calls are provided. The first form is only suitable for use with non-binary character string data. The second _len form is used with any kind of data. ldap_get_values() and ldap_get_values_len() return NULL if no values are found for attr or if an error occurs. ldap_count_values() and ldap_count_values_len() return -1 if an error occurs such as the vals parameter being invalid. Note that the values returned are dynamically allocated and should be freed by calling either ldap_value_free() or ldap_value_free_len() when no longer in use. 14.4. Retrieving the name of an entry ldap_get_dn() is used to retrieve the name of an entry. ldap_explode_dn() and ldap_explode_rdn() are used to break up a name into its component parts. ldap_dn2ufn() is used to convert the name into a more "user friendly" format. char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); char **ldap_explode_dn( char *dn, int notypes ); char **ldap_explode_rdn( char *rdn, int notypes ); char *ldap_dn2ufn( char *dn ); Parameters are: ld The session handle. Expires: 7 February 1999 [Page 44] C LDAP API The C LDAP Application Program Interface 7 August 1998 entry The entry whose name is to be retrieved, as returned by ldap_first_entry() or ldap_next_entry(). dn The dn to explode, such as returned by ldap_get_dn(). rdn The rdn to explode, such as returned in the components of the array returned by ldap_explode_dn(). notypes A boolean parameter, if non-zero indicating that the dn or rdn components should have their type information stripped off (i.e., "cn=Babs" would become "Babs"). ldap_get_dn() will return NULL if there is some error parsing the dn, setting error parameters in the session handle ld to indicate the error. It returns a pointer to newly allocated space that the caller should free by calling ldap_memfree() when it is no longer in use. Note the format of the DNs returned is given by [4]. ldap_explode_dn() returns a NULL-terminated char * array containing the RDN components of the DN supplied, with or without types as indicated by the notypes parameter. The components are returned in the order they appear in the dn. The array returned should be freed when it is no longer in use by calling ldap_value_free(). ldap_explode_rdn() returns a NULL-terminated char * array containing the components of the RDN supplied, with or without types as indicated by the notypes parameter. The components are returned in the order they appear in the rdn. The array returned should be freed when it is no longer in use by calling ldap_value_free(). ldap_dn2ufn() converts the DN into the user friendly format described in [5]. The UFN returned is newly allocated space that should be freed by a call to ldap_memfree() when no longer in use. 14.5. Retrieving controls from an entry ldap_get_entry_controls() is used to extract LDAP controls from an entry. int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry, LDAPControl ***serverctrlsp ); Parameters are: Expires: 7 February 1999 [Page 45] C LDAP API The C LDAP Application Program Interface 7 August 1998 ld The session handle. entry The entry to extract controls from, as returned by ldap_first_entry() or ldap_next_entry(). serverctrlsp This result parameter will be filled in with an allocated array of controls copied out of entry. The control array should be freed by calling ldap_controls_free(). If ser- verctrlsp is NULL, no controls are returned. ldap_get_entry_controls() returns an LDAP error code that indicates whether the reference could be successfully parsed (LDAP_SUCCESS if all goes well). 14.6. Parsing References ldap_parse_reference() is used to extract referrals and controls from a SearchResultReference message. int ldap_parse_reference( LDAP *ld, LDAPMessage *ref, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ); Parameters are: ld The session handle. ref The reference to parse, as returned by ldap_result(), ldap_first_reference(), or ldap_next_reference(). referralsp This result parameter will be filled in with an allocated array of character strings. The elements of the array are the referrals (typically LDAP URLs) contained in ref. The array should be freed when no longer in used by calling ldap_value_free(). If referralsp is NULL, the referral URLs are not returned. serverctrlsp This result parameter will be filled in with an allocated array of controls copied out of ref. The control array should be freed by calling ldap_controls_free(). If ser- verctrlsp is NULL, no controls are returned. Expires: 7 February 1999 [Page 46] C LDAP API The C LDAP Application Program Interface 7 August 1998 freeit A boolean that determines whether the ref parameter is disposed of or not. Pass any non-zero value to have these routines free res after extracting the requested informa- tion. This is provided as a convenience; you can also use ldap_msgfree() to free the result later. ldap_parse_reference() returns an LDAP error code that indicates whether the reference could be successfully parsed (LDAP_SUCCESS if all goes well). 15. Encoded ASN.1 Value Manipulation This section describes routines which may be used to encode and decode BER-encoded ASN.1 values, which are often used inside of control and extension values. With the exceptions of two new functions ber_flatten() and ber_init(), these functions are compatible with the University of Michigan LDAP 3.3 implementation of BER. 15.1. General struct berval { unsigned long bv_len; char *bv_val; }; A struct berval contains a sequence of bytes and an indication of its length. The bv_val is not null terminated. bv_len must always be a nonnegative number. Applications may allocate their own berval struc- tures. typedef struct berelement { /* opaque */ } BerElement; The BerElement structure contains not only a copy of the encoded value, but also state information used in encoding or decoding. Applications cannot allocate their own BerElement structures. The internal state is neither thread-specific nor locked, so two threads should not manipulate the same BerElement value simultaneously. A single BerElement value cannot be used for both encoding and decoding. void ber_bvfree( struct berval *bv ); Expires: 7 February 1999 [Page 47] C LDAP API The C LDAP Application Program Interface 7 August 1998 ber_bvfree() frees a berval returned from this API. Both the bv->bv_val string and the berval itself are freed. Applications should not use ber_bvfree() with bervals which the application has allocated. void ber_bvecfree ( struct berval **bv ); ber_bvecfree() frees an array of bervals returned from this API. Each of the bervals in the array are freed using ber_bvfree(), then the array itself is freed. struct berval *ber_bvdup (struct berval *bv ); ber_bvdup() returns a copy of a berval. The bv_val field in the returned berval points to a different area of memory as the bv_val field in the argument berval. The null pointer is returned on error (e.g. out of memory). void ber_free ( BerElement *ber, int fbuf ); ber_free() frees a BerElement which is returned from the API calls ber_alloc_t() or ber_init(). Each BerElement must be freed by the caller. The second argument fbuf should always be set to 1 to ensure that the internal buffer used by the BER functions is freed as well as the BerElement container itself. 15.2. Encoding BerElement *ber_alloc_t(int options); ber_alloc_t() constructs and returns BerElement. The null pointer is returned on error. The options field contains a bitwise-or of options which are to be used when generating the encoding of this BerElement. One option is defined and must always be supplied: #define LBER_USE_DER 0x01 When this option is present, lengths will always be encoded in the minimum number of octets. Note that this option does not cause values of sets and sequences to be rearranged in tag and byte order, so these functions are not sufficient for generating DER output as defined in X.509 and X.680. If the caller takes responsibility for ordering values of sets and sequences correctly, DER output as defined in X.509 and X.680 can be produced. Unrecognized option bits are ignored. The BerElement returned by ber_alloc_t() is initially empty. Calls to Expires: 7 February 1999 [Page 48] C LDAP API The C LDAP Application Program Interface 7 August 1998 ber_printf() will append bytes to the end of the ber_alloc_t(). int ber_printf(BerElement *ber, char *fmt, ... ) The ber_printf() routine is used to encode a BER element in much the same way that sprintf() works. One important difference, though, is that state information is kept in the ber argument so that multiple calls can be made to ber_printf() to append to the end of the BER ele- ment. ber must be a pointer to a BerElement returned by ber_alloc_t(). ber_printf() interprets and formats its arguments according to the for- mat string fmt. ber_printf() returns -1 if there is an error during encoding and a positive number if successful. As with sprintf(), each character in fmt refers to an argument to ber_printf(). The format string can contain the following format characters: 't' Tag. The next argument is an int specifying the tag to override the next element to be written to the ber. This works across calls. The int value must contain the tag class, constructed bit, and tag value. The tag value must fit in a single octet (tag value is less than 32). For example, a tag of "[3]" for a constructed type is 0xA3. 'b' Boolean. The next argument is an int, containing either 0 for FALSE or 0xff for TRUE. A boolean element is output. If this format character is not preceded by the 't' format modifier, the tag 0x01 is used for the element. 'i' Integer. The next argument is an int, containing the integer in the host's byte order. An integer element is output. If this format character is not preceded by the 't' format modifier, the tag 0x02 is used for the element. 'X' Bitstring. The next two arguments are a char * pointer to the start of the bitstring, followed by an int containing the number of bits in the bitstring. A bitstring element is output, in primitive form. If this format character is not preceded by the 't' format modifier, the tag 0x03 is used for the element. 'n' Null. No argument is required. An ASN.1 NULL element is out- put. If this format character is not preceded by the 't' format modifier, the tag 0x05 is used for the element. 'o' Octet string. The next two arguments are a char *, followed by an int with the length of the string. The string may contain null bytes and need not by zero-terminated. An octet string element is output, in primitive form. If this format character is not preceded by the 't' format modifier, the tag 0x04 is used Expires: 7 February 1999 [Page 49] C LDAP API The C LDAP Application Program Interface 7 August 1998 for the element. 's' Octet string. The next argument is a char * pointing to a zero-terminated string. An octet string element in primitive form is output, which does not include the trailing ' ' byte. If this format character is not preceded by the 't' format modif- ier, the tag 0x04 is used for the element. 'v' Several octet strings. The next argument is a char **, an array of char * pointers to zero-terminated strings. The last element in the array must be a null pointer. The octet strings do not include the trailing SEQUENCE OF octet strings. The 't' format modifier cannot be used with this format character. 'V' Several octet strings. A NULL-terminated array of berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. The 't' format modifier cannot be used with this format character. '{' Begin sequence. No argument is required. If this format char- acter is not preceded by the 't' format modifier, the tag 0x30 is used. '}' End sequence. No argument is required. The 't' format modifier cannot be used with this format character. '[' Begin set. No argument is required. If this format character is not preceded by the 't' format modifier, the tag 0x31 is used. ']' End set. No argument is required. The 't' format modifier can- not be used with this format character. Each use of a '{' format character must be matched by a '}' character, either later in the format string, or in the format string of a subse- quent call to ber_printf() for that BerElement. The same applies to the '[' and Sequences and sets nest, and implementations of this API must maintain internal state to be able to properly calculate the lengths. int ber_flatten (BerElement *ber, struct berval **bvPtr); The ber_flatten routine allocates a struct berval whose contents are a BER encoding taken from the ber argument. The bvPtr pointer points to the returned berval, which must be freed using ber_bvfree(). This rou- tine returns 0 on success and -1 on error. Expires: 7 February 1999 [Page 50] C LDAP API The C LDAP Application Program Interface 7 August 1998 The ber_flatten API call is not present in U-M LDAP 3.3. The use of ber_flatten on a BerElement in which all '{' and '}' format modifiers have not been properly matched is an error (i.e., -1 will be returned by ber_flatten() if this situation is exists). 15.3. Encoding Example The following is an example of encoding the following ASN.1 data type: Example1Request ::= SEQUENCE { s OCTET STRING, -- must be printable val1 INTEGER, val2 [0] INTEGER DEFAULT 0 } int encode_example1(char *s,int val1,int val2,struct berval **bvPtr) { BerElement *ber; int rc; ber = ber_alloc_t(LBER_USE_DER); if (ber == NULL) return -1; if (ber_printf(ber,"{si",s,val1) == -1) { ber_free(ber,1); return -1; } if (val2 != 0) { if (ber_printf(ber,"ti",0x80,val2) == -1) { ber_free(ber,1); return -1; } } if (ber_printf(ber,"}") == -1) { ber_free(ber,1); return -1; } rc = ber_flatten(ber,bvPtr); ber_free(ber,1); return rc; } Expires: 7 February 1999 [Page 51] C LDAP API The C LDAP Application Program Interface 7 August 1998 15.4. Decoding The following two symbols are available to applications. #define LBER_ERROR 0xffffffffL #define LBER_DEFAULT 0xffffffffL BerElement *ber_init (struct berval *bv); The ber_init function constructs a BerElement and returns a new BerEle- ment containing a copy of the data in the bv argument. ber_init returns the null pointer on error. unsigned long ber_scanf (BerElement *ber, char *fmt, ... ); The ber_scanf() routine is used to decode a BER element in much the same way that sscanf() works. One important difference, though, is that some state information is kept with the ber argument so that multiple calls can be made to ber_scanf() to sequentially read from the BER element. The ber argument must be a pointer to a BerElement returned by ber_init(). ber_scanf interprets the bytes according to the format string fmt, and stores the results in its additional arguments. ber_scanf() returns LBER_ERROR on error, and a different value on suc- cess. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters: 'a' Octet string. A char ** argument should be supplied. Memory is allocated, filled with the contents of the octet string, null- terminated, and the pointer to the string is stored in the argu- ment. The returned value must be freed using ldap_memfree. The tag of the element must indicate the primitive form (constructed strings are not supported) but is otherwise ignored and dis- carded during the decoding. This format cannot be used with octet strings which could contain null bytes. 'O' Octet string. A struct berval ** argument should be supplied, which upon return points to a allocated struct berval containing the octet string and its length. ber_bvfree() must be called to free the allocated memory. The tag of the element must indicate the primitive form (constructed strings are not supported) but is otherwise ignored during the decoding. 'b' Boolean. A pointer to an int should be supplied. The int value stored will be 0 for FALSE or nonzero for TRUE. The tag of the element must indicate the primitive form but is otherwise Expires: 7 February 1999 [Page 52] C LDAP API The C LDAP Application Program Interface 7 August 1998 ignored during the decoding. 'i' Integer. A pointer to an int should be supplied. The int value stored will be in host byte order. The tag of the element must indicate the primitive form but is otherwise ignored during the decoding. ber_scanf() will return an error if the integer can- not be stored in an int. 'B' Bitstring. A char ** argument should be supplied which will point to the allocated bits, followed by an unsigned long * argument, which will point to the length (in bits) of the bit- string returned. ldap_memfree must be called to free the bit- string. The tag of the element must indicate the primitive form (constructed bitstrings are not supported) but is otherwise ignored during the decoding. 'n' Null. No argument is required. The element is simply skipped if it is recognized as a zero-length element. The tag is ignored. 'v' Several octet strings. A char *** argument should be supplied, which upon return points to a allocated null-terminated array of char *'s containing the octet strings. NULL is stored if the sequence is empty. ldap_memfree must be called to free each element of the array and the array itself. The tag of the sequence and of the octet strings are ignored. 'V' Several octet strings (which could contain null bytes). A struct berval *** should be supplied, which upon return points to a allocated null-terminated array of struct berval *'s con- taining the octet strings and their lengths. NULL is stored if the sequence is empty. ber_bvecfree() can be called to free the allocated memory. The tag of the sequence and of the octet strings are ignored. 'x' Skip element. The next element is skipped. No argument is required. '{' Begin sequence. No argument is required. The initial sequence tag and length are skipped. '}' End sequence. No argument is required. '[' Begin set. No argument is required. The initial set tag and length are skipped. ']' End set. No argument is required. Expires: 7 February 1999 [Page 53] C LDAP API The C LDAP Application Program Interface 7 August 1998 unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr); ber_peek_tag() returns the tag of the next element to be parsed in the BerElement argument. The length of this element is stored in the *lenPtr argument. LBER_DEFAULT is returned if there is no further data to be read. The ber argument is not modified. unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr); ber_skip_tag() is similar to ber_peek_tag(), except that the state pointer in the BerElement argument is advanced past the first tag and length, and is pointed to the value part of the next element. This rou- tine should only be used with constructed types and situations when a BER encoding is used as the value of an OCTET STRING. The length of the value is stored in *lenPtr. unsigned long ber_first_element(BerElement *ber, unsigned long *lenPtr, char **opaquePtr); unsigned long ber_next_element (BerElement *ber, unsigned long *lenPtr, char *opaque); ber_first_element() and ber_next_element() are used to traverse a SET, SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, and calls ber_peek_tag() for the first element inside the constructed value. LBER_DEFAULT is returned if the constructed value is empty. ber_next_element() positions the state at the start of the next element in the constructed type. LBER_DEFAULT is returned if there are no further values. The len and opaque values should not be used by applications other than as arguments to ber_next_element(), as shown in the example below. 15.5. Decoding Example The following is an example of decoding an ASN.1 data type: Example2Request ::= SEQUENCE { dn OCTET STRING, -- must be printable scope ENUMERATED { b (0), s (1), w (2) }, ali ENUMERATED { n (0), s (1), f (2), a (3) }, size INTEGER, time INTEGER, tonly BOOLEAN, attrs SEQUENCE OF OCTET STRING, -- must be printable [0] SEQUENCE OF SEQUENCE { Expires: 7 February 1999 [Page 54] C LDAP API The C LDAP Application Program Interface 7 August 1998 type OCTET STRING -- must be printable, crit BOOLEAN DEFAULT FALSE, value OCTET STRING } OPTIONAL } #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */ int decode_example2(struct berval *bv) { BerElement *ber; unsigned long len; int scope, ali, size, time, tonly; char *dn = NULL, **attrs = NULL; int res,i,rc = 0; ber = ber_init(bv); if (ber == NULL) { printf("ERROR ber_init failed0); return -1; } res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali, &size,&time,&tonly,&attrs); if (res == -1) { printf("ERROR ber_scanf failed0); ber_free(ber,1); return -1; } /* *** use dn */ ldap_memfree(dn); for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { /* *** use attrs[i] */ ldap_memfree(attrs[i]); } ldap_memfree(attrs); if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) { char *opaque; unsigned long tag; for (tag = ber_first_element(ber,&len,&opaque); tag != LBER_DEFAULT; tag = ber_next_element (ber,&len,opaque)) { unsigned long ttag, tlen; Expires: 7 February 1999 [Page 55] C LDAP API The C LDAP Application Program Interface 7 August 1998 char *type; int crit; struct berval *value; if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { printf("ERROR cannot parse type0); break; } /* *** use type */ ldap_memfree(type); ttag = ber_peek_tag(ber,&tlen); if (ttag == 0x01) { /* boolean */ if (ber_scanf(ber,"b", &crit) == LBER_ERROR) { printf("ERROR cannot parse crit0); rc = -1; break; } } else if (ttag == 0x04) { /* octet string */ crit = 0; } else { printf("ERROR extra field in controls0); break; } if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { printf("ERROR cannot parse value0); rc = -1; break; } /* *** use value */ ber_bvfree(value); } } ber_scanf(ber,"}"); ber_free(ber,1); return rc; } 16. Security Considerations LDAPv2 supports security through protocol-level authentication using Expires: 7 February 1999 [Page 56] C LDAP API The C LDAP Application Program Interface 7 August 1998 clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen- tication Security Layer) methods. LDAPv3 also supports operation over a secure transport layer using Transport Layer Security TLS [9]. Readers are referred to the protocol documents for discussion of related secu- rity considerations. Implementations of this API should be cautious when handling authentica- tion credentials. In particular, keeping long-lived copies of creden- tials without the application's knowledge is discouraged. 17. Acknowledgements Many members of the IETF ASID and LDAPEXT working groups as well as members of the Internet at large have provided useful comments and suggestions that have been incorporated into this revision. This original material upon which this revision is based was based upon work supported by the National Science Foundation under Grant No. NCR- 9416667. 18. Copyright Copyright (C) The Internet Society (1998). All Rights Reserved. This document and translations of it may be copied and furnished to oth- ers, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and dis- tributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Stan- dards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- NESS FOR A PARTICULAR PURPOSE. Expires: 7 February 1999 [Page 57] C LDAP API The C LDAP Application Program Interface 7 August 1998 19. Bibliography [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation X.520. [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [3] T. Howes, "The String Representation of LDAP Search Filters," RFC 2254, December 1997. [4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol (v3): A UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- ing," RFC 1781, March 1995. [6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control Extension for Server Side Sorting of Search Results", INTERNET- DRAFT , 10 March 1998. [8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [9] "Lightweight Directory Access Protocol (v3): Extension for Tran- sport Layer Security", INTERNET-DRAFT , July 1998. [10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2044, October 1996. [11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995. 20. Authors' Addresses Mark Smith Netscape Communications Corp. 501 E. Middlefield Rd., Mailstop MV068 Mountain View, CA 94043 USA +1 650 937-3477 mcs@netscape.com Expires: 7 February 1999 [Page 58] C LDAP API The C LDAP Application Program Interface 7 August 1998 Tim Howes Netscape Communications Corp. 501 E. Middlefield Rd., Mailstop MV068 Mountain View, CA 94043 USA +1 650 937-3419 howes@netscape.com Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA +1 425 882-8080 andyhe@microsoft.com Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA +1 425 882-8080 cweider@microsoft.com Mark Wahl Innosoft International, Inc. 8911 Capital of Texas Hwy, Suite 4140 Austin, TX 78759 USA +1 626 919 3600 Mark.Wahl@innosoft.com Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA +1 425 882-8080 anoopa@microsoft.com 21. Appendix A - Sample LDAP API Code #include main() { LDAP *ld; Expires: 7 February 1999 [Page 59] C LDAP API The C LDAP Application Program Interface 7 August 1998 LDAPMessage *res, *e; int i, rc; char *a, *dn; BerElement *ptr; char **vals; /* open an LDAP session */ if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) exit( 1 ); /* authenticate as nobody */ if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) { fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc )); exit( 1 ); } /* search for entries with cn of "Babs Jensen", return all attrs */ if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US", LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) != LDAP_SUCCESS ) { fprintf( stderr, "ldap_search_s: %s\n", ldap_err2string( rc )); exit( 1 ); } /* step through each entry returned */ for ( e = ldap_first_entry( ld, res ); e != NULL; e = ldap_next_entry( ld, e ) ) { /* print its name */ dn = ldap_get_dn( ld, e ); printf( "dn: %s\n", dn ); ldap_memfree( dn ); /* print each attribute */ for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; a = ldap_next_attribute( ld, e, ptr ) ) { printf( "attribute: %s\n", a ); /* print each value */ vals = ldap_get_values( ld, e, a ); for ( i = 0; vals[i] != NULL; i++ ) { printf( "value: %s\n", vals[i] ); } ldap_value_free( vals ); ldap_memfree( a ); } if ( ptr != NULL ) { Expires: 7 February 1999 [Page 60] C LDAP API The C LDAP Application Program Interface 7 August 1998 ber_free( ptr, 0 ); } } /* free the search results */ ldap_msgfree( res ); /* close and free connection resources */ ldap_unbind( ld ); } 22. Appendix B - Namespace Consumed By This Specification The following 2 prefixes are used in this specification to name func- tions: ldap_ ber_ The following 6 prefixes are used in this specification to name struc- tures, unions, and typedefs: ldap LDAP PLDAP ber Ber timeval The following 3 prefixes are used in this specification to name #defined macros: LDAP LBER_ mod_ 23. Appendix C - Outstanding Issues 23.1. Support for multithreaded applications In order to support multithreaded applications in a platform-independent way, some additions to the LDAP API are needed. Different implementors have taken different paths to solve this problem in the past. A common set of thread-related API calls must be defined so that application developers are not unduly burdened. These will be added to a future revision of this specification. Expires: 7 February 1999 [Page 61] C LDAP API The C LDAP Application Program Interface 7 August 1998 23.2. Using Transport Layer Security (TLS) The API calls used to support TLS must be specified. They will be added to a future revision of this specification or to an LDAP C API extension document. 23.3. Client control for chasing referrals A client control has been defined that can be used to specify on a per- operation basis whether references and external referrals are automati- cally chased by the client library. This will be added to a future revision of this specification. 23.4. Potential confusion between hostname:port and IPv6 addresses String representations of IPv6 network addresses [11] can contain colon characters. The ldap_init() call is specified to take strings of the form "hostname:port" or "ipaddress:port". If IPv6 addresses are used, the latter could be ambiguous. A future revision of this specification will resolve this issue. 23.5. Need to track SASL API standardization efforts If a standard Simple Authentication and Security Layer API is defined, it may be necessary to modify the LDAP API to accommodate it. 23.6. Support for character sets other than UTF-8? Some application developers would prefer to pass string data using a character set other than UTF-8. If this feature is added, the number of different character sets supported should definitely be minimized. 23.7. LDAP Session Handle Options The use of void * as the third parameter to ldap_get_option() and ldap_set_option() is messy and requires callers of the API to use pointers even when passing in scaler values. One suggestion is to use functions declared like these instead: int ldap_get_global_option( LDAP *ld, int option, ... ); int ldap_set_global_option( LDAP *ld, int option, ... ); The type of the third parameter would of course depend on the value for the second. Expires: 7 February 1999 [Page 62] C LDAP API The C LDAP Application Program Interface 7 August 1998 23.8. Re-bind function is not sufficiently general purpose The "re-bind" callback function specified in older revisions of this document is not sufficient to support challenge/response SASL authenti- cation mechanisms such as CRAM-MD5. A new, more functional mechanism should be specified. Client implementors would also like to receive the host and port number and a reason why the re-bind callback has been called so they can make secure, intelligent decisions when processing re-binds. 23.9. LDAP C API extension mechanism should be clearly specified. The "Retrieving Information About the API Implementation" section of this document discusses some of the requirements that should be met by documents that extend this LDAP C API specification. A simple procedure for defining LDAP C API extensions should be completely specified and summarized in one place within this document. 24. Appendix D - Changes Made Since Last Document Revision The previous version of this document was draft-ietf-ldapext-ldap-c- api-00.txt, dated 13 March 1998. This appendix lists all of the changes made to that document to produce the one you are reading now. 24.1. API Changes The "Retrieving Information About the API Implementation" section was completely re-written. The ldap_version() call was eliminated in favor of a new LDAP_STANDARD_API_VERSION macro combined with a new option for ldap_get_option() called LDAP_OPT_API_INFO. In the "LDAP Session Handle Options" section: added notes about free- ing of char * and LDAPControl * values, provided separate types for each option for the "outvalue" and "invalue" parameters, and added information about READ-ONLY options. The only option that is currently specified as READ-ONLY is LDAP_OPT_DESC. In the "Searching", "Reading an Entry", and "Listing the Children of an Entry" sections: passing NULL for the filter string to one of the search functions is equivalent to passing the string "(objectclass=*)". This seems like a convenient shorthand to provide for users of the API. The "Handling re-authentication (re-bind)" section was completely removed. Expires: 7 February 1999 [Page 63] C LDAP API The C LDAP Application Program Interface 7 August 1998 In the "LDAP Session Handle Options" section: removed all references to the inadequate "re-bind proc" related options. In the "Stepping Through the Attributes of an Entry" section: removed ldap_ber_free() function since it serves the same purpose as ber_free(). In the "Parsing References" section: added missing * to the ldap_parse_reference() referralsp parameter. In the "Encoded ASN.1 Value Manipulation: Encoding" section: changed the description of ber_flatten() to specify that unbalanced '{' and '}' format modifiers result in an error. 24.2. Editorial changes In the "Introduction" section: removed old, conflicting text that said that this document specifies information only for the Internet community only and not a standard. In the "Status of this Memo" section: updated the text to reflect the current list of Internet-Drafts Shadow directories. In the "Overview of LDAP API Use" and "LDAP Session Handle Options" sections: replaced references to "default LDAP server" with "primary LDAP server." In the "Overview of LDAP API Use" section: made it clear the message id is not necessarily returned by the asynchronous function calls as their return value. In the "Overview of LDAP API Use" section: mentioned that some LDAP API implementations may support character sets other than UTF-8. In the "Common Data Structures", "Obtaining Results and Peeking Inside LDAP Messages", and "Handling Errors and Parsing Results" sec- tions: added more information about "result chains" to the In the "Authenticating to the directory" section: fix text to indi- cate the SASL mechanisms are identified using text strings, not OIDs. In the "LDAP Error Codes" section: eliminated a repeated sentence. In the "Searching" section: changed ldap_search_ext() and ldap_search_ext_s() prototypes to use timeout instead of timeoutp for struct timeval * parameter. Expires: 7 February 1999 [Page 64] C LDAP API The C LDAP Application Program Interface 7 August 1998 In the "Handling Errors and Parsing Results" section: added a note to clarify that ldap_parse_extended_result() and ldap_parse_sasl_bind_result() are used in addition to ldap_parse_result(). In the "Closing the session" section: added a note to clarify that once ldap_unbind() or ldap_unbind_s() has been done it is illegal to use the session handle in any future API calls. In the "Encoded ASN.1 Value Manipulation: Encoding" section: added note near LBER_USE_DER that if the caller takes responsibility for ordering values of sets and sequences correctly DER output as defined in X.509 and X.680 can be produced. In the "Encoded ASN.1 Value Manipulation: Encoding Example" section: corrected the example code to return rc instead of always returning -1. In the "Bibliography" section: updated references to the LDAPv3 TLS and Sorting drafts. In "Authors' Addresses" section: updated Mark Wahl's address. In "Appendix - Outstanding Issues": added "Re-bind function is not sufficiently general purpose" and "LDAP C API extension mechanism should be clearly specified" issues. In "Appendix - Sample LDAP API Code": added a missing ldap_memfree() call. Added new appendix: "Namespace Consumed By This Specification." Move "Table of Contents" from very end to the early part of this document. Expires: 7 February 1999 [Page 65]