code.delx.au - gnu-emacs/blob - lisp/net/network-stream.el

   1 ;;; network-stream.el --- open network processes, possibly with encryption
   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 provides the function `open-network-stream', which provides a
  26 ;; higher-level interface for opening TCP network processes than the built-in
  27 ;; function `make-network-process'.  In addition to plain connections, it
  28 ;; supports TLS/SSL and STARTTLS connections.
  29
  30 ;; Usage example:
  31
  32 ;; (open-network-stream
  33 ;;  "*nnimap*" buffer address port
  34 ;;  :type 'network
  35 ;;  :capability-command "1 CAPABILITY\r\n"
  36 ;;  :success " OK "
  37 ;;  :starttls-function
  38 ;;  (lambda (capabilities)
  39 ;;    (if (not (string-match "STARTTLS" capabilities))
  40 ;;        nil
  41 ;;      "1 STARTTLS\r\n")))
  42
  43 ;;; Code:
  44
  45 (require 'tls)
  46 (require 'starttls)
  47
  48 (declare-function gnutls-negotiate "gnutls"
  49                   (proc type &optional priority-string trustfiles keyfiles))
  50
  51 ;;;###autoload
  52 (defun open-network-stream (name buffer host service &rest parameters)
  53   "Open a TCP connection to HOST, optionally with encryption.
  54 Normally, return a network process object; with a non-nil
  55 :return-list parameter, return a list instead (see below).
  56 Input and output work as for subprocesses; `delete-process'
  57 closes it.
  58
  59 NAME is the name for the process.  It is modified if necessary to
  60  make it unique.
  61 BUFFER is a buffer or buffer name to associate with the process.
  62  Process output goes at end of that buffer.  BUFFER may be nil,
  63  meaning that the process is not associated with any buffer.
  64 HOST is the name or IP address of the host to connect to.
  65 SERVICE is the name of the service desired, or an integer specifying
  66  a port number to connect to.
  67
  68 The remaining PARAMETERS should be a sequence of keywords and
  69 values:
  70
  71 :type specifies the connection type, one of the following:
  72   nil or `network'
  73              -- Begin with an ordinary network connection, and if
  74                 the parameters :success and :capability-command
  75                 are also supplied, try to upgrade to an encrypted
  76                 connection via STARTTLS.  Even if that
  77                 fails (e.g. if HOST does not support TLS), retain
  78                 an unencrypted connection.
  79   `plain'    -- An ordinary, unencrypted network connection.
  80   `starttls' -- Begin with an ordinary connection, and try
  81                 upgrading via STARTTLS.  If that fails for any
  82                 reason, drop the connection; in that case the
  83                 returned object is a killed process.
  84   `tls'      -- A TLS connection.
  85   `ssl'      -- Equivalent to `tls'.
  86   `shell'    -- A shell connection.
  87
  88 :return-list specifies this function's return value.
  89   If omitted or nil, return a process object.  A non-nil means to
  90   return (PROC . PROPS), where PROC is a process object and PROPS
  91   is a plist of connection properties, with these keywords:
  92    :greeting -- the greeting returned by HOST (a string), or nil.
  93    :capabilities -- a string representing HOST's capabilities,
  94                     or nil if none could be found.
  95    :type -- the resulting connection type; `plain' (unencrypted)
  96             or `tls' (TLS-encrypted).
  97
  98 :end-of-command specifies a regexp matching the end of a command.
  99
 100 :success specifies a regexp matching a message indicating a
 101   successful STARTTLS negotiation.  For instance, the default
 102   should be \"^3\" for an NNTP connection.
 103
 104 :capability-command specifies a command used to query the HOST
 105   for its capabilities.  For instance, for IMAP this should be
 106   \"1 CAPABILITY\\r\\n\".
 107
 108 :starttls-function specifies a function for handling STARTTLS.
 109   This function should take one parameter, the response to the
 110   capability command, and should return the command to switch on
 111   STARTTLS if the server supports STARTTLS, and nil otherwise."
 112   (unless (featurep 'make-network-process)
 113     (error "Emacs was compiled without networking support"))
 114   (let ((type (plist-get parameters :type))
 115         (return-list (plist-get parameters :return-list)))
 116     (if (and (not return-list)
 117              (or (eq type 'plain)
 118                  (and (memq type '(nil network))
 119                       (not (and (plist-get parameters :success)
 120                                 (plist-get parameters :capability-command))))))
 121         ;; The simplest case: wrapper around `make-network-process'.
 122         (make-network-process :name name :buffer buffer
 123                               :host host :service service)
 124       (let ((work-buffer (or buffer
 125                              (generate-new-buffer " *stream buffer*")))
 126             (fun (cond ((eq type 'plain) 'network-stream-open-plain)
 127                        ((memq type '(nil network starttls))
 128                         'network-stream-open-starttls)
 129                        ((memq type '(tls ssl)) 'network-stream-open-tls)
 130                        ((eq type 'shell) 'network-stream-open-shell)
 131                        (t (error "Invalid connection type %s" type))))
 132             result)
 133         (unwind-protect
 134             (setq result (funcall fun name work-buffer host service parameters))
 135           (unless buffer
 136             (and (processp (car result))
 137                  (set-process-buffer (car result) nil))
 138             (kill-buffer work-buffer)))
 139         (if return-list
 140             (list (car result)
 141                   :greeting     (nth 1 result)
 142                   :capabilities (nth 2 result)
 143                   :type         (nth 3 result))
 144           (car result))))))
 145
 146 ;;;###autoload
 147 (defalias 'open-protocol-stream 'open-network-stream)
 148
 149 (defun network-stream-open-plain (name buffer host service parameters)
 150   (let ((start (with-current-buffer buffer (point)))
 151         (stream (make-network-process :name name :buffer buffer
 152                                       :host host :service service)))
 153     (list stream
 154           (network-stream-get-response stream start
 155                                      (plist-get parameters :end-of-command))
 156           nil
 157           'plain)))
 158
 159 (defun network-stream-open-starttls (name buffer host service parameters)
 160   (let* ((start (with-current-buffer buffer (point)))
 161          (require-tls    (eq (plist-get parameters :type) 'starttls))
 162          (starttls-function  (plist-get parameters :starttls-function))
 163          (success-string     (plist-get parameters :success))
 164          (capability-command (plist-get parameters :capability-command))
 165          (eoc                (plist-get parameters :end-of-command))
 166          ;; Return (STREAM GREETING CAPABILITIES RESULTING-TYPE)
 167          (stream (make-network-process :name name :buffer buffer
 168                                        :host host :service service))
 169          (greeting (network-stream-get-response stream start eoc))
 170          (capabilities (network-stream-command stream capability-command eoc))
 171          (resulting-type 'plain)
 172          starttls-command)
 173
 174     ;; If we have built-in STARTTLS support, try to upgrade the
 175     ;; connection.
 176     (when (and (or (fboundp 'open-gnutls-stream)
 177                    (and require-tls
 178                         (executable-find "gnutls-cli")))
 179                capabilities success-string starttls-function
 180                (setq starttls-command
 181                      (funcall starttls-function capabilities)))
 182       ;; If using external STARTTLS, drop this connection and start
 183       ;; anew with `starttls-open-stream'.
 184       (unless (fboundp 'open-gnutls-stream)
 185         (delete-process stream)
 186         (setq start (with-current-buffer buffer (point-max)))
 187         (let* ((starttls-use-gnutls t)
 188                (starttls-extra-arguments
 189                 (if require-tls
 190                     starttls-extra-arguments
 191                   ;; For opportunistic TLS upgrades, we don't really
 192                   ;; care about the identity of the peer.
 193                   (cons "--insecure" starttls-extra-arguments))))
 194           (setq stream (starttls-open-stream name buffer host service)))
 195         (network-stream-get-response stream start eoc))
 196       (when (string-match success-string
 197                           (network-stream-command stream starttls-command eoc))
 198         ;; The server said it was OK to begin STARTTLS negotiations.
 199         (if (fboundp 'open-gnutls-stream)
 200             (gnutls-negotiate stream nil)
 201           (unless (starttls-negotiate stream)
 202             (delete-process stream)))
 203         (if (memq (process-status stream) '(open run))
 204             (setq resulting-type 'tls)
 205           ;; We didn't successfully negotiate STARTTLS; if TLS
 206           ;; isn't demanded, reopen an unencrypted connection.
 207           (unless require-tls
 208             (setq stream
 209                   (make-network-process :name name :buffer buffer
 210                                         :host host :service service))
 211             (network-stream-get-response stream start eoc)))
 212         ;; Re-get the capabilities, which may have now changed.
 213         (setq capabilities
 214               (network-stream-command stream capability-command eoc))))
 215
 216     ;; If TLS is mandatory, close the connection if it's unencrypted.
 217     (and require-tls
 218          (eq resulting-type 'plain)
 219          (delete-process stream))
 220     ;; Return value:
 221     (list stream greeting capabilities resulting-type)))
 222
 223 (defun network-stream-command (stream command eoc)
 224   (when command
 225     (let ((start (with-current-buffer (process-buffer stream) (point-max))))
 226       (process-send-string stream command)
 227       (network-stream-get-response stream start eoc))))
 228
 229 (defun network-stream-get-response (stream start end-of-command)
 230   (when end-of-command
 231     (with-current-buffer (process-buffer stream)
 232       (save-excursion
 233         (goto-char start)
 234         (while (and (memq (process-status stream) '(open run))
 235                     (not (re-search-forward end-of-command nil t)))
 236           (accept-process-output stream 0 50)
 237           (goto-char start))
 238         ;; Return the data we got back, or nil if the process died.
 239         (unless (= start (point))
 240           (buffer-substring start (point)))))))
 241
 242 (defun network-stream-open-tls (name buffer host service parameters)
 243   (with-current-buffer buffer
 244     (let* ((start (point-max))
 245            (use-builtin-gnutls (fboundp 'open-gnutls-stream))
 246            (stream
 247             (funcall (if use-builtin-gnutls
 248                          'open-gnutls-stream
 249                        'open-tls-stream)
 250                      name buffer host service))
 251            (eoc (plist-get parameters :end-of-command)))
 252       (if (null stream)
 253           (list nil nil nil 'plain)
 254         ;; If we're using tls.el, we have to delete the output from
 255         ;; openssl/gnutls-cli.
 256         (when (and (null use-builtin-gnutls) eoc)
 257           (network-stream-get-response stream start eoc)
 258           (goto-char (point-min))
 259           (when (re-search-forward eoc nil t)
 260             (goto-char (match-beginning 0))
 261             (delete-region (point-min) (line-beginning-position))))
 262         (let* ((capability-command (plist-get parameters :capability-command)))
 263           (list stream
 264                 (network-stream-get-response stream start eoc)
 265                 (network-stream-command stream capability-command eoc)
 266                 'tls))))))
 267
 268 (defun network-stream-open-shell (name buffer host service parameters)
 269   (require 'format-spec)
 270   (let* ((capability-command (plist-get parameters :capability-command))
 271          (eoc                (plist-get parameters :end-of-command))
 272          (start (with-current-buffer buffer (point)))
 273          (stream (let ((process-connection-type nil))
 274                    (start-process name buffer shell-file-name
 275                                   shell-command-switch
 276                                   (format-spec
 277                                    (plist-get parameters :shell-command)
 278                                    (format-spec-make
 279                                     ?s host
 280                                     ?p service))))))
 281     (list stream
 282           (network-stream-get-response stream start eoc)
 283           (network-stream-command stream capability-command eoc)
 284           'plain)))
 285
 286 (provide 'network-stream)
 287
 288 ;;; network-stream.el ends here