1ldap(n) LDAP client ldap(n)
2______________________________________________________________________________
6
8 ldap - LDAP client
9
11 package require Tcl 8.4
12 package require ldap ?1.9.2?
14 ::ldap::connect host ?port?
16 ::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?
18 ::ldap::disconnect handle
20 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert?
22 ?sni_servername?
23 ::ldap::bind handle ?name? ?password?
25 ::ldap::bindSASL handle ?name? ?password?
27 ::ldap::unbind handle
29 ::ldap::search handle baseObject filterString attributes options
31 ::ldap::searchInit handle baseObject filterString attributes options
33 ::ldap::searchNext handle
35 ::ldap::searchEnd handle
37 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
39 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
41 ValToAdd?
42 ::ldap::add handle dn attrValueTuples
44 ::ldap::addMulti handle dn attrValueTuples
46 ::ldap::delete handle dn
48 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
50 ::ldap::info ip handle
52 ::ldap::info bound handle
54 ::ldap::info bounduser handle
56 ::ldap::info connections
58 ::ldap::info tls handle
60 ::ldap::info saslmechanisms handle
62 ::ldap::info control handle
64 ::ldap::info extensions extensions
66 ::ldap::info whoami handle
68______________________________________________________________________________
70
72 The ldap package provides a Tcl-only client library for the LDAPv3 pro‐
73 tocol as specified in RFC 4511 (http://www.rfc-edi‐
74 tor.org/rfc/rfc4511.txt). It works by opening the standard (or secure)
75 LDAP socket on the server, and then providing a Tcl API to access the
76 LDAP protocol commands. All server errors are returned as Tcl errors
77 (thrown) which must be caught with the Tcl catch command.
78
80 This package uses the TLS package to handle the security for https urls
81 and other socket connections.
82 Policy decisions like the set of protocols to support and what ciphers
84 to use are not the responsibility of TLS, nor of this package itself
85 however. Such decisions are the responsibility of whichever applica‐
86 tion is using the package, and are likely influenced by the set of
87 servers the application will talk to as well.
88 For example, in light of the recent POODLE attack [http://googleonli‐
90 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
91 ssl-30.html] discovered by Google many servers will disable support for
92 the SSLv3 protocol. To handle this change the applications using TLS
93 must be patched, and not this package, nor TLS itself. Such a patch
94 may be as simple as generally activating tls1 support, as shown in the
95 example below.
96 package require tls
99 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
100 ... your own application code ...
102
105 ::ldap::connect host ?port?
106 Opens a LDAPv3 connection to the specified host, at the given
107 port, and returns a token for the connection. This token is the
108 handle argument for all other commands. If no port is specified
109 it will default to 389.
110 The command blocks until the connection has been established, or
112 establishment definitely failed.
113 ::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?
115 Like ::ldap::connect, except that the created connection is se‐
116 cured by SSL. The port defaults to 636. This command depends on
117 the availability of the package TLS, which is a SSL binding for
118 Tcl. If TLS is not available, then this command will fail.
119 The command blocks until the connection has been established, or
121 establishment definitely failed.
122 If verify_cert is set to 1, the default, this checks the server
124 certificate against the known hosts. If sni_servername is set,
125 the given hostname is used as the hostname for Server Name Indi‐
126 cation in the TLS handshake.
127 Use ::tls::init to setup defaults for trusted certificates.
129 tls::init -cadir /etc/ssl/certs/ca-certificates.crt
132 TLS supports different protocol levels. In common use are the versions
135 1.0, 1.1 and 1.2. By default all those versions are offered. If you
136 need to modify the acceptable protocols, you can change the ::ldap::tl‐
137 sProtocols list.
138 ::ldap::disconnect handle
140 Closes the ldap connection refered to by the token handle. Re‐
141 turns the empty string as its result.
142 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert?
144 ?sni_servername?
145 Start TLS negotiation on the connection denoted by handle. You
146 need to set at least the cafile argument to a file with trusted
147 certificates, if verify_cert is 1, which is the default. The
148 sni_servername can be used to signal a different hostname during
149 the TLS handshake. The announced protocols are determined in
150 the same way as ::ldap::secure_connect. You can specify a TLS
151 client certificate with the certfile and keyfile options.
152 ::ldap::bind handle ?name? ?password?
154 This command authenticates the ldap connection refered to by the
155 token in handle, with a user name and associated password. It
156 blocks until a response from the ldap server arrives. Its result
157 is the empty string. Both name and passwd default to the empty
158 string if they are not specified. By leaving out name and
159 passwd you can make an anonymous bind to the ldap server. You
160 can issue ::ldap::bind again to bind with different credentials.
161 ::ldap::bindSASL handle ?name? ?password?
163 This command uses SASL authentication mechanisms to do a multi‐
164 stage bind. Its otherwise identical to the standard
165 ::ldap::bind. This feature is currently experimental and sub‐
166 ject to change. See the documentation for the SASL and the
167 "SASL.txt" in the tcllib CVS repository for details how to setup
168 and use SASL with openldap.
169 ::ldap::unbind handle
171 This command asks the ldap server to release the last bind done
172 for the connection refered to by the token in handle. The han‐
173 dle is invalid after the unbind, as the server closes the con‐
174 nection. So this is effectivly just a more polite disconnect
175 operation.
176 ::ldap::search handle baseObject filterString attributes options
178 This command performs a LDAP search below the baseObject tree
179 using a complex LDAP search expression filterString and returns
180 the specified attributes of all matching objects (DNs). If the
181 list of attributes was empty all attributes are returned. The
182 command blocks until it has received all results. The valid op‐
183 tions are identical to the options listed for ::ldap::sear‐
184 chInit.
185 An example of a search expression is
187 set filterString "|(cn=Linus*)(sn=Torvalds*)"
191 The return value of the command is a list of nested dictionaries. The
194 first level keys are object identifiers (DNs), second levels keys are
195 attribute names. In other words, it is in the form
196 {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
200 ::ldap::searchInit handle baseObject filterString attributes options
204 This command initiates a LDAP search below the baseObject tree
205 using a complex LDAP search expression filterString. The search
206 gets the specified attributes of all matching objects (DNs).
207 The command itself just starts the search, to retrieve the ac‐
208 tual results, use ::ldap::searchNext. A search can be termi‐
209 nated at any time by ::ldap::searchEnd. This informs the server
210 that no further results should be sent by sending and ABANDON
211 message and cleans up the internal state of the search. Only
212 one ::ldap::search can be active at a given time, this includes
213 the introspection commands ::ldap::info saslmechanisms,
214 ldap::info control and ldap::info extensions, which invoke a
215 search internally. Error responses from the server due to wrong
216 arguments or similar things are returned with the first
217 ::ldap::searchNext call and should be checked and dealed with
218 there. If the list of requested attributes is empty all at‐
219 tributes will be returned. The parameter options specifies the
220 options to be used in the search, and has the following format:
221 {-option1 value1 -option2 value2 ... }
225 Following options are available:
228 -scope base one sub
230 Control the scope of the search to be one of base, one,
231 or sub, to specify a base object, one-level or sub‐
232 tree search. The default is sub.
233 -derefaliases never search find always
235 Control how aliases dereferencing is done. Should be one
236 of never, always, search, or find to specify that
237 aliases are never dereferenced, always dereferenced,
238 dereferenced when searching, or dereferenced only when
239 locating the base object for the search. The default is
240 to never dereference aliases.
241 -sizelimit num
243 Determines the maximum number of entries to return in a
244 search. If specified as 0 no limit is enforced. The
245 server may enforce a configuration dependent sizelimit,
246 which may be lower than the one given by this option. The
247 default is 0, no limit.
248 -timelimit seconds
250 Asks the server to use a timelimit of seconds for the
251 search. Zero means no limit. The default is 0, no limit.
252 -attrsonly boolean
254 If set to 1 only the attribute names but not the values
255 will be present in the search result. The default is to
256 retrieve attribute names and values.
257 -referencevar varname
259 If set the search result reference LDAPURIs, if any, are
260 returned in the given variable. The caller can than de‐
261 cide to follow those references and query other LDAP
262 servers for further results.
263 ::ldap::searchNext handle
266 This command returns the next entry from a LDAP search initiated
267 by ::ldap::searchInit. It returns only after a new result is re‐
268 ceived or when no further results are available, but takes care
269 to keep the event loop alive. The returned entry is a list with
270 two elements: the first is the DN of the entry, the second is
271 the list of attributes and values, under the format:
272 dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
276 The ::ldap::searchNext command returns an empty list at the end of the
279 search.
280 ::ldap::searchEnd handle
283 This command terminates a LDAP search initiated by ::ldap::sear‐
284 chInit. It also cleans up the internal state so a new search can
285 be initiated. If the client has not yet received all results,
286 the client sends an ABANDON message to inform the server that no
287 further results for the previous search should to be sent.
288 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
291 This command modifies the object dn on the ldap server we are
292 connected to via handle. It replaces attributes with new values,
293 deletes attributes, and adds new attributes with new values.
294 All arguments are dictionaries mapping attribute names to val‐
295 ues. The optional arguments default to the empty dictionary,
296 which means that no attributes will be deleted nor added.
297 dictionary attrValToReplace (in)
299 No attributes will be changed if this argument is empty.
300 The dictionary contains the new attributes and their val‐
301 ues. They replace all attributes known to the object.
302 dictionary attrToDelete (in)
304 No attributes will be deleted if this argument is empty.
305 The dictionary values are restrictions on the deletion.
306 An attribute listed here will be deleted if and only if
307 its current value at the server matches the value speci‐
308 fied in the dictionary, or if the value in the dictionary
309 is the empty string.
310 dictionary attrValToAdd (in)
312 No attributes will be added if this argument is empty.
313 The dictionary values are the values for the new at‐
314 tributes.
315 The command blocks until all modifications have completed. Its result
317 is the empty string.
318 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
320 ValToAdd?
321 This command modifies the object dn on the ldap server we are
322 connected to via handle. It replaces attributes with new values,
323 deletes attributes, and adds new attributes with new values.
324 All arguments are lists with the format:
325 attr1 {val11 val12 ...} attr2 {val21...} ...
329 where each value list may be empty for deleting all attributes. The
332 optional arguments default to empty lists of attributes to delete and
333 to add.
334 list attrValToReplace (in)
336 No attributes will be changed if this argument is empty.
337 The dictionary contains the new attributes and their val‐
338 ues. They replace all attributes known to the object.
339 list attrValToDelete (in)
341 No attributes will be deleted if this argument is empty.
342 If no value is specified, the whole set of values for an
343 attribute will be deleted.
344 list attrValToAdd (in)
346 No attributes will be added if this argument is empty.
347 The command blocks until all modifications have completed. Its result
349 is the empty string.
350 ::ldap::add handle dn attrValueTuples
352 This command creates a new object using the specified dn. The
353 attributes of the new object are set to the values in the list
354 attrValueTuples. Multiple valuated attributes may be specified
355 using multiple tuples. The command blocks until the operation
356 has completed. Its result is the empty string.
357 ::ldap::addMulti handle dn attrValueTuples
359 This command is the preferred one to create a new object using
360 the specified dn. The attributes of the new object are set to
361 the values in the dictionary attrValueTuples (which is keyed by
362 the attribute names). Each tuple is a list containing multiple
363 values. The command blocks until the operation has completed.
364 Its result is the empty string.
365 ::ldap::delete handle dn
367 This command removes the object specified by dn, and all its at‐
368 tributes from the server. The command blocks until the opera‐
369 tion has completed. Its result is the empty string.
370 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
372 This command moves or copies the object specified by dn to a new
373 location in the tree of object. This location is specified by
374 newrdn, a relative designation, or by newrdn and newSuperior, a
375 absolute designation. The optional argument deleteOld defaults
376 to true, i.e. a move operation. If deleteOld is not set, then
377 the operation will create a copy of dn in the new location. The
378 optional argument newSuperior defaults an empty string, meaning
379 that the object must not be relocated in another branch of the
380 tree. If this argument is given, the argument deleteOld must be
381 specified also. The command blocks until the operation has com‐
382 pleted. Its result is the empty string.
383 ::ldap::info ip handle
385 This command returns the IP address of the remote LDAP server
386 the handle is connected to.
387 ::ldap::info bound handle
389 This command returns 1 if a handle has successfully completed a
390 ::ldap::bind. If no bind was done or it failed, a 0 is re‐
391 turned.
392 ::ldap::info bounduser handle
394 This command returns the username used in the bind operation if
395 a handle has successfully completed a ::ldap::bind. If no bound
396 was done or it failed, an empty string is returned.
397 ::ldap::info connections
399 This command returns all currently existing ldap connection han‐
400 dles.
401 ::ldap::info tls handle
403 This command returns 1 if the ldap connection handle used
404 TLS/SSL for connection via ldap::secure_connect or completed
405 ldap::starttls, 0 otherwise.
406 ::ldap::info saslmechanisms handle
408 Return the supported SASL mechanisms advertised by the server.
409 Only valid in a bound state (anonymous or other).
410 ::ldap::info control handle
412 Return the supported controls advertised by the server as a list
413 of OIDs. Only valid in a bound state. This is currently experi‐
414 mental and subject to change.
415 ::ldap::info extensions extensions
417 Returns the supported LDAP extensions as list of OIDs. Only
418 valid in a bound state. This is currently experimental and sub‐
419 ject to change.
420 ::ldap::info whoami handle
422 Returns authzId for the current connection. This implements the
423 RFC 4532 protocol extension.
424
426 A small example, extracted from the test application coming with this
427 code.
428 package require ldap
430 # Connect, bind, add a new object, modify it in various ways
432 set handle [ldap::connect localhost 9009]
434 set dn "cn=Manager, o=University of Michigan, c=US"
436 set pw secret
437 ldap::bind $handle $dn $pw
439 set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
441 ldap::add $handle $dn {
443 objectClass OpenLDAPperson
444 cn {Test User}
445 mail test.user@google.com
446 uid testuid
447 sn User
448 telephoneNumber +31415926535
449 telephoneNumber +27182818285
450 }
451 set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
453 ldap::addMulti $handle $dn {
455 objectClass {OpenLDAPperson}
456 cn {{Anotther User}}
457 mail {test.user@google.com}
458 uid {testuid}
459 sn {User}
460 telephoneNumber {+31415926535 +27182818285}
461 }
462 # Replace all attributes
464 ldap::modify $handle $dn [list drink icetea uid JOLO]
465 # Add some more
467 ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]
468 # Delete
470 ldap::modify $handle $dn {} [list drink water pager ""]
471 # Move
473 ldap::modifyDN $handle $dn "cn=Tester"
474 # Kill the test object, and shut the connection down.
476 set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
477 ldap::delete $handle $dn
478 ldap::unbind $handle
480 ldap::disconnect $handle
481 And a another example, a simple query, and processing the results.
484 package require ldap
486 set handle [ldap::connect ldap.acme.com 389]
487 ldap::bind $handle
488 set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
489 foreach result $results {
490 foreach {object attributes} $result break
491 # The processing here is similar to what 'parray' does.
493 # I.e. finding the longest attribute name and then
494 # generating properly aligned output listing all attributes
495 # and their values.
496 set width 0
498 set sortedAttribs {}
499 foreach {type values} $attributes {
500 if {[string length $type] > $width} {
501 set width [string length $type]
502 }
503 lappend sortedAttribs [list $type $values]
504 }
505 puts "object='$object'"
507 foreach sortedAttrib $sortedAttribs {
509 foreach {type values} $sortedAttrib break
510 foreach value $values {
511 regsub -all "\[\x01-\x1f\]" $value ? value
512 puts [format " %-${width}s %s" $type $value]
513 }
514 }
515 puts ""
516 }
517 ldap::unbind $handle
518 ldap::disconnect $handle
519
522 This document, and the package it describes, will undoubtedly contain
523 bugs and other problems. Please report such in the category ldap of
524 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
525 also report any ideas for enhancements you may have for either package
526 and/or documentation.
527 When proposing code changes, please provide unified diffs, i.e the out‐
529 put of diff -u.
530 Note further that attachments are strongly preferred over inlined
532 patches. Attachments can be made by going to the Edit form of the
533 ticket immediately after its creation, and then using the left-most
534 button in the secondary navigation bar.
535
537 directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc
538 4511, x.500
539
541 Networking
542
544 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
545 Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
546 Copyright (c) 2006 Michael Schlenker <mic42@users.sourceforge.net>
547tcllib 1.9.2 ldap(n)