ldap(3tcl)
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::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.
TLS SECURITY CONSIDERATIONS
This package uses the TLS package to handle the security for https urls
and other socket 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
[http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-
exploiting-ssl-30.html] 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.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
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 Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.
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>
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
