60. 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.

60.1 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.2 (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 auto-detects 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.

60.2 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.

The low-level API should be used directly for very specific purposes (such as multiple operations on a connection) only. The higher-level functions provide a more convenient way to access LDAP directories hiding the subtleties of handling the connection, translating arguments and ensuring compliance with LDAP internationalization rules and formats (currently partly implemented only).

60.2.1 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=ACME, c=US" 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 `cn=Babs Jensen,o=ACME,c=US', 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 `o=ACME, c=US', 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.

Variable: ldap-verbose

If non-nil, LDAP operations will echo progress messages. Defaults to nil.

60.2.2 The High-Level LDAP API

The following functions provide the most convenient interface to perform LDAP operations. All of them open a connection to a host, perform an operation (add/search/modify/delete) on one or several entries and cleanly close the connection thus insulating the user from all the details of the low-level interface such as LDAP Lisp objects see section 60.2.3 The Low-Level LDAP API.

Note that ldap-search which used to be the name of the high-level search function in XEmacs 21.1 is now obsolete. For consistency in the naming as well as backward compatibility, that function now acts as a wrapper that calls either ldap-search-basic (low-level search function) or ldap-search-entries (high-level search function) according to the actual parameters. A direct call to one of these two functions is preferred since it is faster and unambiguous.

Command: ldap-search-entries filter &optional host attributes attrsonly withdn

Perform an LDAP search. filter is the search filter see section 60.3 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. If withdn is non-nil each entry in the result will be prepended with its distinguished name DN. Additional search parameters can be specified through ldap-host-parameters-alist. The function returns a list of matching entries. Each entry is itself an alist of attribute/value pairs optionally preceded by the DN of the entry according to the value of withdn.

Function: ldap-add-entries entries &optional host binddn passwd

Add entries to an LDAP directory. entries is a list of entry specifications of the form (DN (ATTR . VALUE) (ATTR . VALUE) ...) where dn the distinguished name of an entry to add, the following are cons cells containing attribute/value string pairs. host is the LDAP host, defaulting to ldap-default-host. binddn is the DN to bind as to the server. passwd is the corresponding password.

Function: ldap-modify-entries entry-mods &optional host binddn passwd

Modify entries of an LDAP directory. entry_mods is a list of entry modifications of the form (DN MOD-SPEC1 MOD-SPEC2 ...) where dn is the distinguished name of the entry to modify, the following are modification specifications. A modification specification is itself a list of the form (MOD-OP ATTR VALUE1 VALUE2 ...) mod-op and attr are mandatory, values are optional depending on mod-op. mod-op is the type of modification, one of the symbols add, delete or replace. attr is the LDAP attribute type to modify. host is the LDAP host, defaulting to ldap-default-host. binddn is the DN to bind as to the server. passwd is the corresponding password.

Function: ldap-delete-entries dn &optional host binddn passwd

Delete an entry from an LDAP directory. dn is the distinguished name of an entry to delete or a list of those. host is the LDAP host, defaulting to ldap-default-host. binddn is the DN to bind as to the server. passwd is the corresponding password.

60.2.3 The Low-Level LDAP API

The low-level API should be used directly for very specific purposes (such as multiple operations on a connection) only. The higher-level functions provide a more convenient way to access LDAP directories hiding the subtleties of handling the connection, translating arguments and ensuring compliance with LDAP internationalization rules and formats (currently partly implemented only). See see section 60.2.2 The High-Level LDAP API

Note that the former functions ldap-*-internal functions have been renamed in XEmacs 21.2

60.2.3.1 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.

60.2.3.2 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=com, o=Acme, cn=Babs Jensen', 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.

60.2.3.3 Low-level Operations on a LDAP Server

ldap-search-basic 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-basic ldap filter &optional base scope attrs attrsonly withdn verbose

Perform a search on an open connection ldap created with ldap-open. filter is a filter string for the search see section 60.3 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. If withdn is non-nil then each entry in the result is prepended with its distinguished name DN. If verbose is non-nil then progress messages are echoed The function returns a list of matching entries. Each entry is itself an alist of attribute/value pairs optionally preceded by the DN of the entry according to the value of withdn.

Function: ldap-add ldap dn entry

Add entry to a LDAP directory which a connection ldap has been opened to with ldap-open. dn is the distinguished name of the entry to add. entry is an entry specification, i.e., a list of cons cells containing attribute/value string pairs.

Function: ldap-modify ldap dn mods

Modify an entry in an LDAP directory. ldap is an LDAP connection object created with ldap-open. dn is the distinguished name of the entry to modify. mods is a list of modifications to apply. A modification is a list of the form (MOD-OP ATTR VALUE1 VALUE2 ...) mod-op and attr are mandatory, values are optional depending on mod-op. mod-op is the type of modification, one of the symbols add, delete or replace. attr is the LDAP attribute type to modify.

Function: ldap-delete ldap dn

Delete an entry to an LDAP directory. ldap is an LDAP connection object created with ldap-open. dn is the distinguished name of the entry to delete.

60.2.4 LDAP Internationalization

The XEmacs LDAP API provides basic internationalization features based on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 Attribute Syntax Definitions"). Unfortunately since there is currently no free LDAP v3 server software, this part has not received much testing and should be considered experimental. The framework is in place though.

Function: ldap-decode-attribute attr

Decode the attribute/value pair attr according to LDAP rules. The attribute name is looked up in ldap-attribute-syntaxes-alist and the corresponding decoder is then retrieved from ldap-attribute-syntax-decoders' and applied on the value(s).

60.2.4.1 LDAP Internationalization Variables

Variable: ldap-ignore-attribute-codings

If non-nil, no encoding/decoding will be performed LDAP attribute values

Variable: ldap-coding-system

Coding system of LDAP string values. LDAP v3 specifies the coding system of strings to be UTF-8. You need an XEmacs with Mule support for this.

Variable: ldap-default-attribute-decoder

Decoder function to use for attributes whose syntax is unknown. Such a function receives an encoded attribute value as a string and should return the decoded value as a string.

Variable: ldap-attribute-syntax-encoders

A vector of functions used to encode LDAP attribute values. The sequence of functions corresponds to the sequence of LDAP attribute syntax object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. As of this writing, only a few encoder functions are available.

Variable: ldap-attribute-syntax-decoders

A vector of functions used to decode LDAP attribute values. The sequence of functions corresponds to the sequence of LDAP attribute syntax object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. As of this writing, only a few decoder functions are available.

Variable: ldap-attribute-syntaxes-alist

A map of LDAP attribute names to their type object id minor number. This table is built from RFC2252 Section 5 and RFC2256 Section 5.

60.2.4.2 Encoder/Decoder Functions

Function: ldap-encode-boolean bool

A function that encodes an elisp boolean bool into a LDAP boolean string representation.

Function: ldap-decode-boolean str

A function that decodes a LDAP boolean string representation str into an elisp boolean.

Function: ldap-decode-string str

Decode a string str according to ldap-coding-system.

Function: ldap-encode-string str

Encode a string str according to ldap-coding-system.

Function: ldap-decode-address str

Decode an address str according to ldap-coding-system and replacing $ signs with newlines as specified by LDAP encoding rules for addresses.

Function: ldap-encode-address str

Encode an address str according to ldap-coding-system and replacing newlines with $ signs as specified by LDAP encoding rules for addresses.

60.3 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.