2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1998 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/ldap.info
8 @node LDAP Support, PostgreSQL Support, ToolTalk Support, top
12 SXEmacs can be linked with a LDAP client library to provide elisp primitives
13 to access directory servers using the Lightweight Directory Access Protocol.
16 * Building SXEmacs with LDAP support:: How to add LDAP support to SXEmacs
17 * SXEmacs LDAP API:: Lisp access to LDAP functions
18 * Syntax of Search Filters:: A brief summary of RFC 1558
21 @node Building SXEmacs with LDAP support, SXEmacs LDAP API, LDAP Support, LDAP Support
22 @comment node-name, next, previous, up
23 @section Building SXEmacs with LDAP support
25 LDAP support must be added to SXEmacs at build time since it requires
26 linking to an external LDAP client library. As of 22.1, SXEmacs has been
27 successfully built and tested with
30 @item OpenLDAP 2.2.6 (@url{http://www.openldap.org/})
31 @item University of Michigan's LDAP 3.3 (@url{http://www.umich.edu/~dirsvcs/ldap/})
32 @item LDAP SDK 1.0 from Netscape Corp. (@url{http://developer.netscape.com/})
35 Other libraries conforming to RFC 1823 will probably work also but may
36 require some minor tweaking at C level.
38 The standard SXEmacs configure script auto-detects an installed LDAP
39 library provided the library itself and the corresponding header files
40 can be found in the library and include paths. A successful detection
41 will be signalled in the final output of the configure script.
44 @node SXEmacs LDAP API, Syntax of Search Filters, Building SXEmacs with LDAP support, LDAP Support
45 @comment node-name, next, previous, up
46 @section SXEmacs LDAP API
48 SXEmacs LDAP API consists of two layers: a low-level layer which tries
49 to stay as close as possible to the C API (where practical) and a
50 higher-level layer which provides more convenient primitives to
53 The low-level API should be used directly for very specific purposes
54 (such as multiple operations on a connection) only. The higher-level
55 functions provide a more convenient way to access LDAP directories
56 hiding the subtleties of handling the connection, translating arguments
57 and ensuring compliance with LDAP internationalization rules and formats
58 (currently partly implemented only).
61 * LDAP Variables:: Lisp variables related to LDAP
62 * The High-Level LDAP API:: High-level LDAP lisp functions
63 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
64 * LDAP Internationalization:: I18n variables and functions
68 @node LDAP Variables, The High-Level LDAP API, SXEmacs LDAP API, SXEmacs LDAP API
69 @comment node-name, next, previous, up
70 @subsection LDAP Variables
72 @defvar ldap-default-host
73 The default LDAP server hostname.
74 A TCP port number can be appended to that name using a colon as
78 @defvar ldap-default-port
79 Default TCP port for LDAP connections.
80 Initialized from the LDAP library. Default value is 389.
83 @defvar ldap-default-base
84 Default base for LDAP searches.
85 This is a string using the syntax of RFC 1779.
86 For instance, "o=ACME, c=US" limits the search to the
87 Acme organization in the United States.
90 @defvar ldap-host-parameters-alist
91 An alist of per host options for LDAP transactions.
92 The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
93 @var{host} is the name of an LDAP server. A TCP port number can be
94 appended to that name using a colon as a separator.
95 @var{propn} and @var{valn} are
96 property/value pairs describing parameters for the server. Valid
100 The distinguished name of the user to bind as. This may look like
101 @samp{cn=Babs Jensen,o=ACME,c=US}, see RFC 1779 for details.
103 The password to use for authentication.
105 The authentication method to use, possible values depend on the LDAP
106 library SXEmacs was compiled with, they may include @code{simple},
107 @code{krbv41} and @code{krbv42}.
109 The base for the search. This may look like @samp{cÿ, o¬me}, see
110 RFC 1779 for syntax details.
112 One of the symbols @code{base}, @code{onelevel} or @code{subtree}
113 indicating the scope of the search limited to a base
114 object, to a single level or to the whole subtree.
116 The dereference policy is one of the symbols @code{never},
117 @code{always}, @code{search} or @code{find} and defines how aliases are
121 Aliases are never dereferenced
123 Aliases are always dereferenced
125 Aliases are dereferenced when searching
127 Aliases are dereferenced when locating the base object for the search
130 The timeout limit for the connection in seconds.
132 The maximum number of matches to return for searches performed on this connection.
137 If non-@code{nil}, LDAP operations will echo progress messages.
138 Defaults to @code{nil}.
142 @node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, SXEmacs LDAP API
143 @comment node-name, next, previous, up
144 @subsection The High-Level LDAP API
146 The following functions provide the most convenient interface to perform
147 LDAP operations. All of them open a connection to a host, perform an
148 operation (add/search/modify/delete) on one or several entries and
149 cleanly close the connection thus insulating the user from all the
150 details of the low-level interface such as LDAP Lisp objects @pxref{The
153 Note that @code{ldap-search} which used to be the name of the high-level
154 search function in SXEmacs 22.1 is now obsolete. For consistency in the
155 naming as well as backward compatibility, that function now acts as a
156 wrapper that calls either @code{ldap-search-basic} (low-level search
157 function) or @code{ldap-search-entries} (high-level search function)
158 according to the actual parameters. A direct call to one of these two
159 functions is preferred since it is faster and unambiguous.
161 @deffn Command ldap-search-entries filter &optional host attributes attrsonly withdn
162 Perform an LDAP search.
163 @var{filter} is the search filter @pxref{Syntax of Search Filters}
164 @var{host} is the LDAP host on which to perform the search.
165 @var{attributes} is the specific attributes to retrieve, @code{nil} means
167 @var{attrsonly} if non-@code{nil} retrieves the attributes only without
168 their associated values.
169 If @var{withdn} is non-@code{nil} each entry in the result will be prepended with
170 its distinguished name DN.
171 Additional search parameters can be specified through
172 @code{ldap-host-parameters-alist}.
173 The function returns a list of matching entries. Each entry is itself
174 an alist of attribute/value pairs optionally preceded by the DN of the
175 entry according to the value of @var{withdn}.
178 @defun ldap-add-entries entries &optional host binddn passwd
179 Add entries to an LDAP directory. @var{entries} is a list of entry
180 specifications of the form @code{(DN (ATTR . VALUE) (ATTR . VALUE) ...)}
181 where @var{dn} the distinguished name of an entry to add, the following
182 are cons cells containing attribute/value string pairs.
183 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}.
184 @var{binddn} is the DN to bind as to the server.
185 @var{passwd} is the corresponding password.
188 @defun ldap-modify-entries entry-mods &optional host binddn passwd
189 Modify entries of an LDAP directory.
190 @var{entry_mods} is a list of entry modifications of the form
191 @code{(DN MOD-SPEC1 MOD-SPEC2 ...)} where @var{dn} is the distinguished name of
192 the entry to modify, the following are modification specifications.
193 A modification specification is itself a list of the form
194 @code{(MOD-OP ATTR VALUE1 VALUE2 ...)} @var{mod-op} and @var{attr} are mandatory,
195 @var{values} are optional depending on @var{mod-op}.
196 @var{mod-op} is the type of modification, one of the symbols @code{add}, @code{delete}
197 or @code{replace}. @var{attr} is the LDAP attribute type to modify.
198 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}.
199 @var{binddn} is the DN to bind as to the server.
200 @var{passwd} is the corresponding password.
203 @defun ldap-delete-entries dn &optional host binddn passwd
204 Delete an entry from an LDAP directory.
205 @var{dn} is the distinguished name of an entry to delete or
207 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}.
208 @var{binddn} is the DN to bind as to the server.
209 @var{passwd} is the corresponding password.
213 @node The Low-Level LDAP API, LDAP Internationalization, The High-Level LDAP API, SXEmacs LDAP API
214 @comment node-name, next, previous, up
215 @subsection The Low-Level LDAP API
217 The low-level API should be used directly for very specific purposes
218 (such as multiple operations on a connection) only. The higher-level
219 functions provide a more convenient way to access LDAP directories
220 hiding the subtleties of handling the connection, translating arguments
221 and ensuring compliance with LDAP internationalization rules and formats
222 (currently partly implemented only). See @pxref{The High-Level LDAP API}
224 Note that the former functions @code{ldap-*-internal} functions have been
225 renamed in SXEmacs 22.1
228 * The LDAP Lisp Object::
229 * Opening and Closing a LDAP Connection::
230 * Low-level Operations on a LDAP Server::
234 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
235 @comment node-name, next, previous, up
236 @subsubsection The LDAP Lisp Object
238 An internal built-in @code{ldap} lisp object represents a LDAP
242 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
245 @defun ldap-host ldap
246 Return the server host of the connection represented by @var{ldap}.
249 @defun ldap-live-p ldap
250 Return non-@code{nil} if @var{ldap} is an active LDAP connection.
254 @node Opening and Closing a LDAP Connection, Low-level Operations on a LDAP Server, The LDAP Lisp Object, The Low-Level LDAP API
255 @comment node-name, next, previous, up
256 @subsubsection Opening and Closing a LDAP Connection
258 @defun ldap-open host &optional plist
259 Open a LDAP connection to @var{host}.
260 @var{plist} is a property list containing additional parameters for the connection.
261 Valid keys in that list are:
264 The TCP port to use for the connection if different from
265 @code{ldap-default-port} or the library builtin value
267 The authentication method to use, possible values depend on the LDAP
268 library SXEmacs was compiled with, they may include @code{simple},
269 @code{krbv41} and @code{krbv42}.
271 The distinguished name of the user to bind as. This may look like
272 @samp{c=com, o=Acme, cn=Babs Jensen}, see RFC 1779 for details.
274 The password to use for authentication.
276 The dereference policy is one of the symbols @code{never},
277 @code{always}, @code{search} or @code{find} and defines how aliases are
281 Aliases are never dereferenced.
283 Aliases are always dereferenced.
285 Aliases are dereferenced when searching.
287 Aliases are dereferenced when locating the base object for the search.
289 The default is @code{never}.
291 The timeout limit for the connection in seconds.
293 The maximum number of matches to return for searches performed on this connection.
297 @defun ldap-close ldap
298 Close the connection represented by @var{ldap}.
302 @node Low-level Operations on a LDAP Server, , Opening and Closing a LDAP Connection, The Low-Level LDAP API
303 @comment node-name, next, previous, up
304 @subsubsection Low-level Operations on a LDAP Server
306 @code{ldap-search-basic} is the low-level primitive to perform a
307 search on a LDAP server. It works directly on an open LDAP connection
308 thus requiring a preliminary call to @code{ldap-open}. Multiple
309 searches can be made on the same connection, then the session must be
310 closed with @code{ldap-close}.
312 @defun ldap-search-basic ldap filter &optional base scope attrs attrsonly withdn verbose
313 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
314 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
315 @var{base} is the distinguished name at which to start the search.
316 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
317 @code{subtree} indicating the scope of the search limited to a base
318 object, to a single level or to the whole subtree. The default is
320 @var{attrs} is a list of strings indicating which attributes to retrieve
321 for each matching entry. If @code{nil} all available attributes are returned.
322 If @var{attrsonly} is non-@code{nil} then only the attributes are
323 retrieved, not their associated values.
324 If @var{withdn} is non-@code{nil} then each entry in the result is
325 prepended with its distinguished name DN.
326 If @var{verbose} is non-@code{nil} then progress messages are echoed
327 The function returns a list of matching entries. Each entry is itself
328 an alist of attribute/value pairs optionally preceded by the DN of the
329 entry according to the value of @var{withdn}.
332 @defun ldap-add ldap dn entry
333 Add @var{entry} to a LDAP directory which a connection @var{ldap} has
334 been opened to with @code{ldap-open}.
335 @var{dn} is the distinguished name of the entry to add.
336 @var{entry} is an entry specification, i.e., a list of cons cells
337 containing attribute/value string pairs.
340 @defun ldap-modify ldap dn mods
341 Modify an entry in an LDAP directory.
342 @var{ldap} is an LDAP connection object created with @code{ldap-open}.
343 @var{dn} is the distinguished name of the entry to modify.
344 @var{mods} is a list of modifications to apply.
345 A modification is a list of the form @code{(MOD-OP ATTR VALUE1 VALUE2 ...)}
346 @var{mod-op} and @var{attr} are mandatory, @var{values} are optional
347 depending on @var{mod-op}.
348 @var{mod-op} is the type of modification, one of the symbols @code{add},
350 or @code{replace}. @var{attr} is the LDAP attribute type to modify.
353 @defun ldap-delete ldap dn
354 Delete an entry to an LDAP directory.
355 @var{ldap} is an LDAP connection object created with @code{ldap-open}.
356 @var{dn} is the distinguished name of the entry to delete.
360 @node LDAP Internationalization, , The Low-Level LDAP API, SXEmacs LDAP API
361 @comment node-name, next, previous, up
362 @subsection LDAP Internationalization
364 The SXEmacs LDAP API provides basic internationalization features based
365 on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 Attribute
366 Syntax Definitions"). Unfortunately since there is currently no free
367 LDAP v3 server software, this part has not received much testing and
368 should be considered experimental. The framework is in place though.
370 @defun ldap-decode-attribute attr
371 Decode the attribute/value pair @var{attr} according to LDAP rules.
372 The attribute name is looked up in @code{ldap-attribute-syntaxes-alist}
373 and the corresponding decoder is then retrieved from
374 @code{ldap-attribute-syntax-decoders}' and applied on the value(s).
378 * LDAP Internationalization Variables::
379 * Encoder/Decoder Functions::
382 @node LDAP Internationalization Variables, Encoder/Decoder Functions, LDAP Internationalization, LDAP Internationalization
383 @comment node-name, next, previous, up
384 @subsubsection LDAP Internationalization Variables
386 @defvar ldap-ignore-attribute-codings
387 If non-@code{nil}, no encoding/decoding will be performed LDAP attribute values
390 @defvar ldap-coding-system
391 Coding system of LDAP string values.
392 LDAP v3 specifies the coding system of strings to be UTF-8.
393 You need an SXEmacs with Mule support for this.
396 @defvar ldap-default-attribute-decoder
397 Decoder function to use for attributes whose syntax is unknown. Such a
398 function receives an encoded attribute value as a string and should
399 return the decoded value as a string.
402 @defvar ldap-attribute-syntax-encoders
403 A vector of functions used to encode LDAP attribute values.
404 The sequence of functions corresponds to the sequence of LDAP attribute syntax
405 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
406 RFC2252 section 4.3.2. As of this writing, only a few encoder functions
410 @defvar ldap-attribute-syntax-decoders
411 A vector of functions used to decode LDAP attribute values.
412 The sequence of functions corresponds to the sequence of LDAP attribute syntax
413 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
414 RFC2252 section 4.3.2. As of this writing, only a few decoder functions
418 @defvar ldap-attribute-syntaxes-alist
419 A map of LDAP attribute names to their type object id minor number.
420 This table is built from RFC2252 Section 5 and RFC2256 Section 5.
423 @node Encoder/Decoder Functions, , LDAP Internationalization Variables, LDAP Internationalization
424 @comment node-name, next, previous, up
425 @subsubsection Encoder/Decoder Functions
427 @defun ldap-encode-boolean bool
428 A function that encodes an elisp boolean @var{bool} into a LDAP
429 boolean string representation.
432 @defun ldap-decode-boolean str
433 A function that decodes a LDAP boolean string representation
434 @var{str} into an elisp boolean.
437 @defun ldap-decode-string str
438 Decode a string @var{str} according to @code{ldap-coding-system}.
441 @defun ldap-encode-string str
442 Encode a string @var{str} according to @code{ldap-coding-system}.
445 @defun ldap-decode-address str
446 Decode an address @var{str} according to @code{ldap-coding-system} and
447 replacing $ signs with newlines as specified by LDAP encoding rules for
451 @defun ldap-encode-address str
452 Encode an address @var{str} according to @code{ldap-coding-system} and
453 replacing newlines with $ signs as specified by LDAP encoding rules for
458 @node Syntax of Search Filters, , SXEmacs LDAP API, LDAP Support
459 @comment node-name, next, previous, up
460 @section Syntax of Search Filters
462 LDAP search functions use RFC1558 syntax to describe the search filter.
463 In that syntax simple filters have the form:
466 (<attr> <filtertype> <value>)
469 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
470 @code{o} for Organization, etc...
472 @code{<value>} is the corresponding value. This is generally an exact
473 string but may also contain @code{*} characters as wildcards
475 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
476 respectively describe equality, approximate equality, inferiority and
479 Thus @code{(cn=John Smith)} matches all records having a canonical name
482 A special case is the presence filter @code{(<attr>=*} which matches
483 records containing a particular attribute. For instance @code{(mail=*)}
484 matches all records containing a @code{mail} attribute.
486 Simple filters can be connected together with the logical operators
487 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
490 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
491 matches records of class @code{Person} containing a @code{mail}
492 attribute and corresponding to people whose last name is @code{Smith} or
493 whose first name is @code{John}.