Tcl Library Source Code

EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]


ldap - LDAP client

Table Of Contents


package require Tcl 8.5 9
package require ldap ?1.10.2?

::ldap::connect host ?port?
::ldap::tlsoptions reset
::ldap::tlsoptions ?opt1 val1? ?opt2 val2? ...
::ldap::secure_connect host ?port?
::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?
::ldap::disconnect handle
::ldap::starttls handle
::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert? ?sni_servername?
::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::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 tlsstatus 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 ( 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.

TLS Security Considerations

This package uses the TLS package to handle the security for LDAPS connections.

Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of TLS, nor of this package itself however. Such decisions are the responsibility of whichever application is using the package, and are likely influenced by the set of servers the application will talk to as well.

For example, in light of the recent POODLE attack discovered by Google many servers will disable support for the SSLv3 protocol. To handle this change the applications using TLS must be patched, and not this package, nor TLS itself. Such a patch may be as simple as generally activating tls1 support, as shown in the example below.

ldap::tlsoptions -tls1 1 -ssl2 0 -ssl3 0 ;# forcibly activate support for the TLS1 protocol

... your own application code ...



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            [email protected]
	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            {[email protected]}
	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 another example, a simple query, and processing the results.

    package require ldap
    set handle [ldap::connect 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 Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.


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




Copyright © 2004 Andreas Kupries
Copyright © 2004 Jochen Loewer
Copyright © 2006 Michael Schlenker