1ldap(n) LDAP client ldap(n)
2______________________________________________________________________________
6
8 ldap - LDAP client
9
11 package require Tcl 8.5
12 package require ldap ?1.10.1?
14 ::ldap::connect host ?port?
16 ::ldap::tlsoptions reset
18 ::ldap::tlsoptions ?opt1 val1? ?opt2 val2? ...
20 ::ldap::secure_connect host ?port?
22 ::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?
24 ::ldap::disconnect handle
26 ::ldap::starttls handle
28 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert?
30 ?sni_servername?
31 ::ldap::bind handle ?name? ?password?
33 ::ldap::bindSASL handle ?name? ?password?
35 ::ldap::unbind handle
37 ::ldap::search handle baseObject filterString attributes options
39 ::ldap::searchInit handle baseObject filterString attributes options
41 ::ldap::searchNext handle
43 ::ldap::searchEnd handle
45 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
47 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
49 ValToAdd?
50 ::ldap::add handle dn attrValueTuples
52 ::ldap::addMulti handle dn attrValueTuples
54 ::ldap::delete handle dn
56 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
58 ::ldap::info ip handle
60 ::ldap::info bound handle
62 ::ldap::info bounduser handle
64 ::ldap::info connections
66 ::ldap::info tls handle
68 ::ldap::info tlsstatus handle
70 ::ldap::info saslmechanisms handle
72 ::ldap::info control handle
74 ::ldap::info extensions extensions
76 ::ldap::info whoami handle
78______________________________________________________________________________
80
82 The ldap package provides a Tcl-only client library for the LDAPv3 pro‐
83 tocol as specified in RFC 4511 (http://www.rfc-edi‐
84 tor.org/rfc/rfc4511.txt). It works by opening the standard (or secure)
85 LDAP socket on the server, and then providing a Tcl API to access the
86 LDAP protocol commands. All server errors are returned as Tcl errors
87 (thrown) which must be caught with the Tcl catch command.
88
90 This package uses the TLS package to handle the security for LDAPS con‐
91 nections.
92 Policy decisions like the set of protocols to support and what ciphers
94 to use are not the responsibility of TLS, nor of this package itself
95 however. Such decisions are the responsibility of whichever applica‐
96 tion is using the package, and are likely influenced by the set of
97 servers the application will talk to as well.
98 For example, in light of the recent POODLE attack [http://googleonli‐
100 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
101 ssl-30.html] discovered by Google many servers will disable support for
102 the SSLv3 protocol. To handle this change the applications using TLS
103 must be patched, and not this package, nor TLS itself. Such a patch
104 may be as simple as generally activating tls1 support, as shown in the
105 example below.
106 ldap::tlsoptions -tls1 1 -ssl2 0 -ssl3 0 ;# forcibly activate support for the TLS1 protocol
109 ... your own application code ...
111
114 ::ldap::connect host ?port?
115 Opens a LDAPv3 connection to the specified host, at the given
116 port, and returns a token for the connection. This token is the
117 handle argument for all other commands. If no port is specified
118 it will default to 389.
119 The command blocks until the connection has been established, or
121 establishment definitely failed.
122 ::ldap::tlsoptions reset
124 This command resets TLS options to default values. It returns
125 the set of options. Using this command is incompatible with the
126 obsolete form of ::ldap::secure_connect and ::ldap_starttls.
127 ::ldap::tlsoptions ?opt1 val1? ?opt2 val2? ...
129 This commands adds one or more options to some value, and may be
130 used more than one time in order to add options in several
131 steps. A complete description of options may be found in the
132 tls package documentation. Valid options and values are:
133 -cadir directory
135 Provide the directory containing the CA certificates. No
136 default.
137 -cafile file
139 Provide the CA file. No default.
140 -cipher string
142 Provide the cipher suites to use. No default.
143 -dhparams file
145 Provide a Diffie-Hellman parameters file. No default.
146 -request boolean
148 Request a certificate from peer during SSL handshake.
149 Default: true.
150 -require boolean
152 Require a valid certificate from peer during SSL hand‐
153 shake. If this is set to true then -request must also be
154 set to true. Default: false
155 -servername host
157 Only available if the OpenSSL library the TLS package is
158 linked against supports the TLS hostname extension for
159 'Server Name Indication' (SNI). Use to name the logical
160 host we are talking to and expecting a certificate for.
161 No default.
162 -ssl2 bool
164 Enable use of SSL v2. Default: false
165 -ssl3 bool
167 Enable use of SSL v3. Default: false
168 -tls1 bool
170 Enable use of TLS v1 Default: true
171 -tls1.1 bool
173 Enable use of TLS v1.1 Default: true
174 -tls1.2 bool
176 Enable use of TLS v1.2 Default: true
177 This command returns the current set of TLS options and values. In
179 particular, one may use this command without any arguments to get the
180 current set of options.
181 Using this command is incompatible with the obsolete form of
183 ::ldap::secure_connect and ::ldap_starttls (see below).
184 ::ldap::secure_connect host ?port?
186 Like ::ldap::connect, except that the created connection is se‐
187 cured by SSL. The port defaults to 636. This command depends on
188 the availability of the package TLS, which is a SSL binding for
189 Tcl. If TLS is not available, then this command will fail.
190 TLS options are specified with ::ldap::tlsoptions.
192 The command blocks until the connection has been established, or
194 establishment definitely failed.
195 ::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?
197 Note: this form of the command is deprecated, since TLS options
198 had to be specified with a combination of parameters to this
199 command (verify_cert and sni_servername) and arguments to
200 ::tls::init (from package tls) for example to setup defaults for
201 trusted certificates. Prefer the above form (without the ver‐
202 ify_cert and sni_servername parameters) and set TLS options with
203 ::ldap::tlsoptions.
204 If verify_cert is set to 1, the default, this checks the server
206 certificate against the known hosts. If sni_servername is set,
207 the given hostname is used as the hostname for Server Name Indi‐
208 cation in the TLS handshake.
209 Use ::tls::init to setup defaults for trusted certificates.
211 TLS supports different protocol levels. In common use are the
213 versions 1.0, 1.1 and 1.2. By default all those versions are
214 offered. If you need to modify the acceptable protocols, you can
215 change the ::ldap::tlsProtocols list (deprecated).
216 ::ldap::disconnect handle
218 Closes the ldap connection refered to by the token handle. Re‐
219 turns the empty string as its result.
220 ::ldap::starttls handle
222 Start TLS negotiation on the connection denoted by handle, with
223 TLS parameters set with ::ldap::tlsoptions.
224 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert?
226 ?sni_servername?
227 Note: this form of the command is deprecated, since TLS options
228 had to be specified with a combination of parameters to this
229 command (cafile, certfile, keyfile, verify_cert and sni_server‐
230 name) and arguments to ::tls::init (from package tls). Prefer
231 the above form (without specific TLS arguments) and set TLS op‐
232 tions with ::ldap::tlsoptions.
233 Start TLS negotiation on the connection denoted by handle. You
235 need to set at least the cafile argument to a file with trusted
236 certificates, if verify_cert is 1, which is the default. The
237 sni_servername can be used to signal a different hostname during
238 the TLS handshake. The announced protocols are determined in
239 the same way as ::ldap::secure_connect. You can specify a TLS
240 client certificate with the certfile and keyfile options.
241 ::ldap::bind handle ?name? ?password?
243 This command authenticates the ldap connection refered to by the
244 token in handle, with a user name and associated password. It
245 blocks until a response from the ldap server arrives. Its result
246 is the empty string. Both name and passwd default to the empty
247 string if they are not specified. By leaving out name and
248 passwd you can make an anonymous bind to the ldap server. You
249 can issue ::ldap::bind again to bind with different credentials.
250 ::ldap::bindSASL handle ?name? ?password?
252 This command uses SASL authentication mechanisms to do a multi‐
253 stage bind. Its otherwise identical to the standard
254 ::ldap::bind. This feature is currently experimental and sub‐
255 ject to change. See the documentation for the SASL and the
256 "SASL.txt" in the tcllib CVS repository for details how to setup
257 and use SASL with openldap.
258 ::ldap::unbind handle
260 This command asks the ldap server to release the last bind done
261 for the connection refered to by the token in handle. The han‐
262 dle is invalid after the unbind, as the server closes the con‐
263 nection. So this is effectivly just a more polite disconnect
264 operation.
265 ::ldap::search handle baseObject filterString attributes options
267 This command performs a LDAP search below the baseObject tree
268 using a complex LDAP search expression filterString and returns
269 the specified attributes of all matching objects (DNs). If the
270 list of attributes was empty all attributes are returned. The
271 command blocks until it has received all results. The valid op‐
272 tions are identical to the options listed for ::ldap::sear‐
273 chInit.
274 An example of a search expression is
276 set filterString "|(cn=Linus*)(sn=Torvalds*)"
280 The return value of the command is a list of nested dictionaries. The
283 first level keys are object identifiers (DNs), second levels keys are
284 attribute names. In other words, it is in the form
285 {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
289 ::ldap::searchInit handle baseObject filterString attributes options
293 This command initiates a LDAP search below the baseObject tree
294 using a complex LDAP search expression filterString. The search
295 gets the specified attributes of all matching objects (DNs).
296 The command itself just starts the search, to retrieve the ac‐
297 tual results, use ::ldap::searchNext. A search can be termi‐
298 nated at any time by ::ldap::searchEnd. This informs the server
299 that no further results should be sent by sending and ABANDON
300 message and cleans up the internal state of the search. Only
301 one ::ldap::search can be active at a given time, this includes
302 the introspection commands ::ldap::info saslmechanisms,
303 ldap::info control and ldap::info extensions, which invoke a
304 search internally. Error responses from the server due to wrong
305 arguments or similar things are returned with the first
306 ::ldap::searchNext call and should be checked and dealed with
307 there. If the list of requested attributes is empty all at‐
308 tributes will be returned. The parameter options specifies the
309 options to be used in the search, and has the following format:
310 {-option1 value1 -option2 value2 ... }
314 Following options are available:
317 -scope base one sub
319 Control the scope of the search to be one of base, one,
320 or sub, to specify a base object, one-level or sub‐
321 tree search. The default is sub.
322 -derefaliases never search find always
324 Control how aliases dereferencing is done. Should be one
325 of never, always, search, or find to specify that
326 aliases are never dereferenced, always dereferenced,
327 dereferenced when searching, or dereferenced only when
328 locating the base object for the search. The default is
329 to never dereference aliases.
330 -sizelimit num
332 Determines the maximum number of entries to return in a
333 search. If specified as 0 no limit is enforced. The
334 server may enforce a configuration dependent sizelimit,
335 which may be lower than the one given by this option. The
336 default is 0, no limit.
337 -timelimit seconds
339 Asks the server to use a timelimit of seconds for the
340 search. Zero means no limit. The default is 0, no limit.
341 -attrsonly boolean
343 If set to 1 only the attribute names but not the values
344 will be present in the search result. The default is to
345 retrieve attribute names and values.
346 -referencevar varname
348 If set the search result reference LDAPURIs, if any, are
349 returned in the given variable. The caller can than de‐
350 cide to follow those references and query other LDAP
351 servers for further results.
352 ::ldap::searchNext handle
355 This command returns the next entry from a LDAP search initiated
356 by ::ldap::searchInit. It returns only after a new result is re‐
357 ceived or when no further results are available, but takes care
358 to keep the event loop alive. The returned entry is a list with
359 two elements: the first is the DN of the entry, the second is
360 the list of attributes and values, under the format:
361 dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
365 The ::ldap::searchNext command returns an empty list at the end of the
368 search.
369 ::ldap::searchEnd handle
372 This command terminates a LDAP search initiated by ::ldap::sear‐
373 chInit. It also cleans up the internal state so a new search can
374 be initiated. If the client has not yet received all results,
375 the client sends an ABANDON message to inform the server that no
376 further results for the previous search should to be sent.
377 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
380 This command modifies the object dn on the ldap server we are
381 connected to via handle. It replaces attributes with new values,
382 deletes attributes, and adds new attributes with new values.
383 All arguments are dictionaries mapping attribute names to val‐
384 ues. The optional arguments default to the empty dictionary,
385 which means that no attributes will be deleted nor added.
386 dictionary attrValToReplace (in)
388 No attributes will be changed if this argument is empty.
389 The dictionary contains the new attributes and their val‐
390 ues. They replace all attributes known to the object.
391 dictionary attrToDelete (in)
393 No attributes will be deleted if this argument is empty.
394 The dictionary values are restrictions on the deletion.
395 An attribute listed here will be deleted if and only if
396 its current value at the server matches the value speci‐
397 fied in the dictionary, or if the value in the dictionary
398 is the empty string.
399 dictionary attrValToAdd (in)
401 No attributes will be added if this argument is empty.
402 The dictionary values are the values for the new at‐
403 tributes.
404 The command blocks until all modifications have completed. Its result
406 is the empty string.
407 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
409 ValToAdd?
410 This command modifies the object dn on the ldap server we are
411 connected to via handle. It replaces attributes with new values,
412 deletes attributes, and adds new attributes with new values.
413 All arguments are lists with the format:
414 attr1 {val11 val12 ...} attr2 {val21...} ...
418 where each value list may be empty for deleting all attributes. The
421 optional arguments default to empty lists of attributes to delete and
422 to add.
423 list attrValToReplace (in)
425 No attributes will be changed if this argument is empty.
426 The dictionary contains the new attributes and their val‐
427 ues. They replace all attributes known to the object.
428 list attrValToDelete (in)
430 No attributes will be deleted if this argument is empty.
431 If no value is specified, the whole set of values for an
432 attribute will be deleted.
433 list attrValToAdd (in)
435 No attributes will be added if this argument is empty.
436 The command blocks until all modifications have completed. Its result
438 is the empty string.
439 ::ldap::add handle dn attrValueTuples
441 This command creates a new object using the specified dn. The
442 attributes of the new object are set to the values in the list
443 attrValueTuples. Multiple valuated attributes may be specified
444 using multiple tuples. The command blocks until the operation
445 has completed. Its result is the empty string.
446 ::ldap::addMulti handle dn attrValueTuples
448 This command is the preferred one to create a new object using
449 the specified dn. The attributes of the new object are set to
450 the values in the dictionary attrValueTuples (which is keyed by
451 the attribute names). Each tuple is a list containing multiple
452 values. The command blocks until the operation has completed.
453 Its result is the empty string.
454 ::ldap::delete handle dn
456 This command removes the object specified by dn, and all its at‐
457 tributes from the server. The command blocks until the opera‐
458 tion has completed. Its result is the empty string.
459 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
461 This command moves or copies the object specified by dn to a new
462 location in the tree of object. This location is specified by
463 newrdn, a relative designation, or by newrdn and newSuperior, a
464 absolute designation. The optional argument deleteOld defaults
465 to true, i.e. a move operation. If deleteOld is not set, then
466 the operation will create a copy of dn in the new location. The
467 optional argument newSuperior defaults an empty string, meaning
468 that the object must not be relocated in another branch of the
469 tree. If this argument is given, the argument deleteOld must be
470 specified also. The command blocks until the operation has com‐
471 pleted. Its result is the empty string.
472 ::ldap::info ip handle
474 This command returns the IP address of the remote LDAP server
475 the handle is connected to.
476 ::ldap::info bound handle
478 This command returns 1 if a handle has successfully completed a
479 ::ldap::bind. If no bind was done or it failed, a 0 is re‐
480 turned.
481 ::ldap::info bounduser handle
483 This command returns the username used in the bind operation if
484 a handle has successfully completed a ::ldap::bind. If no bound
485 was done or it failed, an empty string is returned.
486 ::ldap::info connections
488 This command returns all currently existing ldap connection han‐
489 dles.
490 ::ldap::info tls handle
492 This command returns 1 if the ldap connection handle used
493 TLS/SSL for connection via ldap::secure_connect or completed
494 ldap::starttls, 0 otherwise.
495 ::ldap::info tlsstatus handle
497 This command returns the current security status of an TLS se‐
498 cured channel. The result is a list of key-value pairs describ‐
499 ing the connected peer (see the TLS package documentation for
500 the returned values). If the connection is not secured with
501 TLS, an empty list is returned.
502 ::ldap::info saslmechanisms handle
504 Return the supported SASL mechanisms advertised by the server.
505 Only valid in a bound state (anonymous or other).
506 ::ldap::info control handle
508 Return the supported controls advertised by the server as a list
509 of OIDs. Only valid in a bound state. This is currently experi‐
510 mental and subject to change.
511 ::ldap::info extensions extensions
513 Returns the supported LDAP extensions as list of OIDs. Only
514 valid in a bound state. This is currently experimental and sub‐
515 ject to change.
516 ::ldap::info whoami handle
518 Returns authzId for the current connection. This implements the
519 RFC 4532 protocol extension.
520
522 A small example, extracted from the test application coming with this
523 code.
524 package require ldap
526 # Connect, bind, add a new object, modify it in various ways
528 set handle [ldap::connect localhost 9009]
530 set dn "cn=Manager, o=University of Michigan, c=US"
532 set pw secret
533 ldap::bind $handle $dn $pw
535 set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
537 ldap::add $handle $dn {
539 objectClass OpenLDAPperson
540 cn {Test User}
541 mail test.user@google.com
542 uid testuid
543 sn User
544 telephoneNumber +31415926535
545 telephoneNumber +27182818285
546 }
547 set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
549 ldap::addMulti $handle $dn {
551 objectClass {OpenLDAPperson}
552 cn {{Anotther User}}
553 mail {test.user@google.com}
554 uid {testuid}
555 sn {User}
556 telephoneNumber {+31415926535 +27182818285}
557 }
558 # Replace all attributes
560 ldap::modify $handle $dn [list drink icetea uid JOLO]
561 # Add some more
563 ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]
564 # Delete
566 ldap::modify $handle $dn {} [list drink water pager ""]
567 # Move
569 ldap::modifyDN $handle $dn "cn=Tester"
570 # Kill the test object, and shut the connection down.
572 set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
573 ldap::delete $handle $dn
574 ldap::unbind $handle
576 ldap::disconnect $handle
577 And another example, a simple query, and processing the results.
580 package require ldap
582 set handle [ldap::connect ldap.acme.com 389]
583 ldap::bind $handle
584 set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
585 foreach result $results {
586 foreach {object attributes} $result break
587 # The processing here is similar to what 'parray' does.
589 # I.e. finding the longest attribute name and then
590 # generating properly aligned output listing all attributes
591 # and their values.
592 set width 0
594 set sortedAttribs {}
595 foreach {type values} $attributes {
596 if {[string length $type] > $width} {
597 set width [string length $type]
598 }
599 lappend sortedAttribs [list $type $values]
600 }
601 puts "object='$object'"
603 foreach sortedAttrib $sortedAttribs {
605 foreach {type values} $sortedAttrib break
606 foreach value $values {
607 regsub -all "\[\x01-\x1f\]" $value ? value
608 puts [format " %-${width}s %s" $type $value]
609 }
610 }
611 puts ""
612 }
613 ldap::unbind $handle
614 ldap::disconnect $handle
615
618 This document, and the package it describes, will undoubtedly contain
619 bugs and other problems. Please report such in the category ldap of
620 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
621 also report any ideas for enhancements you may have for either package
622 and/or documentation.
623 When proposing code changes, please provide unified diffs, i.e the out‐
625 put of diff -u.
626 Note further that attachments are strongly preferred over inlined
628 patches. Attachments can be made by going to the Edit form of the
629 ticket immediately after its creation, and then using the left-most
630 button in the secondary navigation bar.
631
633 directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc
634 4511, x.500
635
637 Networking
638
640 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
641 Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
642 Copyright (c) 2006 Michael Schlenker <mic42@users.sourceforge.net>
643tcllib 1.10.1 ldap(n)