ldap - LDAP client

package require Tcl 8.2 package require ldap ?1.2? ::ldap::connect host ?port? ::ldap::secure_connect host ?port? ::ldap::disconnect handle ::ldap::bind handle ?name? ?password? ::ldap::unbind handle ::ldap::search handle baseObject filterString attributes ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd? ::ldap::add handle dn attrValueTuples ::ldap::delete handle dn ::ldap::modifyDN handle dn newrdn ?deleteOld?

The ldap package provides a simple Tcl-only client library for the LDAPv3 protocol as specified in RFC 2251 (http://www.rfc-editor.org/rfc/rfc2251.txt). It works by opening the standard (or secure) LDAP socket on the server, and then providing a Tcl API to access the LDAP protocol commands. All server errors are returned as Tcl errors (thrown) which must be caught with the Tcl catch command.

::ldap::connect host ?port?

Opens a LDAPv3 connection to the specified host, at the given port, and returns a token for the connection. This token is the handle argument for all other commands. If no port is specified it will default to 389. The command blocks until the connection has been established, or establishment definitely failed.

::ldap::secure_connect host ?port?

Like ::ldap::connect, except that the created connection is secured by SSL. The port defaults to 636. This command depends on the availability of the package TLS, which is a SSL binding for Tcl. If TLS is not available, then this command will fail. The command blocks until the connection has been established, or establishment definitely failed.

::ldap::disconnect handle

Closes the ldap connection refered to by the token handle. Returns the empty string as its result.

::ldap::bind handle ?name? ?password?

This command authenticates the ldap connection refered to by the token in handle, with a user name and associated password. It blocks until a response from the ldap server arrives. Its result is the empty string. Both name and passwd default to the empty string if they are not specified.

::ldap::unbind handle

This command asks the ldap server to release the last bind done for the connection refered to by the token in handle.

::ldap::search handle baseObject filterString attributes

This command performs a LDAP search below the baseObject tree using a complex LDAP search expression filterString and returns the specified attributes of all matching objects (DNs). If the list of attributes was empty all attributes are returned. The command blocks until it has received all results. An example of a search expression is

    set filterString "|(cn=Linus*)(sn=Torvalds*)"

The return value of the command is a list of nested dictionaries. The first level keys are object identifiers (DNs), second levels keys are attribute names. In other words, it is in the form

    {dn1 {attr1 val1 attr2 val2 ...}} {dn2 {a1 v1 ...}} ...

::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?

This command modifies the object dn on the ldap server we are connected to via handle. It replaces attributes with new values, deletes attributes, and adds new attributes with new values. All arguments are dictionaries mapping attribute names to values. The optional arguments default to the empty dictionary, which means that no attributes will be deleted nor added.

attrValToReplace dictionary (in)

No attributes will be changed if this argument is empty. The dictionary contains the new attributes and their values. They replace all attributes known to the object.

attrToDelete dictionary (in)

No attributes will be deleted if this argument is empty. The dictionary values are restrictions on the deletion. An attribute listed here will be deleted if and only if its current value at the server matches the value specified in the dictionary, or if the value in the dictionary is the empty string.

attrValToAdd dictionary (in)

No attributes will be added if this argument is empty. The dictionary values are the values for the new attributes. The command blocks until all modifications have completed. Its result is the empty string.

::ldap::add handle dn attrValueTuples

This command creates a new object using the specified dn. The attributes of the new object are set to the values in the dictionary attrValueTuples (which is keyed by the attribute names). The command blocks until the operation has completed. Its result is the empty string.

::ldap::delete handle dn

This command removes the object specified by dn, and all its attributes from the server. The command blocks until the operation has completed. Its result is the empty string.

::ldap::modifyDN handle dn newrdn ?deleteOld?

This command moves or copies the object specified by dn to a new location in the tree of object. This location is specified by newrdn, a relative designation. The optional argument deleteOld default to to true, i.e. a move operation. If deleteOld is not set, then the operation will create a copy of dn in the new location. The command blocks until the operation has completed. Its result is the empty string.

A small example, extracted from the test application coming with this code.

    package require ldap

# Connect, bind, add a new object, modify it in various ways

set handle [ldap::connect localhost 9009]

set dn "cn=Manager, o=University of Michigan, c=US" set pw secret

ldap::bind $handle $dn $pw

set dn "cn=Test User,ou=People,o=University of Michigan,c=US"

ldap::add $handle $dn { objectClass OpenLDAPperson cn "Test User" mail "test.user@google.com" uid "testuid" sn User }

# Replace all attributes ldap::modify $handle $dn [list drink icetea uid JOLO]

# Add some more ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]

# Delete ldap::modify $handle $dn {} [list drink water pager ""]

# Move ldap::modifyDN $handle $dn "cn=Tester"

# Kill the test object, and shut the connection down. set dn "cn=Tester,ou=People,o=University of Michigan,c=US" ldap::delete $handle $dn

ldap::unbind $handle ldap::disconnect $handle

And a another example, a simple query, and processing the results.

    package require ldap
    set handle [ldap::connect ldap.acme.com 389]
    ldap::bind $handle
    set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
    foreach result $results {
	foreach {object attributes} $result break

# The processing here is similar to what 'parray' does. # I.e. finding the longest attribute name and then # generating properly aligned output listing all attributes # and their values.

set width 0 set sortedAttribs {} foreach {type values} $attributes { if {[string length $type] > $width} { set width [string length $type] } lappend sortedAttribs [list $type $values] }

puts "object='$object'"

foreach sortedAttrib $sortedAttribs { foreach {type values} $sortedAttrib break foreach value $values { regsub -all "\[\x01-\x1f\]" $value ? value puts [format " %-${width}s %s" $type $value] } } puts "" } ldap::unbind $handle ldap::disconnect $handle

asn, ber, directory access, internet, ldap, ldap client, protocol, rfc 2251, x.680, x.690

Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright (c) 2004 Jochen Loewer <loewerj@web.de>