|
428
|
1 @c -*-texinfo-*-
|
|
|
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, Internationalization, ToolTalk Support, top
|
|
|
7 @chapter LDAP Support
|
|
|
8 @cindex LDAP
|
|
|
9
|
|
|
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.
|
|
|
12
|
|
|
13 @menu
|
|
|
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
|
|
|
17 @end menu
|
|
|
18
|
|
|
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
|
|
|
22
|
|
|
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
|
|
|
26
|
|
|
27 @itemize @bullet
|
|
|
28 @item OpenLDAP 1.0.3 (@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/})
|
|
|
31 @end itemize
|
|
|
32
|
|
|
33 Other libraries conforming to RFC 1823 will probably work also but may
|
|
|
34 require some minor tweaking at C level.
|
|
|
35
|
|
|
36 The standard XEmacs configure script autodetects 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.
|
|
|
40
|
|
|
41
|
|
|
42
|
|
|
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
|
|
|
46
|
|
|
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
|
|
|
50 effectively use LDAP.
|
|
|
51
|
|
|
52 As of XEmacs 21.0, only interfaces to basic LDAP search functions are
|
|
|
53 provided, broader support is planned in future versions.
|
|
|
54
|
|
|
55 @menu
|
|
|
56 * LDAP Variables:: Lisp variables related to LDAP
|
|
|
57 * The High-Level LDAP API:: High-level LDAP lisp functions
|
|
|
58 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
|
|
|
59 @end menu
|
|
|
60
|
|
|
61
|
|
|
62 @node LDAP Variables, The High-Level LDAP API, XEmacs LDAP API, XEmacs LDAP API
|
|
|
63 @comment node-name, next, previous, up
|
|
|
64 @subsection LDAP Variables
|
|
|
65
|
|
|
66 @defvar ldap-default-host
|
|
|
67 The default LDAP server hostname.
|
|
|
68 A TCP port number can be appended to that name using a colon as
|
|
|
69 a separator.
|
|
|
70 @end defvar
|
|
|
71
|
|
|
72 @defvar ldap-default-port
|
|
|
73 Default TCP port for LDAP connections.
|
|
|
74 Initialized from the LDAP library. Default value is 389.
|
|
|
75 @end defvar
|
|
|
76
|
|
|
77 @defvar ldap-default-base
|
|
|
78 Default base for LDAP searches.
|
|
|
79 This is a string using the syntax of RFC 1779.
|
|
|
80 For instance, "o¬ME, cÿ" limits the search to the
|
|
|
81 Acme organization in the United States.
|
|
|
82 @end defvar
|
|
|
83
|
|
|
84 @defvar ldap-host-parameters-alist
|
|
|
85 An alist of per host options for LDAP transactions.
|
|
|
86 The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
|
|
|
87 @var{host} is the name of an LDAP server. A TCP port number can be
|
|
|
88 appended to that name using a colon as a separator.
|
|
|
89 @var{propn} and @var{valn} are
|
|
|
90 property/value pairs describing parameters for the server. Valid
|
|
|
91 properties:
|
|
|
92 @table @code
|
|
|
93 @item binddn
|
|
|
94 The distinguished name of the user to bind as. This may look like
|
|
|
95 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
|
|
|
96 @item passwd
|
|
|
97 The password to use for authentication.
|
|
|
98 @item auth
|
|
|
99 The authentication method to use, possible values depend on the LDAP
|
|
|
100 library XEmacs was compiled with, they may include @code{simple},
|
|
|
101 @code{krbv41} and @code{krbv42}.
|
|
|
102 @item base
|
|
|
103 The base for the search. This may look like @samp{cÿ, o¬me}, see
|
|
|
104 RFC 1779 for syntax details.
|
|
|
105 @item scope
|
|
|
106 One of the symbols @code{base}, @code{onelevel} or @code{subtree}
|
|
|
107 indicating the scope of the search limited to a base
|
|
|
108 object, to a single level or to the whole subtree.
|
|
|
109 @item deref
|
|
|
110 The dereference policy is one of the symbols @code{never},
|
|
|
111 @code{always}, @code{search} or @code{find} and defines how aliases are
|
|
|
112 dereferenced.
|
|
|
113 @table @code
|
|
|
114 @item never
|
|
|
115 Aliases are never dereferenced
|
|
|
116 @item always
|
|
|
117 Aliases are always dereferenced
|
|
|
118 @item search
|
|
|
119 Aliases are dereferenced when searching
|
|
|
120 @item find
|
|
|
121 Aliases are dereferenced when locating the base object for the search
|
|
|
122 @end table
|
|
|
123 @item timelimit
|
|
|
124 The timeout limit for the connection in seconds.
|
|
|
125 @item sizelimit
|
|
|
126 The maximum number of matches to return for searches performed on this connection.
|
|
|
127 @end table
|
|
|
128 @end defvar
|
|
|
129
|
|
|
130
|
|
|
131
|
|
|
132 @node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, XEmacs LDAP API
|
|
|
133 @comment node-name, next, previous, up
|
|
|
134 @subsection The High-Level LDAP API
|
|
|
135
|
|
|
136 As of this writing the high-level Lisp LDAP API only provides for LDAP
|
|
|
137 searches. Further support is planned in the future.
|
|
|
138
|
|
|
139 The @code{ldap-search} function provides the most convenient interface
|
|
|
140 to perform LDAP searches. It opens a connection to a host, performs the
|
|
|
141 query and cleanly closes the connection thus insulating the user from
|
|
|
142 all the details of the low-level interface such as LDAP Lisp objects
|
|
|
143 @pxref{The Low-Level LDAP API}
|
|
|
144
|
|
|
145 @defun ldap-search filter &optional host attributes attrsonly
|
|
|
146 Perform an LDAP search.
|
|
|
147 @var{filter} is the search filter @pxref{Syntax of Search Filters}
|
|
|
148 @var{host} is the LDAP host on which to perform the search
|
|
|
149 @var{attributes} is the specific attributes to retrieve, @code{nil} means
|
|
|
150 retrieve all
|
|
|
151 @var{attrsonly} if non-@code{nil} retrieves the attributes only without
|
|
|
152 their associated values.
|
|
|
153 Additional search parameters can be specified through
|
|
|
154 @code{ldap-host-parameters-alist}.
|
|
|
155 @end defun
|
|
|
156
|
|
|
157 @node The Low-Level LDAP API, , The High-Level LDAP API, XEmacs LDAP API
|
|
|
158 @comment node-name, next, previous, up
|
|
|
159 @subsection The Low-Level LDAP API
|
|
|
160
|
|
|
161 @menu
|
|
|
162 * The LDAP Lisp Object::
|
|
|
163 * Opening and Closing a LDAP Connection::
|
|
|
164 * Searching on a LDAP Server (Low-level)::
|
|
|
165 @end menu
|
|
|
166
|
|
|
167 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
|
|
|
168 @comment node-name, next, previous, up
|
|
|
169 @subsubsection The LDAP Lisp Object
|
|
|
170
|
|
|
171 An internal built-in @code{ldap} lisp object represents a LDAP
|
|
|
172 connection.
|
|
|
173
|
|
|
174 @defun ldapp object
|
|
|
175 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
|
|
|
176 @end defun
|
|
|
177
|
|
|
178 @defun ldap-host ldap
|
|
|
179 Return the server host of the connection represented by @var{ldap}
|
|
|
180 @end defun
|
|
|
181
|
|
|
182 @defun ldap-live-p ldap
|
|
|
183 Return non-@code{nil} if @var{ldap} is an active LDAP connection
|
|
|
184 @end defun
|
|
|
185
|
|
|
186
|
|
|
187 @node Opening and Closing a LDAP Connection, Searching on a LDAP Server (Low-level), The LDAP Lisp Object, The Low-Level LDAP API
|
|
|
188 @comment node-name, next, previous, up
|
|
|
189 @subsubsection Opening and Closing a LDAP Connection
|
|
|
190
|
|
|
191 @defun ldap-open host &optional plist
|
|
|
192 Open a LDAP connection to @var{host}.
|
|
|
193 @var{plist} is a property list containing additional parameters for the connection.
|
|
|
194 Valid keys in that list are:
|
|
|
195 @table @code
|
|
|
196 @item port
|
|
|
197 The TCP port to use for the connection if different from
|
|
|
198 @code{ldap-default-port} or the library builtin value
|
|
|
199 @item auth
|
|
|
200 The authentication method to use, possible values depend on the LDAP
|
|
|
201 library XEmacs was compiled with, they may include @code{simple},
|
|
|
202 @code{krbv41} and @code{krbv42}.
|
|
|
203 @item binddn
|
|
|
204 The distinguished name of the user to bind as. This may look like
|
|
|
205 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
|
|
|
206 @item passwd
|
|
|
207 The password to use for authentication.
|
|
|
208 @item deref
|
|
|
209 The dereference policy is one of the symbols @code{never},
|
|
|
210 @code{always}, @code{search} or @code{find} and defines how aliases are
|
|
|
211 dereferenced.
|
|
|
212 @table @code
|
|
|
213 @item never
|
|
|
214 Aliases are never dereferenced
|
|
|
215 @item always
|
|
|
216 Aliases are always dereferenced
|
|
|
217 @item search
|
|
|
218 Aliases are dereferenced when searching
|
|
|
219 @item find
|
|
|
220 Aliases are dereferenced when locating the base object for the search
|
|
|
221 @end table
|
|
|
222 The default is @code{never}.
|
|
|
223 @item timelimit
|
|
|
224 The timeout limit for the connection in seconds.
|
|
|
225 @item sizelimit
|
|
|
226 The maximum number of matches to return for searches performed on this connection.
|
|
|
227 @end table
|
|
|
228 @end defun
|
|
|
229
|
|
|
230 @defun ldap-close ldap
|
|
|
231 Close the connection represented by @var{ldap}
|
|
|
232 @end defun
|
|
|
233
|
|
|
234
|
|
|
235 @node Searching on a LDAP Server (Low-level), , Opening and Closing a LDAP Connection, The Low-Level LDAP API
|
|
|
236 @comment node-name, next, previous, up
|
|
|
237 @subsubsection Searching on a LDAP Server (Low-level)
|
|
|
238
|
|
|
239 @code{ldap-search-internal} is the low-level primitive to perform a
|
|
|
240 search on a LDAP server. It works directly on an open LDAP connection
|
|
|
241 thus requiring a preliminary call to @code{ldap-open}. Multiple
|
|
|
242 searches can be made on the same connection, then the session must be
|
|
|
243 closed with @code{ldap-close}.
|
|
|
244
|
|
|
245
|
|
|
246 @defun ldap-search-internal ldap filter base scope attrs attrsonly
|
|
|
247 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
|
|
|
248 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
|
|
|
249 @var{base} is the distinguished name at which to start the search.
|
|
|
250 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
|
|
|
251 @code{subtree} indicating the scope of the search limited to a base
|
|
|
252 object, to a single level or to the whole subtree. The default is
|
|
|
253 @code{subtree}.
|
|
|
254 @code{attrs} is a list of strings indicating which attributes to retrieve
|
|
|
255 for each matching entry. If @code{nil} all available attributes are returned.
|
|
|
256 If @code{attrsonly} is non-@code{nil} then only the attributes are retrieved, not
|
|
|
257 their associated values
|
|
|
258 The function returns a list of matching entries. Each entry being itself
|
|
|
259 an alist of attribute/values.
|
|
|
260 @end defun
|
|
|
261
|
|
|
262
|
|
|
263
|
|
|
264
|
|
|
265
|
|
|
266 @node Syntax of Search Filters, , XEmacs LDAP API, LDAP Support
|
|
|
267 @comment node-name, next, previous, up
|
|
|
268 @section Syntax of Search Filters
|
|
|
269
|
|
|
270 LDAP search functions use RFC1558 syntax to describe the search filter.
|
|
|
271 In that syntax simple filters have the form:
|
|
|
272
|
|
|
273 @example
|
|
|
274 (<attr> <filtertype> <value>)
|
|
|
275 @end example
|
|
|
276
|
|
|
277 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
|
|
|
278 @code{o} for Organization, etc...
|
|
|
279
|
|
|
280 @code{<value>} is the corresponding value. This is generally an exact
|
|
|
281 string but may also contain @code{*} characters as wildcards
|
|
|
282
|
|
|
283 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
|
|
|
284 respectively describe equality, approximate equality, inferiority and
|
|
|
285 superiority.
|
|
|
286
|
|
|
287 Thus @code{(cn=John Smith)} matches all records having a canonical name
|
|
|
288 equal to John Smith.
|
|
|
289
|
|
|
290 A special case is the presence filter @code{(<attr>=*} which matches
|
|
|
291 records containing a particular attribute. For instance @code{(mail=*)}
|
|
|
292 matches all records containing a @code{mail} attribute.
|
|
|
293
|
|
|
294 Simple filters can be connected together with the logical operators
|
|
|
295 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
|
|
|
296 not operators.
|
|
|
297
|
|
|
298 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
|
|
|
299 matches records of class @code{Person} containing a @code{mail}
|
|
|
300 attribute and corresponding to people whose last name is @code{Smith} or
|
|
|
301 whose first name is @code{John}.
|
|
|
302
|
|
|
303
|
|
|
304
|
