git.chise.org Git - chise/xemacs-chise.git.1/blob - man/lispref/ldap.texi

   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