LDAP Support
************

XEmacs can be linked with a LDAP client library to provide Elisp primitives to access directory servers using the Lightweight Directory Access Protocol.

Building XEmacs with LDAP support
=================================

LDAP support must be added to XEmacs at build time since it requires linking to an external LDAP client library.  As of 21.2, XEmacs has been successfully built and tested with

  * OpenLDAP 1.0.3 (http://www.openldap.org/)

  * University of Michigan's LDAP 3.3 (http://www.umich.edu/~dirsvcs/ldap/)

  * LDAP SDK 1.0 from Netscape Corp. (http://developer.netscape.com/)

Other libraries conforming to RFC 1823 will probably work also but may require some minor tweaking at C level.

The standard XEmacs configure script autodetects an installed LDAP library provided the library itself and the corresponding header files can be found in the library and include paths.  A successful detection will be signalled in the final output of the configure script.

XEmacs LDAP API
===============

XEmacs LDAP API consists of two layers:  a low-level layer which tries to stay as close as possible to the C API (where practical) and a higher-level layer which provides more convenient primitives to effectively use LDAP.

As of XEmacs 21.0, only interfaces to basic LDAP search functions are provided, broader support is planned in future versions.

LDAP Variables
--------------

 -- Variable: ldap-default-host
     The default LDAP server hostname. A TCP port number can be appended to that name using a colon as a separator.

 -- Variable: ldap-default-port
     Default TCP port for LDAP connections. Initialized from the LDAP library. Default value is 389.

 -- Variable: ldap-default-base
     Default base for LDAP searches. This is a string using the syntax of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the Acme organization in the United States.

 -- Variable: ldap-host-parameters-alist
     An alist of per host options for LDAP transactions. The list elements look like (HOST PROP1 VAL1 PROP2 VAL2 ...) HOST is the name of an LDAP server. A TCP port number can be appended to that name using a colon as a separator. PROPN and VALN are property/value pairs describing parameters for the server.  Valid properties:

     binddn
          The distinguished name of the user to bind as.  This may look like cÿ, o¬me, cnÿnny Bugs, see RFC 1779 for details.

     passwd
          The password to use for authentication.

     auth
          The authentication method to use, possible values depend on the LDAP library XEmacs was compiled with, they may include simple, krbv41 and krbv42.

     base
          The base for the search. This may look like cÿ, o¬me, see RFC 1779 for syntax details.

     scope
          One of the symbols base, onelevel or subtree indicating the scope of the search limited to a base object, to a single level or to the whole subtree.

     deref
          The dereference policy is one of the symbols never, always, search or find and defines how aliases are dereferenced.

          never
               Aliases are never dereferenced

          always
               Aliases are always dereferenced

          search
               Aliases are dereferenced when searching

          find
               Aliases are dereferenced when locating the base object for the search

     timelimit
          The timeout limit for the connection in seconds.

     sizelimit
          The maximum number of matches to return for searches performed on this connection.

The High-Level LDAP API
-----------------------

As of this writing the high-level Lisp LDAP API only provides for LDAP searches.  Further support is planned in the future.

The ldap-search function provides the most convenient interface to perform LDAP searches.  It opens a connection to a host, performs the query and cleanly closes the connection thus insulating the user from all the details of the low-level interface such as LDAP Lisp objects see The Low-Level LDAP API

 -- Function: ldap-search filter &optional host attributes attrsonly
     Perform an LDAP search. FILTER is the search filter see Syntax of Search Filters HOST is the LDAP host on which to perform the search ATTRIBUTES is the specific attributes to retrieve, nil means retrieve all ATTRSONLY if non-nil retrieves the attributes only without their associated values. Additional search parameters can be specified through ldap-host-parameters-alist.

The Low-Level LDAP API
----------------------

The LDAP Lisp Object
....................

An internal built-in ldap lisp object represents a LDAP connection.

 -- Function: ldapp object
     This function returns non-nil if OBJECT is a ldap object.

 -- Function: ldap-host ldap
     Return the server host of the connection represented by LDAP

 -- Function: ldap-live-p ldap
     Return non-nil if LDAP is an active LDAP connection

Opening and Closing a LDAP Connection
.....................................

 -- Function: ldap-open host &optional plist
     Open a LDAP connection to HOST. PLIST is a property list containing additional parameters for the connection. Valid keys in that list are:

     port
          The TCP port to use for the connection if different from ldap-default-port or the library builtin value

     auth
          The authentication method to use, possible values depend on the LDAP library XEmacs was compiled with, they may include simple, krbv41 and krbv42.

     binddn
          The distinguished name of the user to bind as.  This may look like cÿ, o¬me, cnÿnny Bugs, see RFC 1779 for details.

     passwd
          The password to use for authentication.

     deref
          The dereference policy is one of the symbols never, always, search or find and defines how aliases are dereferenced.

          never
               Aliases are never dereferenced

          always
               Aliases are always dereferenced

          search
               Aliases are dereferenced when searching

          find
               Aliases are dereferenced when locating the base object for the search

          The default is never.

     timelimit
          The timeout limit for the connection in seconds.

     sizelimit
          The maximum number of matches to return for searches performed on this connection.

 -- Function: ldap-close ldap
     Close the connection represented by LDAP

Searching on a LDAP Server (Low-level)
......................................

ldap-search-internal is the low-level primitive to perform a search on a LDAP server.  It works directly on an open LDAP connection thus requiring a preliminary call to ldap-open.  Multiple searches can be made on the same connection, then the session must be closed with ldap-close.

 -- Function: ldap-search-internal ldap filter base scope attrs attrsonly
     Perform a search on an open connection LDAP created with ldap-open. FILTER is a filter string for the search see Syntax of Search Filters BASE is the distinguished name at which to start the search. SCOPE is one of the symbols base, onelevel or subtree indicating the scope of the search limited to a base object, to a single level or to the whole subtree.  The default is subtree. attrs is a list of strings indicating which attributes to retrieve for each matching entry. If nil all available attributes are returned. If attrsonly is non-nil then only the attributes are retrieved, not their associated values The function returns a list of matching entries.  Each entry being itself an alist of attribute/values.

Syntax of Search Filters
========================

LDAP search functions use RFC1558 syntax to describe the search filter. In that syntax simple filters have the form:

     (<attr> <filtertype> <value>)

<attr> is an attribute name such as cn for Common Name, o for Organization, etc...

<value> is the corresponding value.  This is generally an exact string but may also contain * characters as wildcards

filtertype is one = ~=, <=, >= which respectively describe equality, approximate equality, inferiority and superiority.

Thus (cn=John Smith) matches all records having a canonical name equal to John Smith.

A special case is the presence filter (<attr>=* which matches records containing a particular attribute.  For instance (mail=*) matches all records containing a mail attribute.

Simple filters can be connected together with the logical operators &, | and ! which stand for the usual and, or and not operators.

(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John))) matches records of class Person containing a mail attribute and corresponding to people whose last name is Smith or whose first name is John.