The ldap Module

Various operations on LDAP directories are supported after loading the external


Ldap

Tcl module. Only after loading the module, the


ldap

extension command is accessible.

The next step is usually the establishment of a connection ( bind ) to a known LDAP server. In many cases credentials are required for a successful bind with a DN containing a user name. After a completed bind , a handle is returned. This handle can be used for further operations, such as information retrieval, until the connection is closed by an unbind command.

The general syntax of the


ldap

command follows the usual command/subcommand/handle/ parameter s syntax.

ldap bind

ldap bind host ?port? ?bindDN? ?password?

ldap open host ?port? ?bindDN? ?password?

Open a connection to an LDAP server and return the connection handle. Only the host parameter is required. If no port is specified, or an empty string, the default LDAP port (389) is used. If no distinguished name for binding is supplied, or an empty string, an anonymous bind is attempted. If an access control password is required, it may be supplied as last parameter.

The open command alternative is simply an alias intended to provide the standard command nomenclature for opening connections or files.

Example:

set lh [ldap bind $host 389 “cn=mr_x,cn=users,dc=chemcodes,dc=com” $themagicword]

ldap replace

ldap replace ldhandle dn attribute_list

This command can be used to add, replace or delete one or more attributes of a DN. The attribute list is a standard Tcl list, where each attribute is a list element. The list elements must be of the form attribute=value , or simply attribute for deletions. Optionally, they may be prefixed by one of the characters “+” (add attribute), “=” (replace attribute, or create new if not existing), and “-” (delete attribute). The implicit default is “=”. It is possible to add multiple instances of attributes, such as a set of e-mail addresses in the form

set alist [list “+mail=wdi@chemcodes.com” “+mail=wdi@xemistry.com”]

The ldap add command is a variant of this command - the only difference is that the default modification mode is LDAP_MOD_ADD instead of LDAP_MOD_REPLACE , corresponding to am implicit “+” prefix instead of “=”.

Example:

ldap replace $ldhandle “cn=wdi,cn=users,dc=chemcodes,dc=com” \ “mail=wdi@chemcodes.com”

ldap search

ldap search ldhandle baseDN ?scope? ?getdn? ?filter? ?attributelist?

Query an LDAP server for information. Besides an active LDAP connection, the minimal argument set is only the base DB, the root from where the query should start on the connected server.

The optional scope argument may be default or an empty string (the default setting), base (search only the base object), one or level (search one level of sub-objects), or subtree (can be shortened to sub , search all sub-objects of the base object).

The getdn parameter is a boolean flag. If it is set, the first element of each response sublist is the DN of the entry. By default, only the attribute data is returned.

The filter parameter is a standard LDAP filter, which can be used to select subsets of directory entries. An empty string in this position, or omitting the parameter, disables filtering.

Finally, the last parameter is the set of attributes which should be returned. If it is omitted, or an empty string, all attributes of each matched entry are returned. If a requested attribute is not present in a matching record, it is silently omitted from the result list.

If no errors occurred, the result is a triply nested list. The outermost list contains one element for each entry. If a maximum number of responses was set to a positive value ( sizelimit configuration parameter, see ldap set command), the maximum number of list elements is defined by this parameter. Each outer list element is itself a list. The middle lists contain one element for each returned attribute. Each of these is formatted as another sublist with attribute and value list elements. The attributes are returned in the order they were specified, provided that they are found in the returned set. If requested attributes are not present, they are silently omitted from the result list.

The command currently does support the retrieval of binary data.

Example:

ldap search $ldhandle “cn=users,dc=chemcodes,dc=com” one 0 {} [list mail phone]

returns a nested list of addresses, in the format

{{mail user1@addr1} {phone xxx-100}} {{mail user2@addr2} {phone xxx-105}}...

if both the mail and phone attributes are present.

The retrieval of the e-mail address of user wdi may be achieved either by using a filter, or a more specific DN:

ldap search $ldhandle “cn=users,dc=chemcodes,dc=com” one 0 cn=wdi “mail phone”

ldap search $ldhandle “cn=wdi,cn=users,dc=chemcodes,dc=com” one 0 {} “mail phone”

The filter argument1 is a string representation of the filter to apply in the search. Simple filters can be specified as attributetype=attributevalue. More complex filters are specified using a prefix notation according to the following BNF :

<filter> ::= '(' <filtercomp> ')' <filtercomp> ::= <and> | <or> | <not> | <simple><and> ::= '&' <filterlist><or> ::= '|' <filterlist><not> ::= '!' <filter><filterlist> ::= <filter> | <filter> <filterlist><simple> ::= <attributetype> <filtertype> <attributevalue><filtertype> ::= '=' | '~=' | '<=' | '>='

The '~=' construct is used to specify approximate matching. The representation for <attributetype> and<attributevalue> are as described in RFC 2254. In addition, <attributevalue> can be a single * to achieve an attribute existence test, or can contain text and *'s interspersed to achieve substring matching.

For example, the filter "mail=*" finds any entries that have a mail attribute. The filter "mail=*@terminator.rs.itd.umich.edu" will find any entries that have a mail attribute ending in the specified string. To put parentheses in a filter, escape them with a backslash '\' character. See RFC 2254 for a more complete description of allowable filters.

ldap unbind

ldap unbind ldhandle ?ldhandle?...

ldap close ldhandle ?ldhandle?...

ldap unbind all

ldap close all

The first variant unbinds or closes (these are equivalent commands) a specific set if LDAP connections. All resources associated with the connection are freed, and the handles invalidated. However, they may later be reassigned to new connections.

The second alternative closes all currently opened LDAP connections.

The command returns the number of closed connections.

Example:

ldap close all

ldap verify

ldap verify ldhandle bindDN password

ldap verify host port bindDN password

Perform a basic (LDAP_AUTH_SIMPLE ) user/access verification. The first variant uses an existing handle and attempts to re-bind it with a different distinguished bind name. The connection remains bound to the new address and DN.

The second variant temporarily creates a new LDAP connection and attempts to bind. The parameters have the same meaning as in the ldap bind command. The status is saved and then the connection is immediately closed. No persistent LDAP object is created.

This command returns 1 for a successful bind, and 0 for failure.

Example:

ldap verify $host ““ “dn=wdi,dn=users,dc=chemcodes,dc=com” $mypwd

1. Description of filters copied from the OpenLDAP man page for ldap_search(3)

The ldap Module

ldap add

ldap addrdn

ldap bind

ldap delete

ldap get

ldap list

ldap replace

ldap replacerdn

ldap search

ldap set

ldap unbind

ldap verify