TCLLIB - Tcl Standard Library: ldap

SYNOPSIS

package require Tcl 8.4
package require ldap  ? 1.8 ? 
::ldap::connect host  ? port ? 
::ldap::secure_connect host  ? port ? 
::ldap::disconnect handle
::ldap::starttls handle  ? cafile ?   ? certfile ?   ? keyfile ? 
::ldap::bind handle  ? name ?   ? password ? 
::ldap::bindSASL handle  ? name ?   ? password ? 
::ldap::unbind handle
::ldap::search handle baseObject filterString attributes options
::ldap::searchInit handle baseObject filterString attributes options
::ldap::searchNext handle
::ldap::searchEnd handle
::ldap::searchInit 
::ldap::modify handle dn attrValToReplace  ? attrToDelete ?   ? attrValToAdd ? 
::ldap::modifyMulti handle dn attrValToReplace  ? attrValToDelete ?   ? attrValToAdd ? 
::ldap::add handle dn attrValueTuples
::ldap::addMulti handle dn attrValueTuples
::ldap::delete handle dn
::ldap::modifyDN handle dn newrdn  ? deleteOld ?   ? newSuperior ? 
::ldap::info ip handle
::ldap::info bound handle
::ldap::info bounduser handle
::ldap::info connections
::ldap::info tls handle
::ldap::info saslmechanisms handle
::ldap::info control handle
::ldap::info extensions extensions
::ldap::info whoami handle

The ldap package provides a Tcl-only client library for the LDAPv3 protocol as specified in RFC 4511 (http://www.rfc-editor.org/rfc/rfc4511.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.

COMMANDS

::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::starttls handle ? cafile ? ? certfile ? ? keyfile ?

Start TLS negotiation on the connection denoted by handle. This is currently experimental and subject to change, more control over the TLS details will probably be exposed later, to allow users to fine tune the negotiation according to their security needs.

::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. By leaving out name and passwd you can make an anonymous bind to the ldap server. You can issue ::ldap::bind again to bind with different credentials.

::ldap::bindSASL handle ? name ? ? password ?

This command uses SASL authentication mechanisms to do a multistage bind. Its otherwise identical to the standard ::ldap::bind. This feature is currently experimental and subject to change. See the documentation for the SASL and the SASL.txt in the tcllib CVS repository for details how to setup and use SASL with openldap.

::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. The handle is invalid after the unbind, as the server closes the connection. So this is effectivly just a more polite disconnect operation.

::ldap::search handle baseObject filterString attributes options

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. The valid options are identical to the options listed for ::ldap::searchInit.
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 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...

::ldap::searchInit handle baseObject filterString attributes options

This command initiates a LDAP search below the baseObject tree using a complex LDAP search expression filterString. The search gets the specified attributes of all matching objects (DNs). The command itself just starts the search, to retrieve the actual results, use ::ldap::searchNext. A search can be terminated at any time by ::ldap::searchEnd. This informs the server that no further results should be sent by sending and ABANDON message and cleans up the internal state of the search. Only one ::ldap::search can be active at a given time, this includes the introspection commands ::ldap::info saslmechanisms, ldap::info control and ldap::info extensions, which invoke a search internally. Error responses from the server due to wrong arguments or similar things are returned with the first ::ldap::searchNext call and should be checked and dealed with there. If the list of requested attributes is empty all attributes will be returned. The parameter options specifies the options to be used in the search, and has the following format:

    {-option1 value1 -option2 value2 ... }

Following options are available:

-scope base one sub: Control the scope of the search to be one of base, one, or sub, to specify a base object, one-level or subtree search. The default is sub.
-derefaliases never search find always: Control how aliases dereferencing is done. Should be one of never, always, search, or find to specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or dereferenced only when locating the base object for the search. The default is to never dereference aliases.
-sizelimit num: Determines the maximum number of entries to return in a search. If specified as 0 no limit is enforced. The server may enforce a configuration dependent sizelimit, which may be lower than the one given by this option. The default is 0, no limit.
-timelimit seconds: Asks the server to use a timelimit of seconds for the search. Zero means no limit. The default is 0, no limit.
-attrsonly boolean: If set to 1 only the attribute names but not the values will be present in the search result. The default is to retrieve attribute names and values.
-referencevar varname: If set the search result reference LDAPURIs, if any, are returned in the given variable. The caller can than decide to follow those references and query other LDAP servers for further results.

::ldap::searchNext handle

This command returns the next entry from a LDAP search initiated by ::ldap::searchInit. It returns only after a new result is received or when no further results are available, but takes care to keep the event loop alive. The returned entry is a list with two elements: the first is the DN of the entry, the second is the list of attributes and values, under the format:

    dn {attr1 {val11 val12 ...} attr2 {val21...} ...}

The ::ldap::searchNext command returns an empty list at the end of the search.

::ldap::searchEnd handle

This command terminates a LDAP search initiated by

::ldap::searchInit

. It also cleans up the internal state so a new search can be initiated. If the client has not yet received all results, the client sends an ABANDON message to inform the server that no further results for the previous search should to be sent.

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

Type	Name	Mode
dictionary	attrValToReplace	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.
dictionary	attrToDelete	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.
dictionary	attrValToAdd	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::modifyMulti handle dn attrValToReplace ? attrValToDelete ? ? attrValToAdd ?

    attr1 {val11 val12 ...} attr2 {val21...} ...

where each value list may be empty for deleting all attributes. The optional arguments default to empty lists of attributes to delete and to add.

Type	Name	Mode
list	attrValToReplace	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.
list	attrValToDelete	in
	No attributes will be deleted if this argument is empty. If no value is specified, the whole set of values for an attribute will be deleted.
list	attrValToAdd	in
	No attributes will be added if this argument is empty.

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 list attrValueTuples. Multiple valuated attributes may be specified using multiple tuples. The command blocks until the operation has completed. Its result is the empty string.

::ldap::addMulti handle dn attrValueTuples

This command is the preferred one to create 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). Each tuple is a list containing multiple values. 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 ? ? newSuperior ?

] 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, or by newrdn and newSuperior, a absolute designation. The optional argument deleteOld defaults 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 optional argument newSuperior defaults an empty string, meaning that the object must not be relocated in another branch of the tree. If this argument is given, the argument deleteOld must be specified also. The command blocks until the operation has completed. Its result is the empty string.

::ldap::info ip handle

This command returns the IP address of the remote LDAP server the handle is connected to.

::ldap::info bound handle

This command returns 1 if a handle has successfully completed a ::ldap::bind. If no bind was done or it failed, a 0 is returned.

::ldap::info bounduser handle

This command returns the username used in the bind operation if a handle has successfully completed a ::ldap::bind. If no bound was done or it failed, an empty string is returned.

::ldap::info connections

This command returns all currently existing ldap connection handles.

::ldap::info tls handle

This command returns 1 if the ldap connection handle used TLS/SSL for connection via ldap::secure_connect or completed ldap::starttls, 0 otherwise.

::ldap::info saslmechanisms handle

Return the supported SASL mechanisms advertised by the server. Only valid in a bound state (anonymous or other).

::ldap::info control handle

Return the supported controls advertised by the server as a list of OIDs. Only valid in a bound state. This is currently experimental and subject to change.

::ldap::info extensions extensions

Returns the supported LDAP extensions as list of OIDs. Only valid in a bound state. This is currently experimental and subject to change.

::ldap::info whoami handle

Returns authzId for the current connection. This implements the RFC 4532 protocol extension.

EXAMPLES

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
	telephoneNumber +31415926535
	telephoneNumber +27182818285
    }

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

    ldap::addMulti $handle $dn {
	objectClass     {OpenLDAPperson}
	cn              {{Anotther User}}
	mail            {test.user@google.com}
	uid             {testuid}
	sn              {User}
	telephoneNumber {+31415926535 +27182818285}
    }

    # 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

BUGS, IDEAS, FEEDBACK

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category ldap of the http://sourceforge.net/tracker/?group_id=12883. Please also report any ideas for enhancements you may have for either package and/or documentation. One know bug is the usage of vwait inside the dispatch mechanism, which makes it currently unsafe to use this code in code that also enters the event loop.

KEYWORDS

ldap, rfc 2251, rfc 4511, x.500, ldap client, directory access, internet, protocol

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

EXAMPLES

BUGS, IDEAS, FEEDBACK

KEYWORDS