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, PostgreSQL Support, 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.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/})
  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 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.
  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 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).
  58
  59 @menu
  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
  64 @end menu
  65
  66
  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
  70
  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
  74 a separator.
  75 @end defvar
  76
  77 @defvar ldap-default-port
  78 Default TCP port for LDAP connections.
  79 Initialized from the LDAP library. Default value is 389.
  80 @end defvar
  81
  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.
  87 @end defvar
  88
  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
  96 properties:
  97 @table @code
  98 @item binddn
  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.
 101 @item passwd
 102 The password to use for authentication.
 103 @item auth
 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}.
 107 @item base
 108 The base for the search. This may look like @samp{cÿ, o¬me}, see
 109 RFC 1779 for syntax details.
 110 @item scope
 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.
 114 @item deref
 115 The dereference policy is one of the symbols @code{never},
 116 @code{always}, @code{search} or @code{find} and defines how aliases are
 117 dereferenced.
 118 @table @code
 119 @item never
 120 Aliases are never dereferenced
 121 @item always
 122 Aliases are always dereferenced
 123 @item search
 124 Aliases are dereferenced when searching
 125 @item find
 126 Aliases are dereferenced when locating the base object for the search
 127 @end table
 128 @item timelimit
 129 The timeout limit for the connection in seconds.
 130 @item sizelimit
 131 The maximum number of matches to return for searches performed on this connection.
 132 @end table
 133 @end defvar
 134
 135 @defvar ldap-verbose
 136 If non-@code{nil}, LDAP operations will echo progress messages. Defaults to @code{nil}.
 137 @end defvar
 138
 139
 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
 143
 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
 149 Low-Level LDAP API}.
 150
 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.
 158
 159 @deffn Command 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
 164 retrieve all.
 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}.
 174 @end deffn
 175
 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.
 181 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}.
 182 @var{binddn} is the DN to bind as to the server.
 183 @var{passwd} is the corresponding password.
 184 @end defun
 185
 186 @defun ldap-modify-entries entry-mods &optional host binddn passwd
 187 Modify entries of an LDAP directory.
 188 @var{entry_mods} is a list of entry modifications of the form
 189 @code{(DN MOD-SPEC1 MOD-SPEC2 ...)} where @var{dn} is the distinguished name of
 190 the entry to modify, the following are modification specifications.
 191 A modification specification is itself a list of the form
 192 @code{(MOD-OP ATTR VALUE1 VALUE2 ...)} @var{mod-op} and @var{attr} are mandatory,
 193 @var{values} are optional depending on @var{mod-op}.
 194 @var{mod-op} is the type of modification, one of the symbols @code{add}, @code{delete}
 195 or @code{replace}. @var{attr} is the LDAP attribute type to modify.
 196 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}.
 197 @var{binddn} is the DN to bind as to the server.
 198 @var{passwd} is the corresponding password.
 199 @end defun
 200
 201 @defun ldap-delete-entries dn &optional host binddn passwd
 202 Delete an entry from an LDAP directory.
 203 @var{dn} is the distinguished name of an entry to delete or
 204 a list of those.
 205 @var{host} is the LDAP host, defaulting to @code{ldap-default-host}.
 206 @var{binddn} is the DN to bind as to the server.
 207 @var{passwd} is the corresponding password.
 208 @end defun
 209
 210
 211 @node The Low-Level LDAP API, LDAP Internationalization, The High-Level LDAP API, XEmacs LDAP API
 212 @comment  node-name,  next,  previous,  up
 213 @subsection The Low-Level LDAP API
 214
 215 The low-level API should be used directly for very specific purposes
 216 (such as multiple operations on a connection) only.  The higher-level
 217 functions provide a more convenient way to access LDAP directories
 218 hiding the subtleties of handling the connection, translating arguments
 219 and ensuring compliance with LDAP internationalization rules and formats
 220 (currently partly implemented only). See @pxref{The High-Level LDAP API}
 221
 222 Note that the former functions @code{ldap-*-internal} functions have been
 223 renamed in XEmacs 21.2
 224
 225 @menu
 226 * The LDAP Lisp Object::
 227 * Opening and Closing a LDAP Connection::
 228 * Low-level Operations on a LDAP Server::
 229 @end menu
 230
 231 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
 232 @comment  node-name,  next,  previous,  up
 233 @subsubsection The LDAP Lisp Object
 234
 235 An internal built-in @code{ldap} lisp object represents a LDAP
 236 connection.
 237
 238 @defun ldapp object
 239 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
 240 @end defun
 241
 242 @defun ldap-host ldap
 243 Return the server host of the connection represented by @var{ldap}.
 244 @end defun
 245
 246 @defun ldap-live-p ldap
 247 Return non-@code{nil} if @var{ldap} is an active LDAP connection.
 248 @end defun
 249
 250
 251 @node Opening and Closing a LDAP Connection, Low-level Operations on a LDAP Server, The LDAP Lisp Object, The Low-Level LDAP API
 252 @comment  node-name,  next,  previous,  up
 253 @subsubsection Opening and Closing a LDAP Connection
 254
 255 @defun ldap-open host &optional plist
 256 Open a LDAP connection to @var{host}.
 257 @var{plist} is a property list containing additional parameters for the connection.
 258 Valid keys in that list are:
 259 @table @code
 260 @item port
 261 The TCP port to use for the connection if different from
 262 @code{ldap-default-port} or the library builtin value
 263 @item auth
 264 The authentication method to use, possible values depend on the LDAP
 265 library XEmacs was compiled with, they may include @code{simple},
 266 @code{krbv41} and @code{krbv42}.
 267 @item binddn
 268 The distinguished name of the user to bind as.  This may look like
 269 @samp{c=com, o=Acme, cn=Babs Jensen}, see RFC 1779 for details.
 270 @item passwd
 271 The password to use for authentication.
 272 @item deref
 273 The dereference policy is one of the symbols @code{never},
 274 @code{always}, @code{search} or @code{find} and defines how aliases are
 275 dereferenced.
 276 @table @code
 277 @item never
 278 Aliases are never dereferenced.
 279 @item always
 280 Aliases are always dereferenced.
 281 @item search
 282 Aliases are dereferenced when searching.
 283 @item find
 284 Aliases are dereferenced when locating the base object for the search.
 285 @end table
 286 The default is @code{never}.
 287 @item timelimit
 288 The timeout limit for the connection in seconds.
 289 @item sizelimit
 290 The maximum number of matches to return for searches performed on this connection.
 291 @end table
 292 @end defun
 293
 294 @defun ldap-close ldap
 295 Close the connection represented by @var{ldap}.
 296 @end defun
 297
 298
 299 @node Low-level Operations on a LDAP Server,  , Opening and Closing a LDAP Connection, The Low-Level LDAP API
 300 @comment  node-name,  next,  previous,  up
 301 @subsubsection Low-level Operations on a LDAP Server
 302
 303 @code{ldap-search-basic} is the low-level primitive to perform a
 304 search on a LDAP server.  It works directly on an open LDAP connection
 305 thus requiring a preliminary call to @code{ldap-open}.  Multiple
 306 searches can be made on the same connection, then the session must be
 307 closed with @code{ldap-close}.
 308
 309 @defun ldap-search-basic ldap filter &optional base scope attrs attrsonly withdn verbose
 310 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
 311 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
 312 @var{base} is the distinguished name at which to start the search.
 313 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
 314 @code{subtree} indicating the scope of the search limited to a base
 315 object, to a single level or to the whole subtree.  The default is
 316 @code{subtree}.
 317 @var{attrs} is a list of strings indicating which attributes to retrieve
 318 for each matching entry. If @code{nil} all available attributes are returned.
 319 If @var{attrsonly} is non-@code{nil} then only the attributes are
 320 retrieved, not their associated values.
 321 If @var{withdn} is non-@code{nil} then each entry in the result is
 322 prepended with its distinguished name DN.
 323 If @var{verbose} is non-@code{nil} then progress messages are echoed
 324 The function returns a list of matching entries.  Each entry  is itself
 325 an alist of attribute/value pairs optionally preceded by the DN of the
 326 entry according to the value of @var{withdn}.
 327 @end defun
 328
 329 @defun ldap-add ldap dn entry
 330 Add @var{entry} to a LDAP directory which a connection @var{ldap} has
 331 been opened to with @code{ldap-open}.
 332 @var{dn} is the distinguished name of the entry to add.
 333 @var{entry} is an entry specification, i.e., a list of cons cells
 334 containing attribute/value string pairs.
 335 @end defun
 336
 337 @defun ldap-modify ldap dn mods
 338 Modify an entry in an LDAP directory.
 339 @var{ldap} is an LDAP connection object created with @code{ldap-open}.
 340 @var{dn} is the distinguished name of the entry to modify.
 341 @var{mods} is a list of modifications to apply.
 342 A modification is a list of the form @code{(MOD-OP ATTR VALUE1 VALUE2 ...)}
 343 @var{mod-op} and @var{attr} are mandatory, @var{values} are optional depending on @var{mod-op}.
 344 @var{mod-op} is the type of modification, one of the symbols @code{add}, @code{delete}
 345 or @code{replace}. @var{attr} is the LDAP attribute type to modify.
 346 @end defun
 347
 348 @defun ldap-delete ldap dn
 349 Delete an entry to an LDAP directory.
 350 @var{ldap} is an LDAP connection object created with @code{ldap-open}.
 351 @var{dn} is the distinguished name of the entry to delete.
 352 @end defun
 353
 354
 355
 356 @node LDAP Internationalization,  , The Low-Level LDAP API, XEmacs LDAP API
 357 @comment  node-name,  next,  previous,  up
 358 @subsection LDAP Internationalization
 359
 360 The XEmacs LDAP API provides basic internationalization features based
 361 on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 Attribute
 362 Syntax Definitions").  Unfortunately since there is currently no free
 363 LDAP v3 server software, this part has not received much testing and
 364 should be considered experimental.  The framework is in place though.
 365
 366 @defun ldap-decode-attribute attr
 367 Decode the attribute/value pair @var{attr} according to LDAP rules.
 368 The attribute name is looked up in @code{ldap-attribute-syntaxes-alist}
 369 and the corresponding decoder is then retrieved from
 370 @code{ldap-attribute-syntax-decoders}' and applied on the value(s).
 371 @end defun
 372
 373 @menu
 374 * LDAP Internationalization Variables::
 375 * Encoder/Decoder Functions::
 376 @end menu
 377
 378 @node LDAP Internationalization Variables, Encoder/Decoder Functions, LDAP Internationalization, LDAP Internationalization
 379 @comment  node-name,  next,  previous,  up
 380 @subsubsection LDAP Internationalization Variables
 381
 382 @defvar ldap-ignore-attribute-codings
 383 If non-@code{nil}, no encoding/decoding will be performed LDAP attribute values
 384 @end defvar
 385
 386 @defvar ldap-coding-system
 387 Coding system of LDAP string values.
 388 LDAP v3 specifies the coding system of strings to be UTF-8.
 389 You need an XEmacs with Mule support for this.
 390 @end defvar
 391
 392 @defvar ldap-default-attribute-decoder
 393 Decoder function to use for attributes whose syntax is unknown.  Such a
 394 function receives an encoded attribute value as a string and should
 395 return the decoded value as a string.
 396 @end defvar
 397
 398 @defvar ldap-attribute-syntax-encoders
 399 A vector of functions used to encode LDAP attribute values.
 400 The sequence of functions corresponds to the sequence of LDAP attribute syntax
 401 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
 402 RFC2252 section 4.3.2. As of this writing, only a few encoder functions
 403 are available.
 404 @end defvar
 405
 406 @defvar ldap-attribute-syntax-decoders
 407 A vector of functions used to decode LDAP attribute values.
 408 The sequence of functions corresponds to the sequence of LDAP attribute syntax
 409 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
 410 RFC2252 section 4.3.2. As of this writing, only a few decoder functions
 411 are available.
 412 @end defvar
 413
 414 @defvar ldap-attribute-syntaxes-alist
 415 A map of LDAP attribute names to their type object id minor number.
 416 This table is built from RFC2252 Section 5 and RFC2256 Section 5.
 417 @end defvar
 418
 419 @node Encoder/Decoder Functions,  , LDAP Internationalization Variables, LDAP Internationalization
 420 @comment  node-name,  next,  previous,  up
 421 @subsubsection Encoder/Decoder Functions
 422
 423 @defun ldap-encode-boolean bool
 424 A function that encodes an elisp boolean @var{bool} into a LDAP
 425 boolean string representation.
 426 @end defun
 427
 428 @defun ldap-decode-boolean str
 429 A function that decodes a LDAP boolean string representation
 430 @var{str} into an elisp boolean.
 431 @end defun
 432
 433 @defun ldap-decode-string str
 434 Decode a string @var{str} according to @code{ldap-coding-system}.
 435 @end defun
 436
 437 @defun ldap-encode-string str
 438 Encode a string @var{str} according to @code{ldap-coding-system}.
 439 @end defun
 440
 441 @defun ldap-decode-address str
 442 Decode an address @var{str} according to @code{ldap-coding-system} and
 443 replacing $ signs with newlines as specified by LDAP encoding rules for
 444 addresses.
 445 @end defun
 446
 447 @defun ldap-encode-address str
 448 Encode an address @var{str} according to @code{ldap-coding-system} and
 449 replacing newlines with $ signs as specified by LDAP encoding rules for
 450 addresses.
 451 @end defun
 452
 453
 454
 455 @node Syntax of Search Filters,  , XEmacs LDAP API, LDAP Support
 456 @comment  node-name,  next,  previous,  up
 457 @section Syntax of Search Filters
 458
 459 LDAP search functions use RFC1558 syntax to describe the search filter.
 460 In that syntax simple filters have the form:
 461
 462 @example
 463 (<attr> <filtertype> <value>)
 464 @end example
 465
 466 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
 467 @code{o} for Organization, etc...
 468
 469 @code{<value>} is the corresponding value.  This is generally an exact
 470 string but may also contain @code{*} characters as wildcards
 471
 472 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
 473 respectively describe equality, approximate equality, inferiority and
 474 superiority.
 475
 476 Thus @code{(cn=John Smith)} matches all records having a canonical name
 477 equal to John Smith.
 478
 479 A special case is the presence filter @code{(<attr>=*} which matches
 480 records containing a particular attribute.  For instance @code{(mail=*)}
 481 matches all records containing a @code{mail} attribute.
 482
 483 Simple filters can be connected together with the logical operators
 484 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
 485 not operators.
 486
 487 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
 488 matches records of class @code{Person} containing a @code{mail}
 489 attribute and corresponding to people whose last name is @code{Smith} or
 490 whose first name is @code{John}.