1ldap(n) LDAP client ldap(n)
2______________________________________________________________________________
6
8 ldap - LDAP client
9
11 package require Tcl 8.4
12 package require ldap ?1.8?
14 ::ldap::connect host ?port?
16 ::ldap::secure_connect host ?port?
18 ::ldap::disconnect handle
20 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile?
22 ::ldap::bind handle ?name? ?password?
24 ::ldap::bindSASL handle ?name? ?password?
26 ::ldap::unbind handle
28 ::ldap::search handle baseObject filterString attributes options
30 ::ldap::searchInit handle baseObject filterString attributes options
32 ::ldap::searchNext handle
34 ::ldap::searchEnd handle
36 ::ldap::searchInit
38 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
40 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
42 ValToAdd?
43 ::ldap::add handle dn attrValueTuples
45 ::ldap::addMulti handle dn attrValueTuples
47 ::ldap::delete handle dn
49 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
51 ::ldap::info ip handle
53 ::ldap::info bound handle
55 ::ldap::info bounduser handle
57 ::ldap::info connections
59 ::ldap::info tls handle
61 ::ldap::info saslmechanisms handle
63 ::ldap::info control handle
65 ::ldap::info extensions extensions
67 ::ldap::info whoami handle
69_________________________________________________________________
71
73 The ldap package provides a Tcl-only client library for the LDAPv3 pro‐
74 tocol as specified in RFC 4511 (http://www.rfc-edi‐
75 tor.org/rfc/rfc4511.txt). It works by opening the standard (or secure)
76 LDAP socket on the server, and then providing a Tcl API to access the
77 LDAP protocol commands. All server errors are returned as Tcl errors
78 (thrown) which must be caught with the Tcl catch command.
79
81 ::ldap::connect host ?port?
82 Opens a LDAPv3 connection to the specified host, at the given
83 port, and returns a token for the connection. This token is the
84 handle argument for all other commands. If no port is specified
85 it will default to 389.
86 The command blocks until the connection has been established, or
88 establishment definitely failed.
89 ::ldap::secure_connect host ?port?
91 Like ::ldap::connect, except that the created connection is
92 secured by SSL. The port defaults to 636. This command depends
93 on the availability of the package TLS, which is a SSL binding
94 for Tcl. If TLS is not available, then this command will fail.
95 The command blocks until the connection has been established, or
97 establishment definitely failed.
98 ::ldap::disconnect handle
100 Closes the ldap connection refered to by the token handle.
101 Returns the empty string as its result.
102 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile?
104 Start TLS negotiation on the connection denoted by handle. This
105 is currently experimental and subject to change, more control
106 over the TLS details will probably be exposed later, to allow
107 users to fine tune the negotiation according to their security
108 needs.
109 ::ldap::bind handle ?name? ?password?
111 This command authenticates the ldap connection refered to by the
112 token in handle, with a user name and associated password. It
113 blocks until a response from the ldap server arrives. Its result
114 is the empty string. Both name and passwd default to the empty
115 string if they are not specified. By leaving out name and
116 passwd you can make an anonymous bind to the ldap server. You
117 can issue ::ldap::bind again to bind with different credentials.
118 ::ldap::bindSASL handle ?name? ?password?
120 This command uses SASL authentication mechanisms to do a multi‐
121 stage bind. Its otherwise identical to the standard
122 ::ldap::bind. This feature is currently experimental and sub‐
123 ject to change. See the documentation for the SASL and the
124 "SASL.txt" in the tcllib CVS repository for details how to setup
125 and use SASL with openldap.
126 ::ldap::unbind handle
128 This command asks the ldap server to release the last bind done
129 for the connection refered to by the token in handle. The han‐
130 dle is invalid after the unbind, as the server closes the con‐
131 nection. So this is effectivly just a more polite disconnect
132 operation.
133 ::ldap::search handle baseObject filterString attributes options
135 This command performs a LDAP search below the baseObject tree
136 using a complex LDAP search expression filterString and returns
137 the specified attributes of all matching objects (DNs). If the
138 list of attributes was empty all attributes are returned. The
139 command blocks until it has received all results. The valid
140 options are identical to the options listed for ::ldap::sear‐
141 chInit.
142 An example of a search expression is
144 set filterString "|(cn=Linus*)(sn=Torvalds*)"
147 The return value of the command is a list of nested dictionar‐
150 ies. The first level keys are object identifiers (DNs), second
151 levels keys are attribute names. In other words, it is in the
152 form
153 {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
156 ::ldap::searchInit handle baseObject filterString attributes options
160 This command initiates a LDAP search below the baseObject tree
161 using a complex LDAP search expression filterString. The search
162 gets the specified attributes of all matching objects (DNs).
163 The command itself just starts the search, to retrieve the
164 actual results, use ::ldap::searchNext. A search can be termi‐
165 nated at any time by ::ldap::searchEnd. This informs the server
166 that no further results should be sent by sending and ABANDON
167 message and cleans up the internal state of the search. Only
168 one ::ldap::search can be active at a given time, this includes
169 the introspection commands ::ldap::info saslmechanisms,
170 ldap::info control and ldap::info extensions, which invoke a
171 search internally. Error responses from the server due to wrong
172 arguments or similar things are returned with the first
173 ::ldap::searchNext call and should be checked and dealed with
174 there. If the list of requested attributes is empty all
175 attributes will be returned. The parameter options specifies
176 the options to be used in the search, and has the following for‐
177 mat:
178 {-option1 value1 -option2 value2 ... }
181 Following options are available:
184 -scope base one sub
186 Control the scope of the search to be one of base, one,
187 or sub, to specify a base object, one-level or sub‐
188 tree search. The default is sub.
189 -derefaliases never search find always
191 Control how aliases dereferencing is done. Should be one
192 of never, always, search, or find to specify that
193 aliases are never dereferenced, always dereferenced,
194 dereferenced when searching, or dereferenced only when
195 locating the base object for the search. The default is
196 to never dereference aliases.
197 -sizelimit num
199 Determines the maximum number of entries to return in a
200 search. If specified as 0 no limit is enforced. The
201 server may enforce a configuration dependent sizelimit,
202 which may be lower than the one given by this option. The
203 default is 0, no limit.
204 -timelimit seconds
206 Asks the server to use a timelimit of seconds for the
207 search. Zero means no limit. The default is 0, no limit.
208 -attrsonly boolean
210 If set to 1 only the attribute names but not the values
211 will be present in the search result. The default is to
212 retrieve attribute names and values.
213 -referencevar varname
215 If set the search result reference LDAPURIs, if any, are
216 returned in the given variable. The caller can than
217 decide to follow those references and query other LDAP
218 servers for further results.
219 ::ldap::searchNext handle
222 This command returns the next entry from a LDAP search initiated
223 by ::ldap::searchInit. It returns only after a new result is
224 received or when no further results are available, but takes
225 care to keep the event loop alive. The returned entry is a list
226 with two elements: the first is the DN of the entry, the second
227 is the list of attributes and values, under the format:
228 dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
231 The ::ldap::searchNext command returns an empty list at the end
234 of the search.
235 ::ldap::searchEnd handle
238 This command terminates a LDAP search initiated by
239 ::ldap::searchInit
241 the internal state so a new search can be initiated. If the
242 client has not yet received all results, the client sends an
243 ABANDON message to inform the server that no further results for
244 the previous search should to be sent.
245 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
248 This command modifies the object dn on the ldap server we are
249 connected to via handle. It replaces attributes with new values,
250 deletes attributes, and adds new attributes with new values.
251 All arguments are dictionaries mapping attribute names to val‐
252 ues. The optional arguments default to the empty dictionary,
253 which means that no attributes will be deleted nor added.
254 dictionary attrValToReplace (in)
256 No attributes will be changed if this argument is empty.
257 The dictionary contains the new attributes and their val‐
258 ues. They replace all attributes known to the object.
259 dictionary attrToDelete (in)
261 No attributes will be deleted if this argument is empty.
262 The dictionary values are restrictions on the deletion.
263 An attribute listed here will be deleted if and only if
264 its current value at the server matches the value speci‐
265 fied in the dictionary, or if the value in the dictionary
266 is the empty string.
267 dictionary attrValToAdd (in)
269 No attributes will be added if this argument is empty.
270 The dictionary values are the values for the new
271 attributes.
272 The command blocks until all modifications have completed. Its result
274 is the empty string.
275 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
277 ValToAdd?
278 This command modifies the object dn on the ldap server we are
279 connected to via handle. It replaces attributes with new values,
280 deletes attributes, and adds new attributes with new values.
281 All arguments are lists with the format:
282 attr1 {val11 val12 ...} attr2 {val21...} ...
285 where each value list may be empty for deleting all attributes.
288 The optional arguments default to empty lists of attributes to
289 delete and to add.
290 list attrValToReplace (in)
292 No attributes will be changed if this argument is empty.
293 The dictionary contains the new attributes and their val‐
294 ues. They replace all attributes known to the object.
295 list attrValToDelete (in)
297 No attributes will be deleted if this argument is empty.
298 If no value is specified, the whole set of values for an
299 attribute will be deleted.
300 list attrValToAdd (in)
302 No attributes will be added if this argument is empty.
303 The command blocks until all modifications have completed. Its result
305 is the empty string.
306 ::ldap::add handle dn attrValueTuples
308 This command creates a new object using the specified dn. The
309 attributes of the new object are set to the values in the list
310 attrValueTuples. Multiple valuated attributes may be specified
311 using multiple tuples. The command blocks until the operation
312 has completed. Its result is the empty string.
313 ::ldap::addMulti handle dn attrValueTuples
315 This command is the preferred one to create a new object using
316 the specified dn. The attributes of the new object are set to
317 the values in the dictionary attrValueTuples (which is keyed by
318 the attribute names). Each tuple is a list containing multiple
319 values. The command blocks until the operation has completed.
320 Its result is the empty string.
321 ::ldap::delete handle dn
323 This command removes the object specified by dn, and all its
324 attributes from the server. The command blocks until the opera‐
325 tion has completed. Its result is the empty string.
326 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
328 ] This command moves or copies the object specified by dn to a
329 new location in the tree of object. This location is specified
330 by newrdn, a relative designation, or by newrdn and newSuperior,
331 a absolute designation. The optional argument deleteOld
332 defaults to true, i.e. a move operation. If deleteOld is not
333 set, then the operation will create a copy of dn in the new
334 location. The optional argument newSuperior defaults an empty
335 string, meaning that the object must not be relocated in another
336 branch of the tree. If this argument is given, the argument
337 deleteOld must be specified also. The command blocks until the
338 operation has completed. Its result is the empty string.
339 ::ldap::info ip handle
341 This command returns the IP address of the remote LDAP server
342 the handle is connected to.
343 ::ldap::info bound handle
345 This command returns 1 if a handle has successfully completed a
346 ::ldap::bind. If no bind was done or it failed, a 0 is
347 returned.
348 ::ldap::info bounduser handle
350 This command returns the username used in the bind operation if
351 a handle has successfully completed a ::ldap::bind. If no bound
352 was done or it failed, an empty string is returned.
353 ::ldap::info connections
355 This command returns all currently existing ldap connection han‐
356 dles.
357 ::ldap::info tls handle
359 This command returns 1 if the ldap connection handle used
360 TLS/SSL for connection via ldap::secure_connect or completed
361 ldap::starttls, 0 otherwise.
362 ::ldap::info saslmechanisms handle
364 Return the supported SASL mechanisms advertised by the server.
365 Only valid in a bound state (anonymous or other).
366 ::ldap::info control handle
368 Return the supported controls advertised by the server as a list
369 of OIDs. Only valid in a bound state. This is currently experi‐
370 mental and subject to change.
371 ::ldap::info extensions extensions
373 Returns the supported LDAP extensions as list of OIDs. Only
374 valid in a bound state. This is currently experimental and sub‐
375 ject to change.
376 ::ldap::info whoami handle
378 Returns authzId for the current connection. This implements the
379 RFC 4532 protocol extension.
380
382 A small example, extracted from the test application coming with this
383 code.
384 package require ldap
386 # Connect, bind, add a new object, modify it in various ways
388 set handle [ldap::connect localhost 9009]
390 set dn "cn=Manager, o=University of Michigan, c=US"
392 set pw secret
393 ldap::bind $handle $dn $pw
395 set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
397 ldap::add $handle $dn {
399 objectClass OpenLDAPperson
400 cn {Test User}
401 mail test.user@google.com
402 uid testuid
403 sn User
404 telephoneNumber +31415926535
405 telephoneNumber +27182818285
406 }
407 set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
409 ldap::addMulti $handle $dn {
411 objectClass {OpenLDAPperson}
412 cn {{Anotther User}}
413 mail {test.user@google.com}
414 uid {testuid}
415 sn {User}
416 telephoneNumber {+31415926535 +27182818285}
417 }
418 # Replace all attributes
420 ldap::modify $handle $dn [list drink icetea uid JOLO]
421 # Add some more
423 ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]
424 # Delete
426 ldap::modify $handle $dn {} [list drink water pager ""]
427 # Move
429 ldap::modifyDN $handle $dn "cn=Tester"
430 # Kill the test object, and shut the connection down.
432 set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
433 ldap::delete $handle $dn
434 ldap::unbind $handle
436 ldap::disconnect $handle
437 And a another example, a simple query, and processing the results.
440 package require ldap
442 set handle [ldap::connect ldap.acme.com 389]
443 ldap::bind $handle
444 set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
445 foreach result $results {
446 foreach {object attributes} $result break
447 # The processing here is similar to what 'parray' does.
449 # I.e. finding the longest attribute name and then
450 # generating properly aligned output listing all attributes
451 # and their values.
452 set width 0
454 set sortedAttribs {}
455 foreach {type values} $attributes {
456 if {[string length $type] > $width} {
457 set width [string length $type]
458 }
459 lappend sortedAttribs [list $type $values]
460 }
461 puts "object='$object'"
463 foreach sortedAttrib $sortedAttribs {
465 foreach {type values} $sortedAttrib break
466 foreach value $values {
467 regsub -all "\[\x01-\x1f\]" $value ? value
468 puts [format " %-${width}s %s" $type $value]
469 }
470 }
471 puts ""
472 }
473 ldap::unbind $handle
474 ldap::disconnect $handle
475
478 This document, and the package it describes, will undoubtedly contain
479 bugs and other problems. Please report such in the category ldap of
480 the Tcllib SF Trackers [http://source‐
481 forge.net/tracker/?group_id=12883]. Please also report any ideas for
482 enhancements you may have for either package and/or documentation. One
483 know bug is the usage of vwait inside the dispatch mechanism, which
484 makes it currently unsafe to use this code in code that also enters the
485 event loop.
486
488 directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc
489 4511, x.500
490
492 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
493 Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
494 Copyright (c) 2006 Michael Schlenker <mic42@users.sourceforge.net>
495ldap 1.6.9 ldap(n)