2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1998 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/ldap.info
6 @node LDAP Support, PostgreSQL Support, ToolTalk Support, top
10 XEmacs can be linked with a LDAP client library to provide Elisp primitives
11 to access directory servers using the Lightweight Directory Access Protocol.
14 * Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
15 * XEmacs LDAP API:: Lisp access to LDAP functions
16 * Syntax of Search Filters:: A brief summary of RFC 1558
19 @node Building XEmacs with LDAP support, XEmacs LDAP API, LDAP Support, LDAP Support
20 @comment node-name, next, previous, up
21 @section Building XEmacs with LDAP support
23 LDAP support must be added to XEmacs at build time since it requires
24 linking to an external LDAP client library. As of 21.2, XEmacs has been
25 successfully built and tested with
28 @item OpenLDAP 1.2 (@url{http://www.openldap.org/})
29 @item University of Michigan's LDAP 3.3 (@url{http://www.umich.edu/~dirsvcs/ldap/})
30 @item LDAP SDK 1.0 from Netscape Corp. (@url{http://developer.netscape.com/})
33 Other libraries conforming to RFC 1823 will probably work also but may
34 require some minor tweaking at C level.
36 The standard XEmacs configure script auto-detects an installed LDAP
37 library provided the library itself and the corresponding header files
38 can be found in the library and include paths. A successful detection
39 will be signalled in the final output of the configure script.
43 @node XEmacs LDAP API, Syntax of Search Filters, Building XEmacs with LDAP support, LDAP Support
44 @comment node-name, next, previous, up
45 @section XEmacs LDAP API
47 XEmacs LDAP API consists of two layers: a low-level layer which tries
48 to stay as close as possible to the C API (where practical) and a
49 higher-level layer which provides more convenient primitives to
52 The low-level API should be used directly for very specific purposes
53 (such as multiple operations on a connection) only. The higher-level
54 functions provide a more convenient way to access LDAP directories
55 hiding the subtleties of handling the connection, translating arguments
56 and ensuring compliance with LDAP internationalization rules and formats
57 (currently partly implemented only).
60 * LDAP Variables:: Lisp variables related to LDAP
61 * The High-Level LDAP API:: High-level LDAP lisp functions
62 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
63 * LDAP Internationalization:: I18n variables and functions
67 @node LDAP Variables, The High-Level LDAP API, XEmacs LDAP API, XEmacs LDAP API
68 @comment node-name, next, previous, up
69 @subsection LDAP Variables
71 @defvar ldap-default-host
72 The default LDAP server hostname.
73 A TCP port number can be appended to that name using a colon as
77 @defvar ldap-default-port
78 Default TCP port for LDAP connections.
79 Initialized from the LDAP library. Default value is 389.
82 @defvar ldap-default-base
83 Default base for LDAP searches.
84 This is a string using the syntax of RFC 1779.
85 For instance, "o=ACME, c=US" limits the search to the
86 Acme organization in the United States.
89 @defvar ldap-host-parameters-alist
90 An alist of per host options for LDAP transactions.
91 The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
92 @var{host} is the name of an LDAP server. A TCP port number can be
93 appended to that name using a colon as a separator.
94 @var{propn} and @var{valn} are
95 property/value pairs describing parameters for the server. Valid
99 The distinguished name of the user to bind as. This may look like
100 @samp{cn=Babs Jensen,o=ACME,c=US}, see RFC 1779 for details.
102 The password to use for authentication.
104 The authentication method to use, possible values depend on the LDAP
105 library XEmacs was compiled with, they may include @code{simple},
106 @code{krbv41} and @code{krbv42}.
108 The base for the search. This may look like @samp{cÿ, o¬me}, see
109 RFC 1779 for syntax details.
111 One of the symbols @code{base}, @code{onelevel} or @code{subtree}
112 indicating the scope of the search limited to a base
113 object, to a single level or to the whole subtree.
115 The dereference policy is one of the symbols @code{never},
116 @code{always}, @code{search} or @code{find} and defines how aliases are
120 Aliases are never dereferenced
122 Aliases are always dereferenced
124 Aliases are dereferenced when searching
126 Aliases are dereferenced when locating the base object for the search
129 The timeout limit for the connection in seconds.
131 The maximum number of matches to return for searches performed on this connection.
136 If non-@code{nil}, LDAP operations will echo progress messages. Defaults to @code{nil}.
140 @node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, XEmacs LDAP API
141 @comment node-name, next, previous, up
142 @subsection The High-Level LDAP API
144 The following functions provide the most convenient interface to perform
145 LDAP operations. All of them open a connection to a host, perform an
146 operation (add/search/modify/delete) on one or several entries and
147 cleanly close the connection thus insulating the user from all the
148 details of the low-level interface such as LDAP Lisp objects @pxref{The
151 Note that @code{ldap-search} which used to be the name of the high-level
152 search function in XEmacs 21.1 is now obsolete. For consistency in the
153 naming as well as backward compatibility, that function now acts as a
154 wrapper that calls either @code{ldap-search-basic} (low-level search
155 function) or @code{ldap-search-entries} (high-level search function)
156 according to the actual parameters. A direct call to one of these two
157 functions is preferred since it is faster and unambiguous.
159 @defun ldap-search-entries filter &optional host attributes attrsonly withdn
160 Perform an LDAP search.
161 @var{filter} is the search filter @pxref{Syntax of Search Filters}
162 @var{host} is the LDAP host on which to perform the search.
163 @var{attributes} is the specific attributes to retrieve, @code{nil} means
165 @var{attrsonly} if non-@code{nil} retrieves the attributes only without
166 their associated values.
167 If @var{withdn} is non-@code{nil} each entry in the result will be prepended with
168 its distinguished name DN.
169 Additional search parameters can be specified through
170 @code{ldap-host-parameters-alist}.
171 The function returns a list of matching entries. Each entry is itself
172 an alist of attribute/value pairs optionally preceded by the DN of the
173 entry according to the value of @var{withdn}.
176 @defun ldap-add-entries entries &optional host binddn passwd
177 Add entries to an LDAP directory. @var{entries} is a list of entry
178 specifications of the form @code{(DN (ATTR . VALUE) (ATTR . VALUE) ...)}
179 where @var{dn} the distinguished name of an entry to add, the following
180 are cons cells containing attribute/value string pairs. @var{host} is
181 the LDAP host, defaulting to `ldap-default-host' @var{binddn} is the DN
182 to bind as to the server @var{passwd} is the corresponding password.
185 @defun ldap-modify-entries entry-mods &optional host binddn passwd
186 Modify entries of an LDAP directory.
187 @var{entry_mods} is a list of entry modifications of the form
188 @code{(DN MOD-SPEC1 MOD-SPEC2 ...)} where @var{dn} is the distinguished name of
189 the entry to modify, the following are modification specifications.
190 A modification specification is itself a list of the form
191 @code{(MOD-OP ATTR VALUE1 VALUE2 ...)} @var{mod-op} and @var{attr} are mandatory,
192 @var{values} are optional depending on @var{mod-op}.
193 @var{mod-op} is the type of modification, one of the symbols @code{add}, @code{delete}
194 or @code{replace}. @var{attr} is the LDAP attribute type to modify.
195 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}
196 @var{binddn} is the DN to bind as to the server
197 @var{passwd} is the corresponding password"
200 @defun ldap-delete-entries dn &optional host binddn passwd
201 Delete an entry from an LDAP directory.
202 @var{dn} is the distinguished name of an entry to delete or
204 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}
205 @var{binddn} is the DN to bind as to the server
206 @var{passwd} is the corresponding password.
210 @node The Low-Level LDAP API, LDAP Internationalization, The High-Level LDAP API, XEmacs LDAP API
211 @comment node-name, next, previous, up
212 @subsection The Low-Level LDAP API
214 The low-level API should be used directly for very specific purposes
215 (such as multiple operations on a connection) only. The higher-level
216 functions provide a more convenient way to access LDAP directories
217 hiding the subtleties of handling the connection, translating arguments
218 and ensuring compliance with LDAP internationalization rules and formats
219 (currently partly implemented only). See @pxref{The High-Level LDAP API}
221 Note that the former functions @code{ldap-*-internal} functions have been
222 renamed in XEmacs 21.2
225 * The LDAP Lisp Object::
226 * Opening and Closing a LDAP Connection::
227 * Low-level Operations on a LDAP Server::
230 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
231 @comment node-name, next, previous, up
232 @subsubsection The LDAP Lisp Object
234 An internal built-in @code{ldap} lisp object represents a LDAP
238 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
241 @defun ldap-host ldap
242 Return the server host of the connection represented by @var{ldap}
245 @defun ldap-live-p ldap
246 Return non-@code{nil} if @var{ldap} is an active LDAP connection
250 @node Opening and Closing a LDAP Connection, Low-level Operations on a LDAP Server, The LDAP Lisp Object, The Low-Level LDAP API
251 @comment node-name, next, previous, up
252 @subsubsection Opening and Closing a LDAP Connection
254 @defun ldap-open host &optional plist
255 Open a LDAP connection to @var{host}.
256 @var{plist} is a property list containing additional parameters for the connection.
257 Valid keys in that list are:
260 The TCP port to use for the connection if different from
261 @code{ldap-default-port} or the library builtin value
263 The authentication method to use, possible values depend on the LDAP
264 library XEmacs was compiled with, they may include @code{simple},
265 @code{krbv41} and @code{krbv42}.
267 The distinguished name of the user to bind as. This may look like
268 @samp{c=com, o=Acme, cn=Babs Jensen}, see RFC 1779 for details.
270 The password to use for authentication.
272 The dereference policy is one of the symbols @code{never},
273 @code{always}, @code{search} or @code{find} and defines how aliases are
277 Aliases are never dereferenced
279 Aliases are always dereferenced
281 Aliases are dereferenced when searching
283 Aliases are dereferenced when locating the base object for the search
285 The default is @code{never}.
287 The timeout limit for the connection in seconds.
289 The maximum number of matches to return for searches performed on this connection.
293 @defun ldap-close ldap
294 Close the connection represented by @var{ldap}
298 @node Low-level Operations on a LDAP Server, , Opening and Closing a LDAP Connection, The Low-Level LDAP API
299 @comment node-name, next, previous, up
300 @subsubsection Low-level Operations on a LDAP Server
302 @code{ldap-search-basic} is the low-level primitive to perform a
303 search on a LDAP server. It works directly on an open LDAP connection
304 thus requiring a preliminary call to @code{ldap-open}. Multiple
305 searches can be made on the same connection, then the session must be
306 closed with @code{ldap-close}.
308 @defun ldap-search-basic ldap filter base scope attrs attrsonly
309 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
310 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
311 @var{base} is the distinguished name at which to start the search.
312 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
313 @code{subtree} indicating the scope of the search limited to a base
314 object, to a single level or to the whole subtree. The default is
316 @code{attrs} is a list of strings indicating which attributes to retrieve
317 for each matching entry. If @code{nil} all available attributes are returned.
318 If @code{attrsonly} is non-@code{nil} then only the attributes are retrieved, not
319 their associated values
320 If @code{withdn} is non-@code{nil} then each entry in the result is prepended with
321 its distinguished name DN
322 If @code{verbose} is non-@code{nil} then progress messages are echoed
323 The function returns a list of matching entries. Each entry is itself
324 an alist of attribute/value pairs optionally preceded by the DN of the
325 entry according to the value of @code{withdn}.
328 @defun ldap-add ldap dn entry
329 Add @var{entry} to a LDAP directory which a connection @var{ldap} has
330 been opened to with @code{ldap-open}.
331 @var{dn} is the distinguished name of the entry to add.
332 @var{entry} is an entry specification, i.e., a list of cons cells
333 containing attribute/value string pairs.
336 @defun ldap-modify ldap dn mods
337 Modify an entry in an LDAP directory.
338 @var{ldap} is an LDAP connection object created with @code{ldap-open}.
339 @var{dn} is the distinguished name of the entry to modify.
340 @var{mods} is a list of modifications to apply.
341 A modification is a list of the form @code{(MOD-OP ATTR VALUE1 VALUE2 ...)}
342 @var{mod-op} and @var{attr} are mandatory, @var{values} are optional depending on @var{mod-op}.
343 @var{mod-op} is the type of modification, one of the symbols @code{add}, @code{delete}
344 or @code{replace}. @var{attr} is the LDAP attribute type to modify
347 @defun ldap-delete ldap dn
348 Delete an entry to an LDAP directory.
349 @var{ldap} is an LDAP connection object created with @code{ldap-open}.
350 @var{dn} is the distinguished name of the entry to delete
355 @node LDAP Internationalization, , The Low-Level LDAP API, XEmacs LDAP API
356 @comment node-name, next, previous, up
357 @subsection LDAP Internationalization
359 The XEmacs LDAP API provides basic internationalization features based
360 on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 Attribute
361 Syntax Definitions"). Unfortunately since there is currently no free
362 LDAP v3 server software, this part has not received much testing and
363 should be considered experimental. The framework is in place though.
365 @defun ldap-decode-attribute attr
366 Decode the attribute/value pair @var{attr} according to LDAP rules.
367 The attribute name is looked up in @code{ldap-attribute-syntaxes-alist}
368 and the corresponding decoder is then retrieved from
369 @code{ldap-attribute-syntax-decoders}' and applied on the value(s).
373 * LDAP Internationalization Variables::
374 * Encoder/Decoder Functions::
377 @node LDAP Internationalization Variables, Encoder/Decoder Functions, LDAP Internationalization, LDAP Internationalization
378 @comment node-name, next, previous, up
379 @subsubsection LDAP Internationalization Variables
381 @defvar ldap-ignore-attribute-codings
382 If non-@code{nil}, no encoding/decoding will be performed LDAP attribute values
385 @defvar ldap-coding-system
386 Coding system of LDAP string values.
387 LDAP v3 specifies the coding system of strings to be UTF-8.
388 You need an XEmacs with Mule support for this.
391 @defvar ldap-default-attribute-decoder
392 Decoder function to use for attributes whose syntax is unknown. Such a
393 function receives an encoded attribute value as a string and should
394 return the decoded value as a string
397 @defvar ldap-attribute-syntax-encoders
398 A vector of functions used to encode LDAP attribute values.
399 The sequence of functions corresponds to the sequence of LDAP attribute syntax
400 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
401 RFC2252 section 4.3.2. As of this writing, only a few encoder functions
405 @defvar ldap-attribute-syntax-decoders
406 A vector of functions used to decode LDAP attribute values.
407 The sequence of functions corresponds to the sequence of LDAP attribute syntax
408 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
409 RFC2252 section 4.3.2. As of this writing, only a few decoder functions
413 @defvar ldap-attribute-syntaxes-alist
414 A map of LDAP attribute names to their type object id minor number.
415 This table is built from RFC2252 Section 5 and RFC2256 Section 5
418 @node Encoder/Decoder Functions, , LDAP Internationalization Variables, LDAP Internationalization
419 @comment node-name, next, previous, up
420 @subsubsection Encoder/Decoder Functions
422 @defun ldap-encode-boolean bool
423 A function that encodes an elisp boolean @var{bool} into a LDAP
424 boolean string representation
427 @defun ldap-decode-boolean str
428 A function that decodes a LDAP boolean string representation
429 @var{str} into an elisp boolean
432 @defun ldap-decode-string str
433 Decode a string @var{str} according to `ldap-coding-system'
436 @defun ldap-encode-string str
437 Encode a string @var{str} according to `ldap-coding-system'
440 @defun ldap-decode-address str
441 Decode an address @var{str} according to `ldap-coding-system' and
442 replacing $ signs with newlines as specified by LDAP encoding rules for
446 @defun ldap-encode-address str
447 Encode an address @var{str} according to `ldap-coding-system' and
448 replacing newlines with $ signs as specified by LDAP encoding rules for
454 @node Syntax of Search Filters, , XEmacs LDAP API, LDAP Support
455 @comment node-name, next, previous, up
456 @section Syntax of Search Filters
458 LDAP search functions use RFC1558 syntax to describe the search filter.
459 In that syntax simple filters have the form:
462 (<attr> <filtertype> <value>)
465 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
466 @code{o} for Organization, etc...
468 @code{<value>} is the corresponding value. This is generally an exact
469 string but may also contain @code{*} characters as wildcards
471 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
472 respectively describe equality, approximate equality, inferiority and
475 Thus @code{(cn=John Smith)} matches all records having a canonical name
478 A special case is the presence filter @code{(<attr>=*} which matches
479 records containing a particular attribute. For instance @code{(mail=*)}
480 matches all records containing a @code{mail} attribute.
482 Simple filters can be connected together with the logical operators
483 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
486 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
487 matches records of class @code{Person} containing a @code{mail}
488 attribute and corresponding to people whose last name is @code{Smith} or
489 whose first name is @code{John}.