Provided by: tcllib_1.14-dfsg-1_all bug

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

              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>