create-animated-image: Don't add heuristic mask to image (Bug#6839).
[emacs.git] / lisp / net / ldap.el
blob4676aba2d9a08f9e463a887f794d2486c53bd982
1 ;;; ldap.el --- client interface to LDAP for Emacs
3 ;; Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004,
4 ;; 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
6 ;; Author: Oscar Figueiredo <oscar@cpe.fr>
7 ;; Maintainer: FSF
8 ;; Created: April 1998
9 ;; Keywords: comm
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
26 ;;; Commentary:
28 ;; This package provides basic functionality to perform searches on LDAP
29 ;; servers. It requires a command line utility generally named
30 ;; `ldapsearch' to actually perform the searches. That program can be
31 ;; found in all LDAP developer kits such as:
32 ;; - UM-LDAP 3.3 (http://www.umich.edu/~dirsvcs/ldap/)
33 ;; - OpenLDAP (http://www.openldap.org/)
35 ;;; Code:
37 (require 'custom)
38 (eval-when-compile (require 'cl))
40 (defgroup ldap nil
41 "Lightweight Directory Access Protocol."
42 :version "21.1"
43 :group 'comm)
45 (defcustom ldap-default-host nil
46 "*Default LDAP server.
47 A TCP port number can be appended to that name using a colon as
48 a separator."
49 :type '(choice (string :tag "Host name")
50 (const :tag "Use library default" nil))
51 :group 'ldap)
53 (defcustom ldap-default-port nil
54 "*Default TCP port for LDAP connections.
55 Initialized from the LDAP library at build time. Default value is 389."
56 :type '(choice (const :tag "Use library default" nil)
57 (integer :tag "Port number"))
58 :group 'ldap)
60 (defcustom ldap-default-base nil
61 "*Default base for LDAP searches.
62 This is a string using the syntax of RFC 1779.
63 For instance, \"o=ACME, c=US\" limits the search to the
64 Acme organization in the United States."
65 :type '(choice (const :tag "Use library default" nil)
66 (string :tag "Search base"))
67 :group 'ldap)
70 (defcustom ldap-host-parameters-alist nil
71 "*Alist of host-specific options for LDAP transactions.
72 The format of each list element is (HOST PROP1 VAL1 PROP2 VAL2 ...).
73 HOST is the hostname of an LDAP server (with an optional TCP port number
74 appended to it using a colon as a separator).
75 PROPn and VALn are property/value pairs describing parameters for the server.
76 Valid properties include:
77 `binddn' is the distinguished name of the user to bind as
78 (in RFC 1779 syntax).
79 `passwd' is the password to use for simple authentication.
80 `auth' is the authentication method to use.
81 Possible values are: `simple', `krbv41' and `krbv42'.
82 `base' is the base for the search as described in RFC 1779.
83 `scope' is one of the three symbols `subtree', `base' or `onelevel'.
84 `deref' is one of the symbols `never', `always', `search' or `find'.
85 `timelimit' is the timeout limit for the connection in seconds.
86 `sizelimit' is the maximum number of matches to return."
87 :type '(repeat :menu-tag "Host parameters"
88 :tag "Host parameters"
89 (list :menu-tag "Host parameters"
90 :tag "Host parameters"
91 :value nil
92 (string :tag "Host name")
93 (checklist :inline t
94 :greedy t
95 (list
96 :tag "Search Base"
97 :inline t
98 (const :tag "Search Base" base)
99 string)
100 (list
101 :tag "Binding DN"
102 :inline t
103 (const :tag "Binding DN" binddn)
104 string)
105 (list
106 :tag "Password"
107 :inline t
108 (const :tag "Password" passwd)
109 string)
110 (list
111 :tag "Authentication Method"
112 :inline t
113 (const :tag "Authentication Method" auth)
114 (choice
115 (const :menu-tag "None" :tag "None" nil)
116 (const :menu-tag "Simple" :tag "Simple" simple)
117 (const :menu-tag "Kerberos 4.1" :tag "Kerberos 4.1" krbv41)
118 (const :menu-tag "Kerberos 4.2" :tag "Kerberos 4.2" krbv42)))
119 (list
120 :tag "Search Scope"
121 :inline t
122 (const :tag "Search Scope" scope)
123 (choice
124 (const :menu-tag "Default" :tag "Default" nil)
125 (const :menu-tag "Subtree" :tag "Subtree" subtree)
126 (const :menu-tag "Base" :tag "Base" base)
127 (const :menu-tag "One Level" :tag "One Level" onelevel)))
128 (list
129 :tag "Dereferencing"
130 :inline t
131 (const :tag "Dereferencing" deref)
132 (choice
133 (const :menu-tag "Default" :tag "Default" nil)
134 (const :menu-tag "Never" :tag "Never" never)
135 (const :menu-tag "Always" :tag "Always" always)
136 (const :menu-tag "When searching" :tag "When searching" search)
137 (const :menu-tag "When locating base" :tag "When locating base" find)))
138 (list
139 :tag "Time Limit"
140 :inline t
141 (const :tag "Time Limit" timelimit)
142 (integer :tag "(in seconds)"))
143 (list
144 :tag "Size Limit"
145 :inline t
146 (const :tag "Size Limit" sizelimit)
147 (integer :tag "(number of records)")))))
148 :group 'ldap)
150 (defcustom ldap-ldapsearch-prog "ldapsearch"
151 "*The name of the ldapsearch command line program."
152 :type '(string :tag "`ldapsearch' Program")
153 :group 'ldap)
155 (defcustom ldap-ldapsearch-args '("-LL" "-tt")
156 "*A list of additional arguments to pass to `ldapsearch'."
157 :type '(repeat :tag "`ldapsearch' Arguments"
158 (string :tag "Argument"))
159 :group 'ldap)
161 (defcustom ldap-ignore-attribute-codings nil
162 "*If non-nil, do not encode/decode LDAP attribute values."
163 :type 'boolean
164 :group 'ldap)
166 (defcustom ldap-default-attribute-decoder nil
167 "*Decoder function to use for attributes whose syntax is unknown."
168 :type 'symbol
169 :group 'ldap)
171 (defcustom ldap-coding-system 'utf-8
172 "*Coding system of LDAP string values.
173 LDAP v3 specifies the coding system of strings to be UTF-8."
174 :type 'symbol
175 :group 'ldap)
177 (defvar ldap-attribute-syntax-encoders
178 [nil ; 1 ACI Item N
179 nil ; 2 Access Point Y
180 nil ; 3 Attribute Type Description Y
181 nil ; 4 Audio N
182 nil ; 5 Binary N
183 nil ; 6 Bit String Y
184 ldap-encode-boolean ; 7 Boolean Y
185 nil ; 8 Certificate N
186 nil ; 9 Certificate List N
187 nil ; 10 Certificate Pair N
188 ldap-encode-country-string ; 11 Country String Y
189 ldap-encode-string ; 12 DN Y
190 nil ; 13 Data Quality Syntax Y
191 nil ; 14 Delivery Method Y
192 ldap-encode-string ; 15 Directory String Y
193 nil ; 16 DIT Content Rule Description Y
194 nil ; 17 DIT Structure Rule Description Y
195 nil ; 18 DL Submit Permission Y
196 nil ; 19 DSA Quality Syntax Y
197 nil ; 20 DSE Type Y
198 nil ; 21 Enhanced Guide Y
199 nil ; 22 Facsimile Telephone Number Y
200 nil ; 23 Fax N
201 nil ; 24 Generalized Time Y
202 nil ; 25 Guide Y
203 nil ; 26 IA5 String Y
204 number-to-string ; 27 INTEGER Y
205 nil ; 28 JPEG N
206 nil ; 29 Master And Shadow Access Points Y
207 nil ; 30 Matching Rule Description Y
208 nil ; 31 Matching Rule Use Description Y
209 nil ; 32 Mail Preference Y
210 nil ; 33 MHS OR Address Y
211 nil ; 34 Name And Optional UID Y
212 nil ; 35 Name Form Description Y
213 nil ; 36 Numeric String Y
214 nil ; 37 Object Class Description Y
215 nil ; 38 OID Y
216 nil ; 39 Other Mailbox Y
217 nil ; 40 Octet String Y
218 ldap-encode-address ; 41 Postal Address Y
219 nil ; 42 Protocol Information Y
220 nil ; 43 Presentation Address Y
221 ldap-encode-string ; 44 Printable String Y
222 nil ; 45 Subtree Specification Y
223 nil ; 46 Supplier Information Y
224 nil ; 47 Supplier Or Consumer Y
225 nil ; 48 Supplier And Consumer Y
226 nil ; 49 Supported Algorithm N
227 nil ; 50 Telephone Number Y
228 nil ; 51 Teletex Terminal Identifier Y
229 nil ; 52 Telex Number Y
230 nil ; 53 UTC Time Y
231 nil ; 54 LDAP Syntax Description Y
232 nil ; 55 Modify Rights Y
233 nil ; 56 LDAP Schema Definition Y
234 nil ; 57 LDAP Schema Description Y
235 nil ; 58 Substring Assertion Y
237 "A vector of functions used to encode LDAP attribute values.
238 The sequence of functions corresponds to the sequence of LDAP attribute syntax
239 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
240 RFC2252 section 4.3.2")
242 (defvar ldap-attribute-syntax-decoders
243 [nil ; 1 ACI Item N
244 nil ; 2 Access Point Y
245 nil ; 3 Attribute Type Description Y
246 nil ; 4 Audio N
247 nil ; 5 Binary N
248 nil ; 6 Bit String Y
249 ldap-decode-boolean ; 7 Boolean Y
250 nil ; 8 Certificate N
251 nil ; 9 Certificate List N
252 nil ; 10 Certificate Pair N
253 ldap-decode-string ; 11 Country String Y
254 ldap-decode-string ; 12 DN Y
255 nil ; 13 Data Quality Syntax Y
256 nil ; 14 Delivery Method Y
257 ldap-decode-string ; 15 Directory String Y
258 nil ; 16 DIT Content Rule Description Y
259 nil ; 17 DIT Structure Rule Description Y
260 nil ; 18 DL Submit Permission Y
261 nil ; 19 DSA Quality Syntax Y
262 nil ; 20 DSE Type Y
263 nil ; 21 Enhanced Guide Y
264 nil ; 22 Facsimile Telephone Number Y
265 nil ; 23 Fax N
266 nil ; 24 Generalized Time Y
267 nil ; 25 Guide Y
268 nil ; 26 IA5 String Y
269 string-to-number ; 27 INTEGER Y
270 nil ; 28 JPEG N
271 nil ; 29 Master And Shadow Access Points Y
272 nil ; 30 Matching Rule Description Y
273 nil ; 31 Matching Rule Use Description Y
274 nil ; 32 Mail Preference Y
275 nil ; 33 MHS OR Address Y
276 nil ; 34 Name And Optional UID Y
277 nil ; 35 Name Form Description Y
278 nil ; 36 Numeric String Y
279 nil ; 37 Object Class Description Y
280 nil ; 38 OID Y
281 nil ; 39 Other Mailbox Y
282 nil ; 40 Octet String Y
283 ldap-decode-address ; 41 Postal Address Y
284 nil ; 42 Protocol Information Y
285 nil ; 43 Presentation Address Y
286 ldap-decode-string ; 44 Printable String Y
287 nil ; 45 Subtree Specification Y
288 nil ; 46 Supplier Information Y
289 nil ; 47 Supplier Or Consumer Y
290 nil ; 48 Supplier And Consumer Y
291 nil ; 49 Supported Algorithm N
292 nil ; 50 Telephone Number Y
293 nil ; 51 Teletex Terminal Identifier Y
294 nil ; 52 Telex Number Y
295 nil ; 53 UTC Time Y
296 nil ; 54 LDAP Syntax Description Y
297 nil ; 55 Modify Rights Y
298 nil ; 56 LDAP Schema Definition Y
299 nil ; 57 LDAP Schema Description Y
300 nil ; 58 Substring Assertion Y
302 "A vector of functions used to decode LDAP attribute values.
303 The sequence of functions corresponds to the sequence of LDAP attribute syntax
304 object identifiers of the form 1.3.6.1.4.1.1466.1115.121.1.* as defined in
305 RFC2252 section 4.3.2")
308 (defvar ldap-attribute-syntaxes-alist
309 '((createtimestamp . 24)
310 (modifytimestamp . 24)
311 (creatorsname . 12)
312 (modifiersname . 12)
313 (subschemasubentry . 12)
314 (attributetypes . 3)
315 (objectclasses . 37)
316 (matchingrules . 30)
317 (matchingruleuse . 31)
318 (namingcontexts . 12)
319 (altserver . 26)
320 (supportedextension . 38)
321 (supportedcontrol . 38)
322 (supportedsaslmechanisms . 15)
323 (supportedldapversion . 27)
324 (ldapsyntaxes . 16)
325 (ditstructurerules . 17)
326 (nameforms . 35)
327 (ditcontentrules . 16)
328 (objectclass . 38)
329 (aliasedobjectname . 12)
330 (cn . 15)
331 (sn . 15)
332 (serialnumber . 44)
333 (c . 15)
334 (l . 15)
335 (st . 15)
336 (street . 15)
337 (o . 15)
338 (ou . 15)
339 (title . 15)
340 (description . 15)
341 (searchguide . 25)
342 (businesscategory . 15)
343 (postaladdress . 41)
344 (postalcode . 15)
345 (postofficebox . 15)
346 (physicaldeliveryofficename . 15)
347 (telephonenumber . 50)
348 (telexnumber . 52)
349 (telexterminalidentifier . 51)
350 (facsimiletelephonenumber . 22)
351 (x121address . 36)
352 (internationalisdnnumber . 36)
353 (registeredaddress . 41)
354 (destinationindicator . 44)
355 (preferreddeliverymethod . 14)
356 (presentationaddress . 43)
357 (supportedapplicationcontext . 38)
358 (member . 12)
359 (owner . 12)
360 (roleoccupant . 12)
361 (seealso . 12)
362 (userpassword . 40)
363 (usercertificate . 8)
364 (cacertificate . 8)
365 (authorityrevocationlist . 9)
366 (certificaterevocationlist . 9)
367 (crosscertificatepair . 10)
368 (name . 15)
369 (givenname . 15)
370 (initials . 15)
371 (generationqualifier . 15)
372 (x500uniqueidentifier . 6)
373 (dnqualifier . 44)
374 (enhancedsearchguide . 21)
375 (protocolinformation . 42)
376 (distinguishedname . 12)
377 (uniquemember . 34)
378 (houseidentifier . 15)
379 (supportedalgorithms . 49)
380 (deltarevocationlist . 9)
381 (dmdname . 15))
382 "A map of LDAP attribute names to their type object id minor number.
383 This table is built from RFC2252 Section 5 and RFC2256 Section 5")
386 ;; Coding/decoding functions
388 (defun ldap-encode-boolean (bool)
389 (if bool
390 "TRUE"
391 "FALSE"))
393 (defun ldap-decode-boolean (str)
394 (cond
395 ((string-equal str "TRUE")
397 ((string-equal str "FALSE")
398 nil)
400 (error "Wrong LDAP boolean string: %s" str))))
402 (defun ldap-encode-country-string (str)
403 ;; We should do something useful here...
404 (if (not (= 2 (length str)))
405 (error "Invalid country string: %s" str)))
407 (defun ldap-decode-string (str)
408 (decode-coding-string str ldap-coding-system))
410 (defun ldap-encode-string (str)
411 (encode-coding-string str ldap-coding-system))
413 (defun ldap-decode-address (str)
414 (mapconcat 'ldap-decode-string
415 (split-string str "\\$")
416 "\n"))
418 (defun ldap-encode-address (str)
419 (mapconcat 'ldap-encode-string
420 (split-string str "\n")
421 "$"))
424 ;; LDAP protocol functions
426 (defun ldap-get-host-parameter (host parameter)
427 "Get the value of PARAMETER for HOST in `ldap-host-parameters-alist'."
428 (plist-get (cdr (assoc host ldap-host-parameters-alist))
429 parameter))
431 (defun ldap-decode-attribute (attr)
432 "Decode the attribute/value pair ATTR according to LDAP rules.
433 The attribute name is looked up in `ldap-attribute-syntaxes-alist'
434 and the corresponding decoder is then retrieved from
435 `ldap-attribute-syntax-decoders' and applied on the value(s)."
436 (let* ((name (car attr))
437 (values (cdr attr))
438 (syntax-id (cdr (assq (intern (downcase name))
439 ldap-attribute-syntaxes-alist)))
440 decoder)
441 (if syntax-id
442 (setq decoder (aref ldap-attribute-syntax-decoders
443 (1- syntax-id)))
444 (setq decoder ldap-default-attribute-decoder))
445 (if decoder
446 (cons name (mapcar decoder values))
447 attr)))
449 (defun ldap-search (filter &optional host attributes attrsonly withdn)
450 "Perform an LDAP search.
451 FILTER is the search filter in RFC1558 syntax.
452 HOST is the LDAP host on which to perform the search.
453 ATTRIBUTES are the specific attributes to retrieve, nil means
454 retrieve all.
455 ATTRSONLY, if non-nil, retrieves the attributes only, without
456 the associated values.
457 If WITHDN is non-nil, each entry in the result will be prepended with
458 its distinguished name WITHDN.
459 Additional search parameters can be specified through
460 `ldap-host-parameters-alist', which see."
461 (interactive "sFilter:")
462 (or host
463 (setq host ldap-default-host)
464 (error "No LDAP host specified"))
465 (let ((host-plist (cdr (assoc host ldap-host-parameters-alist)))
466 result)
467 (setq result (ldap-search-internal (list* 'host host
468 'filter filter
469 'attributes attributes
470 'attrsonly attrsonly
471 'withdn withdn
472 host-plist)))
473 (if ldap-ignore-attribute-codings
474 result
475 (mapcar (lambda (record)
476 (mapcar 'ldap-decode-attribute record))
477 result))))
480 (defun ldap-search-internal (search-plist)
481 "Perform a search on a LDAP server.
482 SEARCH-PLIST is a property list describing the search request.
483 Valid keys in that list are:
484 `host' is a string naming one or more (blank-separated) LDAP servers to
485 to try to connect to. Each host name may optionally be of the form HOST:PORT.
486 `filter' is a filter string for the search as described in RFC 1558.
487 `attributes' is a list of strings indicating which attributes to retrieve
488 for each matching entry. If nil, return all available attributes.
489 `attrsonly', if non-nil, indicates that only attributes are retrieved,
490 not their associated values.
491 `auth' is one of the symbols `simple', `krbv41' or `krbv42'.
492 `base' is the base for the search as described in RFC 1779.
493 `scope' is one of the three symbols `sub', `base' or `one'.
494 `binddn' is the distinguished name of the user to bind as (in RFC 1779 syntax).
495 `auth' is one of the symbols `simple', `krbv41' or `krbv42'
496 `passwd' is the password to use for simple authentication.
497 `deref' is one of the symbols `never', `always', `search' or `find'.
498 `timelimit' is the timeout limit for the connection in seconds.
499 `sizelimit' is the maximum number of matches to return.
500 `withdn' if non-nil each entry in the result will be prepended with
501 its distinguished name DN.
502 The function returns a list of matching entries. Each entry is itself
503 an alist of attribute/value pairs."
504 (let ((buf (get-buffer-create " *ldap-search*"))
505 (bufval (get-buffer-create " *ldap-value*"))
506 (host (or (plist-get search-plist 'host)
507 ldap-default-host))
508 (filter (plist-get search-plist 'filter))
509 (attributes (plist-get search-plist 'attributes))
510 (attrsonly (plist-get search-plist 'attrsonly))
511 (base (or (plist-get search-plist 'base)
512 ldap-default-base))
513 (scope (plist-get search-plist 'scope))
514 (binddn (plist-get search-plist 'binddn))
515 (auth (plist-get search-plist 'auth))
516 (passwd (plist-get search-plist 'passwd))
517 (deref (plist-get search-plist 'deref))
518 (timelimit (plist-get search-plist 'timelimit))
519 (sizelimit (plist-get search-plist 'sizelimit))
520 (withdn (plist-get search-plist 'withdn))
521 (numres 0)
522 arglist dn name value record result)
523 (if (or (null filter)
524 (equal "" filter))
525 (error "No search filter"))
526 (setq filter (cons filter attributes))
527 (with-current-buffer buf
528 (erase-buffer)
529 (if (and host
530 (not (equal "" host)))
531 (setq arglist (nconc arglist (list (format "-h%s" host)))))
532 (if (and attrsonly
533 (not (equal "" attrsonly)))
534 (setq arglist (nconc arglist (list "-A"))))
535 (if (and base
536 (not (equal "" base)))
537 (setq arglist (nconc arglist (list (format "-b%s" base)))))
538 (if (and scope
539 (not (equal "" scope)))
540 (setq arglist (nconc arglist (list (format "-s%s" scope)))))
541 (if (and binddn
542 (not (equal "" binddn)))
543 (setq arglist (nconc arglist (list (format "-D%s" binddn)))))
544 (if (and auth
545 (equal 'simple auth))
546 (setq arglist (nconc arglist (list "-x"))))
547 (if (and passwd
548 (not (equal "" passwd)))
549 (setq arglist (nconc arglist (list (format "-w%s" passwd)))))
550 (if (and deref
551 (not (equal "" deref)))
552 (setq arglist (nconc arglist (list (format "-a%s" deref)))))
553 (if (and timelimit
554 (not (equal "" timelimit)))
555 (setq arglist (nconc arglist (list (format "-l%s" timelimit)))))
556 (if (and sizelimit
557 (not (equal "" sizelimit)))
558 (setq arglist (nconc arglist (list (format "-z%s" sizelimit)))))
559 (eval `(call-process ldap-ldapsearch-prog
563 ,@arglist
564 ,@ldap-ldapsearch-args
565 ,@filter))
566 (insert "\n")
567 (goto-char (point-min))
569 (while (re-search-forward "[\t\n\f]+ " nil t)
570 (replace-match "" nil nil))
571 (goto-char (point-min))
573 (if (looking-at "usage")
574 (error "Incorrect ldapsearch invocation")
575 (message "Parsing results... ")
576 ;; Skip error message when retrieving attribute list
577 (if (looking-at "Size limit exceeded")
578 (forward-line 1))
579 (while (progn
580 (skip-chars-forward " \t\n")
581 (not (eobp)))
582 (setq dn (buffer-substring (point) (save-excursion
583 (end-of-line)
584 (point))))
585 (forward-line 1)
586 (while (looking-at "^\\([A-Za-z][-A-Za-z0-9]*\
587 \\|[0-9]+\\(?:\\.[0-9]+\\)*\\)\\(;[-A-Za-z0-9]+\\)*[=:\t ]+\
588 \\(<[\t ]*file://\\)\\(.*\\)$")
589 (setq name (match-string 1)
590 value (match-string 4))
591 ;; Need to handle file:///D:/... as generated by OpenLDAP
592 ;; on DOS/Windows as local files.
593 (if (and (memq system-type '(windows-nt ms-dos))
594 (eq (string-match "/\\(.:.*\\)$" value) 0))
595 (setq value (match-string 1 value)))
596 ;; Do not try to open non-existent files
597 (if (equal value "")
598 (setq value " ")
599 (with-current-buffer bufval
600 (erase-buffer)
601 (set-buffer-multibyte nil)
602 (insert-file-contents-literally value)
603 (delete-file value)
604 (setq value (buffer-string))))
605 (setq record (cons (list name value)
606 record))
607 (forward-line 1))
608 (push (if withdn
609 (cons dn (nreverse record))
610 (nreverse record)) result)
611 (setq record nil)
612 (skip-chars-forward " \t\n")
613 (message "Parsing results... %d" numres)
614 (1+ numres))
615 (message "Parsing results... done")
616 (nreverse result)))))
618 (provide 'ldap)
620 ;; arch-tag: 47913a76-6155-42e6-ac58-6d28b5d50eb0
621 ;;; ldap.el ends here