ldap(n)                           LDAP client                          ldap(n)



______________________________________________________________________________

NAME
       ldap - LDAP client

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

_________________________________________________________________

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

              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?
              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 lists with the format:



                  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.

              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 Tcllib SF Trackers
       [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
       directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc
       4511, x.500

CATEGORY
       Networking

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




ldap                                 1.6.9                             ldap(n)
