Lines Matching refs:LDAP
17 The C LDAP Application Program Interface
42 cussion of this document will take place on the IETF LDAP Extension
56 C LDAP API C LDAP Application Program Interface 17 November 2000
62 to the Lightweight Directory Access Protocol (LDAP). This document
65 LDAP protocol. New extended operation functions were added to support
66 LDAPv3 features such as controls. In addition, other LDAP API changes
73 The C LDAP API is designed to be powerful, yet simple to use. It defines
74 compatible synchronous and asynchronous interfaces to LDAP to suit a
76 the LDAP model, then an overview of how the API is used by an applica-
77 tion program to obtain LDAP information. The API calls are described in
89 4. Overview of the LDAP Model.....................................4
90 5. Overview of LDAP API Use and General Requirements..............4
98 11. Performing LDAP Operations.....................................16
99 11.1. Initializing an LDAP Session................................16
100 11.2. LDAP Session Handle Options.................................17
112 C LDAP API C LDAP Application Program Interface 17 November 2000
124 13. Obtaining Results and Peeking Inside LDAP Messages.............45
146 23. Appendix A - Sample C LDAP API Code............................73
156 26.1. Opaque LDAP Structure.......................................76
168 C LDAP API C LDAP Application Program Interface 17 November 2000
178 4. Overview of the LDAP Model
180 LDAP is the lightweight directory access protocol, described in [2] and
182 or a stand-alone service. In either mode, LDAP is based on a client-
183 server model in which a client makes a TCP connection to an LDAP server,
186 The LDAP information model is based on the entry, which contains infor-
206 o=University of Michigan, c=US". The DN format used by LDAP is defined
212 descriptions of the LDAP API calls that implement all of these func-
216 5. Overview of LDAP API Use and General Requirements
218 An application generally uses the C LDAP API in four simple steps.
224 C LDAP API C LDAP Application Program Interface 17 November 2000
227 1. Initialize an LDAP session with a primary LDAP server. The
231 2. Authenticate to the LDAP server. The ldap_sasl_bind() function
234 3. Perform some LDAP operations and obtain some results.
251 there is no requirement that an LDAP API implementation not block when
253 this document refers to the fact that the sending of LDAP requests can
254 be separated from the receiving of LDAP responses.
262 LDAP version 3 servers can return referrals and references to other
269 LDAP API are represented using the character set of the underlying LDAP
280 C LDAP API C LDAP Application Program Interface 17 November 2000
284 API will by default use version 2 of the LDAP protocol. Applications
285 that intend to take advantage of LDAP version 3 features will need to
290 cation MUST implement all of the C LDAP API functions as described in
322 development of applications desiring compatibility with older LDAP
336 C LDAP API C LDAP Application Program Interface 17 November 2000
356 LDAP API functions as 'const.' Implementations specifically
377 Data structures and types that are common to several LDAP API functions
380 typedef struct ldap LDAP;
392 C LDAP API C LDAP Application Program Interface 17 November 2000
405 The LDAP structure is an opaque data type that represents an LDAP ses-
414 returned by LDAP operations such as search. LDAP API functions such as
417 the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
448 C LDAP API C LDAP Application Program Interface 17 November 2000
465 All memory that is allocated by a function in this C LDAP API and
471 Memory that is allocated through means outside of the C LDAP API MUST
474 If a pointer value passed to one of the C LDAP API "free" functions is
504 C LDAP API C LDAP Application Program Interface 17 November 2000
510 tions in a header so compile time tests can be done by LDAP software
521 "level" is replaced with the RFC number given to this C LDAP API
524 min-version is replaced with the lowest LDAP protocol version sup-
527 max-version is replaced with the highest LDAP protocol version sup-
550 and application code can test the C LDAP API version level using a
560 C LDAP API C LDAP Application Program Interface 17 November 2000
579 For example, if C LDAP API extensions for Transport Layer Security [9]
607 valid LDAP session handle which was obtained by calling ldap_init().
616 C LDAP API C LDAP Application Program Interface 17 November 2000
622 int ldapai_protocol_version; /* highest LDAP version supported */
651 A number that matches that assigned to the C LDAP API RFC sup-
656 The highest LDAP protocol version supported by the implementa-
662 that produced the LDAP API implementation. This field may be
672 C LDAP API C LDAP Application Program Interface 17 November 2000
687 names of the API extensions supported by the LDAP API imple-
691 cise value MUST be defined by documents that specify C LDAP
728 C LDAP API C LDAP Application Program Interface 17 November 2000
749 assigned to the C LDAP API extension RFC supported for this
759 Many of the LDAP API routines return result codes, some of which indi-
760 cate local API errors and some of which are LDAP resultCodes that are
784 C LDAP API C LDAP Application Program Interface 17 November 2000
840 C LDAP API C LDAP Application Program Interface 17 November 2000
843 11. Performing LDAP Operations
845 This section describes each LDAP operation API call in detail. Most
846 functions take a "session handle," a pointer to an LDAP structure con-
852 11.1. Initializing an LDAP Session
854 ldap_init() initializes a session with an LDAP server. The server is not
858 LDAP *ldap_init(
865 LDAP *ldap_open(
877 representing the IP address of hosts running an LDAP server to
887 portno Contains the TCP port number to connect to. The default LDAP
896 C LDAP API C LDAP Application Program Interface 17 November 2000
905 Note that if you connect to an LDAPv2 server, one of the LDAP bind calls
914 11.2. LDAP Session Handle Options
916 The LDAP session handle returned by ldap_init() is a pointer to an
917 opaque data type representing an LDAP session. In RFC 1823 this data
938 LDAP *ld,
944 LDAP *ld,
952 C LDAP API C LDAP Application Program Interface 17 November 2000
970 accessed. New LDAP session handles created with ldap_init() or
986 Used to retrieve some basic information about the LDAP API
1008 C LDAP API C LDAP Application Program Interface 17 November 2000
1035 long the C LDAP API implementation itself will wait locally
1047 Determines whether the LDAP library automatically follows
1048 referrals returned by LDAP servers or not. It MAY be set to
1064 C LDAP API C LDAP Application Program Interface 17 November 2000
1068 Determines whether LDAP I/O operations are automatically res-
1074 is useful if an LDAP I/O operation can be interrupted prema-
1084 This option indicates the version of the LDAP protocol used
1085 when communicating with the primary LDAP server. It SHOULD be
1095 A default list of LDAP server controls to be sent with each
1104 A default list of client controls that affect the LDAP ses-
1113 Used to retrieve version information about LDAP API extended
1120 C LDAP API C LDAP Application Program Interface 17 November 2000
1132 The host name (or list of hosts) for the primary LDAP server.
1157 The most recent local (API generated) or server returned LDAP
1166 The message returned with the most recent LDAP error that
1176 C LDAP API C LDAP Application Program Interface 17 November 2000
1182 The matched DN value returned with the most recent LDAP error
1189 trol **, a copy of the data that is associated with the LDAP
1211 NOT change the state of the LDAP session handle or the state of the
1213 LDAP API calls. When a call to ldap_get_option() fails, the only ses-
1214 sion handle change permitted is setting the LDAP result code (as
1218 the LDAP session handle or the state of the underlying implementation in
1219 a way that affects the behavior of future LDAP API calls.
1232 C LDAP API C LDAP Application Program Interface 17 November 2000
1235 defined by C LDAP API implementations to aid extension implementors:
1243 can be sent to a server or returned to the client with any LDAP message.
1246 The LDAP API also supports a client-side extension mechanism through the
1247 use of client controls. These controls affect the behavior of the LDAP
1270 and/or client. Note that the LDAP unbind and abandon
1275 Some LDAP API calls allocate an ldapcontrol structure or a NULL-
1288 C LDAP API C LDAP Application Program Interface 17 November 2000
1293 passed directly to some LDAP API calls such as ldap_search_ext(), in
1309 As described previously in the section "LDAP Session Handle Options,"
1344 C LDAP API C LDAP Application Program Interface 17 November 2000
1352 The following functions are used to authenticate an LDAP client to an
1353 LDAP directory server.
1356 general and extensible authentication over LDAP through the use of the
1365 LDAP *ld,
1375 LDAP *ld,
1385 LDAP *ld,
1391 LDAP *ld,
1400 C LDAP API C LDAP Application Program Interface 17 November 2000
1406 int ldap_bind( LDAP *ld, const char *dn, const char *cred,
1409 int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
1412 int ldap_kerberos_bind( LDAP *ld, const char *dn );
1414 int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
1440 serverctrls List of LDAP server controls, or NULL if no server controls
1456 C LDAP API C LDAP Application Program Interface 17 November 2000
1472 sent, or another LDAP result code if not. See the section below on
1482 -1, setting the session error parameters in the LDAP structure appropri-
1487 LDAP_SUCCESS if the operation was successful, or another LDAP result
1505 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
1512 C LDAP API C LDAP Application Program Interface 17 November 2000
1515 int ldap_unbind( LDAP *ld );
1517 int ldap_unbind_s( LDAP *ld );
1523 serverctrls List of LDAP server controls, or NULL if no server controls
1531 close all open connections associated with the LDAP session handle, and
1533 returning. Note, however, that there is no server response to an LDAP
1535 (or another LDAP result code if the request cannot be sent to the LDAP
1537 dle ld is invalid and it is illegal to make any further LDAP API calls
1550 The following functions are used to search the LDAP directory, returning
1555 LDAP *ld,
1568 C LDAP API C LDAP Application Program Interface 17 November 2000
1577 LDAP *ld,
1591 LDAP *ld,
1600 LDAP *ld,
1610 LDAP *ld,
1624 C LDAP API C LDAP Application Program Interface 17 November 2000
1672 the LDAP session handle (set by using ldap_set_option()
1680 C LDAP API C LDAP Application Program Interface 17 November 2000
1687 1 SHOULD be passed to the LDAP server as the operation time
1689 SHOULD be passed to the LDAP server.
1695 timeout from the LDAP session handle (which is set by cal-
1704 serverctrls List of LDAP server controls, or NULL if no server controls
1722 These options are fully described in the earlier section "LDAP Session
1727 fully sent, or another LDAP result code if not. See the section below
1736 C LDAP API C LDAP Application Program Interface 17 November 2000
1748 sion error parameters in the LDAP structure appropriately.
1753 another LDAP result code if it was not. See the section below on error
1773 LDAP does not support a read operation directly. Instead, this operation
1781 LDAP does not support a list operation directly. Instead, this operation
1792 C LDAP API C LDAP Application Program Interface 17 November 2000
1798 assertion against an LDAP entry. There are four variations:
1801 LDAP *ld,
1811 LDAP *ld,
1820 LDAP *ld,
1827 LDAP *ld,
1848 C LDAP API C LDAP Application Program Interface 17 November 2000
1860 serverctrls List of LDAP server controls, or NULL if no server controls
1873 fully sent, or another LDAP result code if not. See the section below
1884 sion error parameters in the LDAP structure appropriately.
1889 or another LDAP result code if it was not. See the section below on
1904 C LDAP API C LDAP Application Program Interface 17 November 2000
1909 The following routines are used to modify an existing LDAP entry. There
1926 LDAP *ld,
1935 LDAP *ld,
1943 LDAP *ld,
1949 LDAP *ld,
1960 C LDAP API C LDAP Application Program Interface 17 November 2000
1971 serverctrls List of LDAP server controls, or NULL if no server controls
2016 C LDAP API C LDAP Application Program Interface 17 November 2000
2023 fully sent, or another LDAP result code if not. See the section below
2034 sion error parameters in the LDAP structure appropriately.
2038 the operation was successful, or another LDAP result code if it was not.
2049 ldap_modrdn2_s() routines were used to change the name of an LDAP entry.
2059 LDAP *ld,
2072 C LDAP API C LDAP Application Program Interface 17 November 2000
2077 LDAP *ld,
2090 LDAP *ld,
2095 LDAP *ld,
2100 LDAP *ld,
2106 LDAP *ld,
2128 C LDAP API C LDAP Application Program Interface 17 November 2000
2133 version 2 of the LDAP protocol; otherwise the server's
2142 serverctrls List of LDAP server controls, or NULL if no server controls
2154 sent, or another LDAP result code if not. See the section below on
2162 another LDAP result code if it was not. See the section below on error
2172 The following functions are used to add entries to the LDAP directory.
2176 LDAP *ld,
2184 C LDAP API C LDAP Application Program Interface 17 November 2000
2193 LDAP *ld,
2201 LDAP *ld,
2207 LDAP *ld,
2225 serverctrls List of LDAP server controls, or NULL if no server controls
2240 C LDAP API C LDAP Application Program Interface 17 November 2000
2248 or another LDAP result code if not. See the section below on error han-
2259 in the LDAP structure appropriately.
2263 operation was successful, or another LDAP result code if it was not.
2274 The following functions are used to delete a leaf entry from the LDAP
2278 LDAP *ld,
2286 LDAP *ld,
2296 C LDAP API C LDAP Application Program Interface 17 November 2000
2301 LDAP *ld,
2306 LDAP *ld,
2317 serverctrls List of LDAP server controls, or NULL if no server controls
2330 supported by LDAP.
2334 fully sent, or another LDAP result code if not. See the section below
2345 sion error parameters in the LDAP structure appropriately.
2352 C LDAP API C LDAP Application Program Interface 17 November 2000
2357 the operation was successful, or another LDAP result code if it was not.
2368 allow extended LDAP operations to be passed to the server, providing a
2372 LDAP *ld,
2381 LDAP *ld,
2399 serverctrls List of LDAP server controls, or NULL if no server controls
2408 C LDAP API C LDAP Application Program Interface 17 November 2000
2432 was successfully sent, or another LDAP result code if not. See the sec-
2442 successful, or another LDAP result code if it was not. See the section
2456 LDAP *ld,
2464 C LDAP API C LDAP Application Program Interface 17 November 2000
2471 LDAP *ld,
2480 serverctrls List of LDAP server controls, or NULL if no server controls
2488 another LDAP result code if not. See the section below on error han-
2498 ldap_result(). There is no server response to LDAP abandon operations.
2501 13. Obtaining Results and Peeking Inside LDAP Messages
2507 so for all LDAP operations other than search only one result message is
2511 longer tied in any caller-visible way to the LDAP request that produced
2514 nous search routine will never be affected by subsequent LDAP API calls
2520 C LDAP API C LDAP Application Program Interface 17 November 2000
2532 ldap_msgtype() returns the type of an LDAP message.
2534 ldap_msgid() returns the message ID of an LDAP message.
2537 LDAP *ld,
2576 C LDAP API C LDAP Application Program Interface 17 November 2000
2604 occurs, in which case the error parameters of the LDAP session handle
2611 ldap_msgtype() returns the type of the LDAP message it is passed as a
2615 ldap_msgid() returns the message ID associated with the LDAP message
2622 handle errors returned by other LDAP API routines. Note that
2632 C LDAP API C LDAP Application Program Interface 17 November 2000
2636 LDAP *ld,
2647 LDAP *ld,
2654 LDAP *ld,
2669 LDAP *ld,
2674 void ldap_perror( LDAP *ld, const char *msg );
2680 res The result of an LDAP operation as returned by
2688 C LDAP API C LDAP Application Program Interface 17 November 2000
2691 errcodep This result parameter will be filled in with the LDAP
2716 cating zero or more alternate LDAP servers where the
2744 C LDAP API C LDAP Application Program Interface 17 November 2000
2770 err For ldap_err2string(), an LDAP result code, as returned by
2771 ldap_parse_result() or another LDAP API call.
2780 result was successfully parsed and another LDAP API result code if not.
2782 result parameters are undefined. Note that the LDAP result code that
2788 ldap_err2string() is used to convert a numeric LDAP result code, as
2800 C LDAP API C LDAP Application Program Interface 17 November 2000
2813 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
2815 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
2817 int ldap_count_messages( LDAP *ld, LDAPMessage *res );
2856 C LDAP API C LDAP Application Program Interface 17 November 2000
2873 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
2875 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
2877 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
2879 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
2881 int ldap_count_entries( LDAP *ld, LDAPMessage *res );
2883 int ldap_count_references( LDAP *ld, LDAPMessage *res );
2912 C LDAP API C LDAP Application Program Interface 17 November 2000
2933 LDAP *ld,
2939 LDAP *ld,
2960 mem A pointer to memory allocated by the LDAP library, such as the
2968 C LDAP API C LDAP Application Program Interface 17 November 2000
3003 LDAP *ld,
3009 LDAP *ld,
3024 C LDAP API C LDAP Application Program Interface 17 November 2000
3068 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
3080 C LDAP API C LDAP Application Program Interface 17 November 2000
3127 ldap_get_entry_controls() is used to extract LDAP controls from an
3136 C LDAP API C LDAP Application Program Interface 17 November 2000
3140 LDAP *ld,
3158 ldap_get_entry_controls() returns an LDAP result code that indicates
3173 LDAP *ld,
3192 C LDAP API C LDAP Application Program Interface 17 November 2000
3197 the referrals (typically LDAP URLs) contained in ref. The
3215 ldap_parse_reference() returns an LDAP result code that indicates
3229 these functions are compatible with the University of Michigan LDAP 3.3
3248 C LDAP API C LDAP Application Program Interface 17 November 2000
3280 in the C LDAP API but is provided for the convenience of application
3304 C LDAP API C LDAP Application Program Interface 17 November 2000
3360 C LDAP API C LDAP Application Program Interface 17 November 2000
3416 C LDAP API C LDAP Application Program Interface 17 November 2000
3472 C LDAP API C LDAP Application Program Interface 17 November 2000
3498 The ber_flatten API call is not present in U-M LDAP 3.3.
3528 C LDAP API C LDAP Application Program Interface 17 November 2000
3584 C LDAP API C LDAP Application Program Interface 17 November 2000
3640 C LDAP API C LDAP Application Program Interface 17 November 2000
3696 C LDAP API C LDAP Application Program Interface 17 November 2000
3752 C LDAP API C LDAP Application Program Interface 17 November 2000
3808 C LDAP API C LDAP Application Program Interface 17 November 2000
3864 C LDAP API C LDAP Application Program Interface 17 November 2000
3920 C LDAP API C LDAP Application Program Interface 17 November 2000
3976 C LDAP API C LDAP Application Program Interface 17 November 2000
3979 [11] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension
3986 [13] T. Howes, "The String Representation of LDAP Search Filters," RFC
4032 C LDAP API C LDAP Application Program Interface 17 November 2000
4044 23. Appendix A - Sample C LDAP API Code
4051 LDAP *ld;
4058 /* open an LDAP session */
4088 C LDAP API C LDAP Application Program Interface 17 November 2000
4135 LDAP
4144 C LDAP API C LDAP Application Program Interface 17 November 2000
4151 LDAP
4158 As the LDAP protocol is extended, this C LDAP API will need to be
4167 ally changes the behavior of any existing C LDAP API function calls, the
4169 on an LDAP session affects a chain of messages that was previously
4200 C LDAP API C LDAP Application Program Interface 17 November 2000
4230 requirements contained in the last paragraph of the "LDAP Session Handle
4244 26.1. Opaque LDAP Structure
4246 In RFC 1823, some fields in the LDAP structure were exposed to applica-
4249 patibility with older applications, the LDAP structure is now entirely
4256 C LDAP API C LDAP Application Program Interface 17 November 2000
4312 C LDAP API C LDAP Application Program Interface 17 November 2000
4368 C LDAP API C LDAP Application Program Interface 17 November 2000
4397 binary compatibility of the C LDAP API can be maintained across ILP32
4402 In older implementations of the C LDAP API, such as those based on RFC
4406 data model would find the size of the types used by the C LDAP API to
4411 LDAP API implementation is free to choose the correct data type and the
4424 C LDAP API C LDAP Application Program Interface 17 November 2000
4450 "LDAP Session Handle Options" section: changed the name of the
4456 "Initializing an LDAP Session" section: allow use of the value zero
4460 application programmers to use the sizelimit from the LDAP session
4480 C LDAP API C LDAP Application Program Interface 17 November 2000
4485 "Overview of LDAP API Use and General Requirements" section: added
4493 "LDAP Session Handle Options" section: improved the text that
4499 "Result Codes" section: renamed section (was "LDAP Error Codes").
4505 "Performing LDAP Operations" section: replaced "All functions take a
4536 C LDAP API C LDAP Application Program Interface 17 November 2000
4543 "Obtaining Results and Peeking Inside LDAP Messages" section: added
4592 C LDAP API C LDAP Application Program Interface 17 November 2000