cgit.sxemacs.org Git - gnus/blob - lisp/proto-stream.el

   1 ;;; proto-stream.el --- negotiating TLS, STARTTLS and other connections
   2
   3 ;; Copyright (C) 2010-2011 Free Software Foundation, Inc.
   4
   5 ;; Author: Lars Magne Ingebrigtsen <larsi@gnus.org>
   6 ;; Keywords: network
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; This library is meant to provide the glue between modules that want
  26 ;; to establish a network connection to a server for protocols such as
  27 ;; IMAP, NNTP, SMTP and POP3.
  28
  29 ;; The main problem is that there's more than a couple of interfaces
  30 ;; towards doing this.  You have normal, plain connections, which are
  31 ;; no trouble at all, but you also have TLS/SSL connections, and you
  32 ;; have STARTTLS.  Negotiating this for each protocol can be rather
  33 ;; tedious, so this library provides a single entry point, and hides
  34 ;; much of the ugliness.
  35
  36 ;; Usage example:
  37
  38 ;; (open-protocol-stream
  39 ;;  "*nnimap*" buffer address port
  40 ;;  :type 'network
  41 ;;  :capability-command "1 CAPABILITY\r\n"
  42 ;;  :success " OK "
  43 ;;  :starttls-function
  44 ;;  (lambda (capabilities)
  45 ;;    (if (not (string-match "STARTTLS" capabilities))
  46 ;;        nil
  47 ;;      "1 STARTTLS\r\n")))
  48
  49 ;;; Code:
  50
  51 (require 'tls)
  52 (require 'starttls)
  53
  54 (declare-function gnutls-negotiate "gnutls"
  55                   (proc type host &optional priority-string trustfiles keyfiles
  56                         verify-flags verify-error verify-hostname-error))
  57
  58 ;;;###autoload
  59 (defun open-protocol-stream (name buffer host service &rest parameters)
  60   "Open a network stream to HOST, possibly with encryption.
  61 Normally, return a network process object; with a non-nil
  62 :return-list parameter, return a list instead (see below).
  63
  64 The first four parameters, NAME, BUFFER, HOST, and SERVICE, have
  65 the same meanings as in `open-network-stream'.  The remaining
  66 PARAMETERS should be a sequence of keywords and values:
  67
  68 :type specifies the connection type, one of the following:
  69   nil or `network'
  70              -- Begin with an ordinary network connection, and if
  71                 the parameters :success and :capability-command
  72                 are also supplied, try to upgrade to an encrypted
  73                 connection via STARTTLS.  Even if that
  74                 fails (e.g. if HOST does not support TLS), retain
  75                 an unencrypted connection.
  76   `plain'    -- An ordinary, unencrypted network connection.
  77   `starttls' -- Begin with an ordinary connection, and try
  78                 upgrading via STARTTLS.  If that fails for any
  79                 reason, drop the connection; in that case the
  80                 returned object is a killed process.
  81   `tls'      -- A TLS connection.
  82   `ssl'      -- Equivalent to `tls'.
  83   `shell'    -- A shell connection.
  84
  85 :return-list specifies this function's return value.
  86   If omitted or nil, return a process object.  A non-nil means to
  87   return (PROC . PROPS), where PROC is a process object and PROPS
  88   is a plist of connection properties, with these keywords:
  89    :greeting -- the greeting returned by HOST (a string), or nil.
  90    :capabilities -- a string representing HOST's capabilities,
  91                     or nil if none could be found.
  92    :type -- the resulting connection type; `plain' (unencrypted)
  93             or `tls' (TLS-encrypted).
  94
  95 :end-of-command specifies a regexp matching the end of a command.
  96   If non-nil, it defaults to \"\\n\".
  97
  98 :success specifies a regexp matching a message indicating a
  99   successful STARTTLS negotiation.  For instance, the default
 100   should be \"^3\" for an NNTP connection.
 101
 102 :capability-command specifies a command used to query the HOST
 103   for its capabilities.  For instance, for IMAP this should be
 104   \"1 CAPABILITY\\r\\n\".
 105
 106 :starttls-function specifies a function for handling STARTTLS.
 107   This function should take one parameter, the response to the
 108   capability command, and should return the command to switch on
 109   STARTTLS if the server supports STARTTLS, and nil otherwise."
 110   (let ((type (plist-get parameters :type))
 111         (return-list (plist-get parameters :return-list)))
 112     (if (and (not return-list)
 113              (or (eq type 'plain)
 114                  (and (memq type '(nil network))
 115                       (not (and (plist-get parameters :success)
 116                                 (plist-get parameters :capability-command))))))
 117         ;; The simplest case is equivalent to `open-network-stream'.
 118         (open-network-stream name buffer host service)
 119       ;; For everything else, refer to proto-stream-open-*.
 120       (unless (plist-get parameters :end-of-command)
 121         (setq parameters (append '(:end-of-command "\r\n") parameters)))
 122       (let* ((connection-function
 123               (cond
 124                ((eq type 'plain) 'proto-stream-open-plain)
 125                ((memq type '(nil network starttls))
 126                 'proto-stream-open-starttls)
 127                ((memq type '(tls ssl)) 'proto-stream-open-tls)
 128                ((eq type 'shell) 'proto-stream-open-shell)
 129                (t (error "Invalid connection type %s" type))))
 130              (result (funcall connection-function
 131                               name buffer host service parameters)))
 132         (if return-list
 133             (list (car result)
 134                   :greeting     (nth 1 result)
 135                   :capabilities (nth 2 result)
 136                   :type         (nth 3 result))
 137           (car result))))))
 138
 139 (defun proto-stream-open-plain (name buffer host service parameters)
 140   (let ((start (with-current-buffer buffer (point)))
 141         (stream (open-network-stream name buffer host service)))
 142     (list stream
 143           (proto-stream-get-response stream start
 144                                      (plist-get parameters :end-of-command))
 145           nil
 146           'plain)))
 147
 148 (defun proto-stream-open-starttls (name buffer host service parameters)
 149   (let* ((start (with-current-buffer buffer (point)))
 150          (require-tls    (eq (plist-get parameters :type) 'starttls))
 151          (starttls-function  (plist-get parameters :starttls-function))
 152          (success-string     (plist-get parameters :success))
 153          (capability-command (plist-get parameters :capability-command))
 154          (eoc                (plist-get parameters :end-of-command))
 155          ;; Return (STREAM GREETING CAPABILITIES RESULTING-TYPE)
 156          (stream (open-network-stream name buffer host service))
 157          (greeting (proto-stream-get-response stream start eoc))
 158          (capabilities (when capability-command
 159                          (proto-stream-command stream
 160                                                capability-command eoc)))
 161          (resulting-type 'plain)
 162          starttls-command)
 163
 164     ;; If we have built-in STARTTLS support, try to upgrade the
 165     ;; connection.
 166     (when (and (or (fboundp 'open-gnutls-stream)
 167                    (and require-tls
 168                         (executable-find "gnutls-cli")))
 169                capabilities success-string starttls-function
 170                (setq starttls-command
 171                      (funcall starttls-function capabilities)))
 172       ;; If using external STARTTLS, drop this connection and start
 173       ;; anew with `starttls-open-stream'.
 174       (unless (fboundp 'open-gnutls-stream)
 175         (delete-process stream)
 176         (setq start (with-current-buffer buffer (point-max)))
 177         (let* ((starttls-use-gnutls t)
 178                (starttls-extra-arguments
 179                 (if require-tls
 180                     starttls-extra-arguments
 181                   ;; For opportunistic TLS upgrades, we don't really
 182                   ;; care about the identity of the peer.
 183                   (cons "--insecure" starttls-extra-arguments))))
 184           (setq stream (starttls-open-stream name buffer host service)))
 185         (proto-stream-get-response stream start eoc))
 186       (when (string-match success-string
 187                           (proto-stream-command stream starttls-command eoc))
 188         ;; The server said it was OK to begin STARTTLS negotiations.
 189         (if (fboundp 'open-gnutls-stream)
 190             (gnutls-negotiate stream nil host)
 191           (unless (starttls-negotiate stream)
 192             (delete-process stream)))
 193         (if (memq (process-status stream) '(open run))
 194             (setq resulting-type 'tls)
 195           ;; We didn't successfully negotiate STARTTLS; if TLS
 196           ;; isn't demanded, reopen an unencrypted connection.
 197           (unless require-tls
 198             (setq stream (open-network-stream name buffer host service))
 199             (proto-stream-get-response stream start eoc)))
 200         ;; Re-get the capabilities, which may have now changed.
 201         (setq capabilities
 202               (proto-stream-command stream capability-command eoc))))
 203
 204     ;; If TLS is mandatory, close the connection if it's unencrypted.
 205     (and require-tls
 206          (eq resulting-type 'plain)
 207          (delete-process stream))
 208     ;; Return value:
 209     (list stream greeting capabilities resulting-type)))
 210
 211 (defun proto-stream-command (stream command eoc)
 212   (let ((start (with-current-buffer (process-buffer stream) (point-max))))
 213     (process-send-string stream command)
 214     (proto-stream-get-response stream start eoc)))
 215
 216 (defun proto-stream-get-response (stream start end-of-command)
 217   (with-current-buffer (process-buffer stream)
 218     (save-excursion
 219       (goto-char start)
 220       (while (and (memq (process-status stream)
 221                         '(open run))
 222                   (not (re-search-forward end-of-command nil t)))
 223         (accept-process-output stream 0 50)
 224         (goto-char start))
 225       (if (= start (point))
 226           ;; The process died; return nil.
 227           nil
 228         ;; Return the data we got back.
 229         (buffer-substring start (point))))))
 230
 231 (defun proto-stream-open-tls (name buffer host service parameters)
 232   (with-current-buffer buffer
 233     (let ((start (point-max))
 234           (stream
 235            (funcall (if (fboundp 'open-gnutls-stream)
 236                         'open-gnutls-stream
 237                       'open-tls-stream)
 238                     name buffer host service))
 239           (eoc (plist-get parameters :end-of-command)))
 240       (if (null stream)
 241           (list nil nil nil 'plain)
 242         ;; If we're using tls.el, we have to delete the output from
 243         ;; openssl/gnutls-cli.
 244         (unless (fboundp 'open-gnutls-stream)
 245           (proto-stream-get-response stream start eoc)
 246           (goto-char (point-min))
 247           (when (re-search-forward eoc nil t)
 248             (goto-char (match-beginning 0))
 249             (delete-region (point-min) (line-beginning-position))))
 250         (proto-stream-capability-open start stream parameters 'tls)))))
 251
 252 (defun proto-stream-open-shell (name buffer host service parameters)
 253   (require 'format-spec)
 254   (proto-stream-capability-open
 255    (with-current-buffer buffer (point))
 256    (let ((process-connection-type nil))
 257      (start-process name buffer shell-file-name
 258                     shell-command-switch
 259                     (format-spec
 260                      (plist-get parameters :shell-command)
 261                      (format-spec-make
 262                       ?s host
 263                       ?p service))))
 264    parameters 'plain))
 265
 266 (defun proto-stream-capability-open (start stream parameters stream-type)
 267   (let* ((capability-command (plist-get parameters :capability-command))
 268          (eoc                (plist-get parameters :end-of-command))
 269          (greeting (proto-stream-get-response stream start eoc)))
 270     (list stream greeting
 271           (and capability-command
 272                (proto-stream-command stream capability-command eoc))
 273           stream-type)))
 274
 275 (provide 'proto-stream)
 276
 277 ;;; proto-stream.el ends here