1 ;;; imap.el --- imap library
2 ;; Copyright (C) 1998,1999 Free Software Foundation, Inc.
4 ;; Author: Simon Josefsson <jas@pdc.kth.se>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software; you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation; either version 2, or (at your option)
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs; see the file COPYING. If not, write to the
21 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 ;; Boston, MA 02111-1307, USA.
26 ;; imap.el is a elisp library providing an interface for talking to
29 ;; imap.el is roughly divided in two parts, one that parses IMAP
30 ;; responses from the server and storing data into buffer-local
31 ;; variables, and one for utility functions which send commands to
32 ;; server, waits for an answer, and return information. The latter
33 ;; part is layered on top of the previous.
35 ;; The imap.el API consist of the following functions, other functions
36 ;; in this file should not be called directly and the result of doing
37 ;; so are at best undefined.
41 ;; imap-open, imap-opened, imap-authenticate, imap-close,
42 ;; imap-capability, imap-namespace, imap-error-text
46 ;; imap-mailbox-get, imap-mailbox-map, imap-current-mailbox,
47 ;; imap-current-mailbox-p, imap-search, imap-mailbox-select,
48 ;; imap-mailbox-examine, imap-mailbox-unselect, imap-mailbox-expunge
49 ;; imap-mailbox-close, imap-mailbox-create, imap-mailbox-delete
50 ;; imap-mailbox-rename, imap-mailbox-lsub, imap-mailbox-list
51 ;; imap-mailbox-subscribe, imap-mailbox-unsubscribe, imap-mailbox-status
52 ;; imap-mailbox-acl-get, imap-mailbox-acl-set, imap-mailbox-acl-delete
56 ;; imap-fetch-asynch, imap-fetch,
57 ;; imap-current-message, imap-list-to-message-set,
58 ;; imap-message-get, imap-message-map
59 ;; imap-message-envelope-date, imap-message-envelope-subject,
60 ;; imap-message-envelope-from, imap-message-envelope-sender,
61 ;; imap-message-envelope-reply-to, imap-message-envelope-to,
62 ;; imap-message-envelope-cc, imap-message-envelope-bcc
63 ;; imap-message-envelope-in-reply-to, imap-message-envelope-message-id
64 ;; imap-message-body, imap-message-flag-permanent-p
65 ;; imap-message-flags-set, imap-message-flags-del
66 ;; imap-message-flags-add, imap-message-copyuid
67 ;; imap-message-copy, imap-message-appenduid
68 ;; imap-message-append, imap-envelope-from
71 ;; It is my hope that theese commands should be pretty self
72 ;; explanatory for someone that know IMAP. All functions have
73 ;; additional documentation on how to invoke them.
75 ;; imap.el support RFC1730/2060 (IMAP4/IMAP4rev1), implemented IMAP
76 ;; extensions are RFC2195 (CRAM-MD5), RFC2086 (ACL), RFC2342
77 ;; (NAMESPACE), RFC2359 (UIDPLUS), and the kerberos V4 part of RFC1731
78 ;; (with use of external program `imtest'). It also take advantage
79 ;; the UNSELECT extension in Cyrus IMAPD.
81 ;; Without the work of John McClary Prevost and Jim Radford this library
82 ;; would not have seen the light of day. Many thanks.
84 ;; This is a transcript of short interactive session for demonstration
87 ;; (imap-open "my.mail.server")
88 ;; => " *imap* my.mail.server:0"
90 ;; The rest are invoked with current buffer as the buffer returned by
91 ;; `imap-open'. It is possible to do all without this, but it would
92 ;; look ugly here since `buffer' is always the last argument for all
93 ;; imap.el API functions.
95 ;; (imap-authenticate "myusername" "mypassword")
98 ;; (imap-mailbox-lsub "*")
99 ;; => ("INBOX.sentmail" "INBOX.private" "INBOX.draft" "INBOX.spam")
101 ;; (imap-mailbox-list "INBOX.n%")
102 ;; => ("INBOX.namedroppers" "INBOX.nnimap" "INBOX.ntbugtraq")
104 ;; (imap-mailbox-select "INBOX.nnimap")
107 ;; (imap-mailbox-get 'exists)
110 ;; (imap-mailbox-get 'uidvalidity)
113 ;; (imap-search "FLAGGED SINCE 18-DEC-98")
116 ;; (imap-fetch 235 "RFC822.PEEK" 'RFC822)
117 ;; => "X-Sieve: cmu-sieve 1.3^M\nX-Username: <jas@pdc.kth.se>^M\r...."
121 ;; o Parse UIDs as strings? We need to overcome the 28 bit limit somehow.
122 ;; o Don't use `read' at all (important places already fixed)
123 ;; o Accept list of articles instead of message set string in most
124 ;; imap-message-* functions.
125 ;; o Cyrus IMAPd 1.6.x `imtest' support in the imtest wrapper
129 ;; - this is unreleased software
134 (eval-when-compile (require 'cl))
136 (autoload 'open-ssl-stream "ssl")
137 (autoload 'base64-decode-string "base64")
138 (autoload 'base64-encode-string "base64")
139 (autoload 'rfc2104-hash "rfc2104")
140 (autoload 'md5 "md5")
141 (autoload 'utf7-encode "utf7")
142 (autoload 'utf7-decode "utf7")
143 (autoload 'format-spec "format-spec")
144 (autoload 'format-spec-make "format-spec"))
148 (defvar imap-imtest-program "imtest -kp %s %p"
149 "How to call program for Kerberos 4 authentication.
150 %s is replaced with server and %p with port to connect to. The
151 program should accept IMAP commands on stdin and return responses to
154 (defvar imap-ssl-program '("openssl s_client -ssl3 -connect %s:%p"
155 "openssl s_client -ssl2 -connect %s:%p"
156 "s_client -ssl3 -connect %s:%p"
157 "s_client -ssl2 -connect %s:%p")
158 "A string, or list of strings, containing commands for SSL connections.
159 Within a string, %s is replaced with the server address and %p with
160 port number on server. The program should accept IMAP commands on
161 stdin and return responses to stdout.")
163 (defvar imap-default-user (user-login-name)
164 "Default username to use.")
166 (defvar imap-error nil
167 "Error codes from the last command.")
169 ;; Various variables.
171 (defvar imap-fetch-data-hook nil
172 "Hooks called after receiving each FETCH response.")
174 (defvar imap-streams '(kerberos4 ssl network)
175 "Priority of streams to consider when opening connection to server.")
177 (defvar imap-stream-alist
178 '((kerberos4 imap-kerberos4s-p imap-kerberos4-open)
179 (ssl imap-ssl-p imap-ssl-open)
180 (network imap-network-p imap-network-open))
181 "Definition of network streams.
185 NAME names the stream, CHECK is a function returning non-nil if the
186 server support the stream and OPEN is a function for opening the
189 (defvar imap-authenticators '(kerberos4 cram-md5 login anonymous)
190 "Priority of authenticators to consider when authenticating to server.")
192 (defvar imap-authenticator-alist
193 '((kerberos4 imap-kerberos4a-p imap-kerberos4-auth)
194 (cram-md5 imap-cram-md5-p imap-cram-md5-auth)
195 (login imap-login-p imap-login-auth)
196 (anonymous imap-anonymous-p imap-anonymous-auth))
197 "Definition of authenticators.
199 (NAME CHECK AUTHENTICATE)
201 NAME names the authenticator. CHECK is a function returning non-nil if
202 the server support the authenticator and AUTHENTICATE is a function
203 for doing the actuall authentification.")
205 (defvar imap-utf7-p nil
206 "If non-nil, do utf7 encoding/decoding of mailbox names.
207 Since the UTF7 decoding currently only decodes into ISO-8859-1
208 characters, you may disable this decoding if you need to access UTF7
209 encoded mailboxes which doesn't translate into ISO-8859-1.")
211 ;; Internal constants. Change theese and die.
213 (defconst imap-default-port 143)
214 (defconst imap-default-ssl-port 993)
215 (defconst imap-default-stream 'network)
216 (defconst imap-coding-system-for-read 'binary)
217 (defconst imap-coding-system-for-write 'binary)
218 (defconst imap-local-variables '(imap-server
227 imap-current-target-mailbox
238 ;; Internal variables.
240 (defvar imap-stream nil)
241 (defvar imap-auth nil)
242 (defvar imap-server nil)
243 (defvar imap-port nil)
244 (defvar imap-username nil)
245 (defvar imap-password nil)
246 (defvar imap-state 'closed
248 Valid states are `closed', `initial', `nonauth', `auth', `selected'
251 (defvar imap-server-eol "\r\n"
252 "The EOL string sent from the server.")
254 (defvar imap-client-eol "\r\n"
255 "The EOL string we send to the server.")
257 (defvar imap-current-mailbox nil
258 "Current mailbox name.")
260 (defvar imap-current-target-mailbox nil
261 "Current target mailbox for COPY and APPEND commands.")
263 (defvar imap-mailbox-data nil
264 "Obarray with mailbox data.")
266 (defvar imap-mailbox-prime 997
267 "Length of imap-mailbox-data.")
269 (defvar imap-current-message nil
270 "Current message number.")
272 (defvar imap-message-data nil
273 "Obarray with message data.")
275 (defvar imap-message-prime 997
276 "Length of imap-message-data.")
278 (defvar imap-capability nil
279 "Capability for server.")
281 (defvar imap-namespace nil
282 "Namespace for current server.")
284 (defvar imap-reached-tag 0
285 "Lower limit on command tags that have been parsed.")
287 (defvar imap-failed-tags nil
288 "Alist of tags that failed.
289 Each element is a list with four elements; tag (a integer), response
290 state (a symbol, `OK', `NO' or `BAD'), response code (a string), and
291 human readable response text (a string).")
294 "Command tag number.")
296 (defvar imap-process nil
299 (defvar imap-continuation nil
300 "Non-nil indicates that the server emitted a continuation request.
301 The actually value is really the text on the continuation line.")
304 "Imap session trace.")
306 (defvar imap-debug nil ;"*imap-debug*"
307 "Random debug spew.")
310 ;; Utility functions:
312 (defsubst imap-disable-multibyte ()
313 "Enable multibyte in the current buffer."
314 (when (fboundp 'set-buffer-multibyte)
315 (set-buffer-multibyte nil)))
317 (defun imap-read-passwd (prompt &rest args)
318 "Read a password using PROMPT.
319 If ARGS, PROMPT is used as an argument to `format'."
320 (let ((prompt (if args
321 (apply 'format prompt args)
323 (funcall (if (or (fboundp 'read-passwd)
325 (fboundp 'read-passwd))
326 (and (load "passwd" t)
327 (fboundp 'read-passwd)))
329 (autoload 'ange-ftp-read-passwd "ange-ftp")
330 'ange-ftp-read-passwd)
333 (defsubst imap-utf7-encode (string)
337 (utf7-encode string t)
339 "imap: Could not UTF7 encode `%s', using it unencoded..."
344 (defsubst imap-utf7-decode (string)
348 (utf7-decode string t)
350 "imap: Could not UTF7 decode `%s', using it undecoded..."
355 (defsubst imap-ok-p (status)
358 (setq imap-error status)
361 (defun imap-error-text (&optional buffer)
362 (with-current-buffer (or buffer (current-buffer))
363 (nth 3 (car imap-failed-tags))))
366 ;; Server functions; stream stuff:
368 (defun imap-kerberos4s-p (buffer)
369 (imap-capability 'AUTH=KERBEROS_V4 buffer))
371 (defun imap-kerberos4-open (name buffer server port)
372 (message "Opening Kerberized IMAP connection...")
373 (let* ((port (or port imap-default-port))
374 (coding-system-for-read imap-coding-system-for-read)
375 (coding-system-for-write imap-coding-system-for-write)
376 (process (start-process
377 name buffer shell-file-name shell-command-switch
380 (format-spec-make ?s server ?p (number-to-string port))))))
382 (with-current-buffer buffer
383 (setq imap-client-eol "\n")
384 ;; Result of authentication is a string: __Full privacy protection__
385 (while (and (memq (process-status process) '(open run))
386 (goto-char (point-min))
387 (not (and (imap-parse-greeting)
388 (re-search-forward "__\\(.*\\)__\n" nil t))))
389 (accept-process-output process 1)
392 (with-current-buffer (get-buffer-create imap-log)
393 (imap-disable-multibyte)
394 (buffer-disable-undo)
395 (goto-char (point-max))
396 (insert-buffer-substring buffer)))
397 (let ((response (match-string 1)))
399 (message "Kerberized IMAP connection: %s" response)
400 (if (and response (let ((case-fold-search nil))
401 (not (string-match "failed" response))))
403 (if (memq (process-status process) '(open run))
404 (imap-send-command-wait "LOGOUT"))
405 (delete-process process)
408 (defun imap-ssl-p (buffer)
411 (defun imap-ssl-open (name buffer server port)
412 "Open a SSL connection to server."
413 (let ((cmds (if (listp imap-ssl-program) imap-ssl-program
414 (list imap-ssl-program)))
416 (while (and (not done) (setq cmd (pop cmds)))
417 (message "imap: Opening SSL connection with `%s'..." cmd)
418 (let* ((port (or port imap-default-ssl-port))
419 (coding-system-for-read imap-coding-system-for-read)
420 (coding-system-for-write imap-coding-system-for-write)
421 (ssl-program-name shell-file-name)
422 (ssl-program-arguments
423 (list shell-command-switch
424 (format-spec cmd (format-spec-make
426 ?p (number-to-string port)))))
428 (when (setq process (ignore-errors (open-ssl-stream
429 name buffer server port)))
430 (with-current-buffer buffer
431 (goto-char (point-min))
432 (while (and (memq (process-status process) '(open run))
433 (goto-char (point-max))
435 (not (imap-parse-greeting)))
436 (accept-process-output process 1)
439 (with-current-buffer (get-buffer-create imap-log)
440 (imap-disable-multibyte)
441 (buffer-disable-undo)
442 (goto-char (point-max))
443 (insert-buffer-substring buffer)))
445 (when (memq (process-status process) '(open run))
446 (setq done process))))))
449 (message "imap: Opening SSL connection with `%s'...done" cmd)
451 (message "imap: Failed opening SSL connection")
454 (defun imap-network-p (buffer)
457 (defun imap-network-open (name buffer server port)
458 (let* ((port (or port imap-default-port))
459 (coding-system-for-read imap-coding-system-for-read)
460 (coding-system-for-write imap-coding-system-for-write)
461 (process (open-network-stream name buffer server port)))
463 (while (and (memq (process-status process) '(open run))
464 (goto-char (point-min))
465 (not (imap-parse-greeting)))
466 (accept-process-output process 1)
469 (with-current-buffer (get-buffer-create imap-log)
470 (imap-disable-multibyte)
471 (buffer-disable-undo)
472 (goto-char (point-max))
473 (insert-buffer-substring buffer)))
474 (when (memq (process-status process) '(open run))
477 ;; Server functions; authenticator stuff:
479 (defun imap-interactive-login (buffer loginfunc)
480 "Login to server in BUFFER.
481 LOGINFUNC is passed a username and a password, it should return t if
482 it where sucessful authenticating itself to the server, nil otherwise.
483 Returns t if login was successful, nil otherwise."
484 (with-current-buffer buffer
485 (make-variable-buffer-local 'imap-username)
486 (make-variable-buffer-local 'imap-password)
487 (let (user passwd ret)
488 ;; (condition-case ()
489 (while (or (not user) (not passwd))
490 (setq user (or imap-username
491 (read-from-minibuffer
492 (concat "IMAP username for " imap-server ": ")
493 (or user imap-default-user))))
494 (setq passwd (or imap-password
496 (concat "IMAP password for " user "@"
498 (when (and user passwd)
499 (if (funcall loginfunc user passwd)
503 (if (and (not imap-password)
504 (y-or-n-p "Store password for this session? "))
505 (setq imap-password passwd)))
506 (message "Login failed...")
509 ;; (quit (with-current-buffer buffer
512 ;; (error (with-current-buffer buffer
517 (defun imap-kerberos4a-p (buffer)
518 (imap-capability 'AUTH=KERBEROS_V4 buffer))
520 (defun imap-kerberos4-auth (buffer)
521 (eq imap-stream 'kerberos4))
523 (defun imap-cram-md5-p (buffer)
524 (imap-capability 'AUTH=CRAM-MD5 buffer))
526 (defun imap-cram-md5-auth (buffer)
527 "Login to server using the AUTH CRAM-MD5 method."
528 (imap-interactive-login
530 (lambda (user passwd)
532 (imap-send-command-wait
534 "AUTHENTICATE CRAM-MD5"
536 (let* ((decoded (base64-decode-string challenge))
537 (hash (rfc2104-hash 'md5 64 16 passwd decoded))
538 (response (concat user " " hash))
539 (encoded (base64-encode-string response)))
542 (defun imap-login-p (buffer)
543 (not (imap-capability 'X-LOGIN-CMD-DISABLED buffer)))
545 (defun imap-login-auth (buffer)
546 "Login to server using the LOGIN command."
547 (imap-interactive-login buffer
548 (lambda (user passwd)
549 (imap-ok-p (imap-send-command-wait
550 (concat "LOGIN \"" user "\" \""
553 (defun imap-anonymous-p (buffer)
556 (defun imap-anonymous-auth (buffer)
557 (with-current-buffer buffer
558 (imap-ok-p (imap-send-command-wait
559 (concat "LOGIN anonymous \"" (concat (user-login-name) "@"
560 (system-name)) "\"")))))
564 (defun imap-open-1 (buffer)
565 (with-current-buffer buffer
567 (setq imap-current-mailbox nil
568 imap-current-message nil
570 imap-process (condition-case ()
571 (funcall (nth 2 (assq imap-stream
573 "imap" buffer imap-server imap-port)
576 (set-process-filter imap-process 'imap-arrival-filter)
577 (set-process-sentinel imap-process 'imap-sentinel)
578 (while (and (eq imap-state 'initial)
579 (memq (process-status imap-process) '(open run)))
580 (message "Waiting for response from %s..." imap-server)
581 (accept-process-output imap-process 1))
582 (message "Waiting for response from %s...done" imap-server)
583 (and (memq (process-status imap-process) '(open run))
586 (defun imap-open (server &optional port stream auth buffer)
587 "Open a IMAP connection to host SERVER at PORT returning a buffer.
588 If PORT is unspecified, a default value is used (143 except
589 for SSL which use 993).
590 STREAM indicates the stream to use, see `imap-streams' for available
591 streams. If nil, it choices the best stream the server is capable of.
592 AUTH indicates authenticator to use, see `imap-authenticators' for
593 available authenticators. If nil, it choices the best stream the
594 server is capable of.
595 BUFFER can be a buffer or a name of a buffer, which is created if
596 necessery. If nil, the buffer name is generated."
597 (setq buffer (or buffer (format " *imap* %s:%d" server (or port 0))))
598 (with-current-buffer (get-buffer-create buffer)
599 (if (imap-opened buffer)
601 (mapcar 'make-variable-buffer-local imap-local-variables)
602 (imap-disable-multibyte)
603 (buffer-disable-undo)
604 (setq imap-server (or server imap-server))
605 (setq imap-port (or port imap-port))
606 (setq imap-auth (or auth imap-auth))
607 (setq imap-stream (or stream imap-stream))
608 (when (let ((imap-stream (or imap-stream imap-default-stream)))
609 (imap-open-1 buffer))
611 (let (stream-changed)
612 (when (null imap-stream)
613 (let ((streams imap-streams))
614 (while (setq stream (pop streams))
615 (if (funcall (nth 1 (assq stream imap-stream-alist)) buffer)
616 (setq stream-changed (not (eq (or imap-stream