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