lisp/net/network-stream.el

   1 ;;; network-stream.el --- open network processes, possibly with encryption
   2
   3 ;; Copyright (C) 2010-2012 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 (require 'auth-source)
  48
  49 (autoload 'gnutls-negotiate "gnutls")
  50 (autoload 'open-gnutls-stream "gnutls")
  51
  52 ;;;###autoload
  53 (defun open-network-stream (name buffer host service &rest parameters)
  54   "Open a TCP connection to HOST, optionally with encryption.
  55 Normally, return a network process object; with a non-nil
  56 :return-list parameter, return a list instead (see below).
  57 Input and output work as for subprocesses; `delete-process'
  58 closes it.
  59
  60 NAME is the name for the process.  It is modified if necessary to
  61  make it unique.
  62 BUFFER is a buffer or buffer name to associate with the process.
  63  Process output goes at end of that buffer.  BUFFER may be nil,
  64  meaning that the process is not associated with any buffer.
  65 HOST is the name or IP address of the host to connect to.
  66 SERVICE is the name of the service desired, or an integer specifying
  67  a port number to connect to.
  68
  69 The remaining PARAMETERS should be a sequence of keywords and
  70 values:
  71
  72 :type specifies the connection type, one of the following:
  73   nil or `network'
  74              -- Begin with an ordinary network connection, and if
  75                 the parameters :success and :capability-command
  76                 are also supplied, try to upgrade to an encrypted
  77                 connection via STARTTLS.  Even if that
  78                 fails (e.g. if HOST does not support TLS), retain
  79                 an unencrypted connection.
  80   `plain'    -- An ordinary, unencrypted network connection.
  81   `starttls' -- Begin with an ordinary connection, and try
  82                 upgrading via STARTTLS.  If that fails for any
  83                 reason, drop the connection; in that case the
  84                 returned object is a killed process.
  85   `tls'      -- A TLS connection.
  86   `ssl'      -- Equivalent to `tls'.
  87   `shell'    -- A shell connection.
  88
  89 :return-list specifies this function's return value.
  90   If omitted or nil, return a process object.  A non-nil means to
  91   return (PROC . PROPS), where PROC is a process object and PROPS
  92   is a plist of connection properties, with these keywords:
  93    :greeting -- the greeting returned by HOST (a string), or nil.
  94    :capabilities -- a string representing HOST's capabilities,
  95                     or nil if none could be found.
  96    :type -- the resulting connection type; `plain' (unencrypted)
  97             or `tls' (TLS-encrypted).
  98
  99 :end-of-command specifies a regexp matching the end of a command.
 100
 101 :end-of-capability specifies a regexp matching the end of the
 102   response to the command specified for :capability-command.
 103   It defaults to the regexp specified for :end-of-command.
 104
 105 :success specifies a regexp matching a message indicating a
 106   successful STARTTLS negotiation.  For instance, the default
 107   should be \"^3\" for an NNTP connection.
 108
 109 :capability-command specifies a command used to query the HOST
 110   for its capabilities.  For instance, for IMAP this should be
 111   \"1 CAPABILITY\\r\\n\".
 112
 113 :starttls-function specifies a function for handling STARTTLS.
 114   This function should take one parameter, the response to the
 115   capability command, and should return the command to switch on
 116   STARTTLS if the server supports STARTTLS, and nil otherwise.
 117
 118 :always-query-capabilities says whether to query the server for
 119   capabilities, even if we're doing a `plain' network connection.
 120
 121 :client-certificate should either be a list where the first
 122   element is the certificate key file name, and the second
 123   element is the certificate file name itself, or `t', which
 124   means that `auth-source' will be queried for the key and the
 125   certificate.  This parameter will only be used when doing TLS
 126   or STARTTLS connections.
 127
 128 If :use-starttls-if-possible is non-nil, do opportunistic
 129 STARTTLS upgrades even if Emacs doesn't have built-in TLS
 130 functionality.
 131
 132 :nowait is a boolean that says the connection should be made
 133   asynchronously, if possible."
 134   (unless (featurep 'make-network-process)
 135     (error "Emacs was compiled without networking support"))
 136   (let ((type (plist-get parameters :type))
 137         (return-list (plist-get parameters :return-list)))
 138     (if (and (not return-list)
 139              (or (eq type 'plain)
 140                  (and (memq type '(nil network))
 141                       (not (and (plist-get parameters :success)
 142                                 (plist-get parameters :capability-command))))))
 143         ;; The simplest case: wrapper around `make-network-process'.
 144         (make-network-process :name name :buffer buffer
 145                               :host host :service service
 146                               :nowait (plist-get parameters :nowait))
 147       (let ((work-buffer (or buffer
 148                              (generate-new-buffer " *stream buffer*")))
 149             (fun (cond ((and (eq type 'plain)
 150                              (not (plist-get parameters
 151                                              :always-query-capabilities)))
 152                         'network-stream-open-plain)
 153                        ((memq type '(nil network starttls plain))
 154                         'network-stream-open-starttls)
 155                        ((memq type '(tls ssl)) 'network-stream-open-tls)
 156                        ((eq type 'shell) 'network-stream-open-shell)
 157                        (t (error "Invalid connection type %s" type))))
 158             result)
 159         (unwind-protect
 160             (setq result (funcall fun name work-buffer host service parameters))
 161           (unless buffer
 162             (and (processp (car result))
 163                  (set-process-buffer (car result) nil))
 164             (kill-buffer work-buffer)))
 165         (if return-list
 166             (list (car result)
 167                   :greeting     (nth 1 result)
 168                   :capabilities (nth 2 result)
 169                   :type         (nth 3 result)
 170                   :error        (nth 4 result))
 171           (car result))))))
 172
 173 (defun network-stream-certificate (host service parameters)
 174   (let ((spec (plist-get :client-certificate parameters)))
 175     (cond
 176      ((listp spec)
 177       ;; Either nil or a list with a key/certificate pair.
 178       spec)
 179      ((eq spec t)
 180       (let* ((auth-info
 181               (car (auth-source-search :max 1
 182                                        :host host
 183                                        :port service)))
 184              (key (plist-get auth-info :key))
 185              (cert (plist-get auth-info :cert)))
 186         (and key cert
 187              (list key cert)))))))
 188
 189 ;;;###autoload
 190 (defalias 'open-protocol-stream 'open-network-stream)
 191
 192 (defun network-stream-open-plain (name buffer host service parameters)
 193   (let ((start (with-current-buffer buffer (point)))
 194         (stream (make-network-process :name name :buffer buffer
 195                                       :host host :service service
 196                                       :nowait (plist-get parameters :nowait))))
 197     (list stream
 198           (network-stream-get-response stream start
 199                                        (plist-get parameters :end-of-command))
 200           nil
 201           'plain)))
 202
 203 (defun network-stream-open-starttls (name buffer host service parameters)
 204   (let* ((start (with-current-buffer buffer (point)))
 205          (require-tls    (eq (plist-get parameters :type) 'starttls))
 206          (starttls-function  (plist-get parameters :starttls-function))
 207          (success-string     (plist-get parameters :success))
 208          (capability-command (plist-get parameters :capability-command))
 209          (eoc                (plist-get parameters :end-of-command))
 210          (eo-capa            (or (plist-get parameters :end-of-capability)
 211                                  eoc))
 212          ;; Return (STREAM GREETING CAPABILITIES RESULTING-TYPE)
 213          (stream (make-network-process :name name :buffer buffer
 214                                        :host host :service service))
 215          (greeting (network-stream-get-response stream start eoc))
 216          (capabilities (network-stream-command stream capability-command
 217                                                eo-capa))
 218          (resulting-type 'plain)
 219          (builtin-starttls (and (fboundp 'gnutls-available-p)
 220                                 (gnutls-available-p)))
 221          starttls-available starttls-command error)
 222
 223     ;; First check whether the server supports STARTTLS at all.
 224     (when (and capabilities success-string starttls-function)
 225       (setq starttls-command
 226             (funcall starttls-function capabilities)))
 227     ;; If we have built-in STARTTLS support, try to upgrade the
 228     ;; connection.
 229     (when (and starttls-command
 230                (setq starttls-available
 231                      (or builtin-starttls
 232                          (and (or require-tls
 233                                   (plist-get parameters :use-starttls-if-possible))
 234                               (starttls-available-p))))
 235                (not (eq (plist-get parameters :type) 'plain)))
 236       ;; If using external STARTTLS, drop this connection and start
 237       ;; anew with `starttls-open-stream'.
 238       (unless builtin-starttls
 239         (delete-process stream)
 240         (setq start (with-current-buffer buffer (point-max)))
 241         (let* ((starttls-extra-arguments
 242                 (if require-tls
 243                     starttls-extra-arguments
 244                   ;; For opportunistic TLS upgrades, we don't really
 245                   ;; care about the identity of the peer.
 246                   (cons "--insecure" starttls-extra-arguments)))
 247                (starttls-extra-args starttls-extra-args)
 248                (cert (network-stream-certificate host service parameters)))
 249           ;; There are client certificates requested, so add them to
 250           ;; the command line.
 251           (when cert
 252             (setq starttls-extra-arguments
 253                   (nconc (list "--x509keyfile" (expand-file-name (nth 0 cert))
 254                                "--x509certfile" (expand-file-name (nth 1 cert)))
 255                          starttls-extra-arguments)
 256                   starttls-extra-args
 257                   (nconc (list "--key-file" (expand-file-name (nth 0 cert))
 258                                "--cert-file" (expand-file-name (nth 1 cert)))
 259                          starttls-extra-args)))
 260           (setq stream (starttls-open-stream name buffer host service)))
 261         (network-stream-get-response stream start eoc)
 262         ;; Requery capabilities for protocols that require it; i.e.,
 263         ;; EHLO for SMTP.
 264         (when (plist-get parameters :always-query-capabilities)
 265           (network-stream-command stream capability-command eo-capa)))
 266       (when (string-match success-string
 267                           (network-stream-command stream starttls-command eoc))
 268         ;; The server said it was OK to begin STARTTLS negotiations.
 269         (if builtin-starttls
 270             (let ((cert (network-stream-certificate host service parameters)))
 271               (condition-case nil
 272                   (gnutls-negotiate :process stream :hostname host
 273                                     :keylist (and cert (list cert)))
 274                 ;; If we get a gnutls-specific error (for instance if
 275                 ;; the certificate the server gives us is completely
 276                 ;; syntactically invalid), then close the connection
 277                 ;; and possibly (further down) try to create a
 278                 ;; non-encrypted connection.
 279                 (gnutls-error
 280                  (delete-process stream))))
 281           (unless (starttls-negotiate stream)
 282             (delete-process stream)))
 283         (if (memq (process-status stream) '(open run))
 284             (setq resulting-type 'tls)
 285           ;; We didn't successfully negotiate STARTTLS; if TLS
 286           ;; isn't demanded, reopen an unencrypted connection.
 287           (unless require-tls
 288             (setq stream
 289                   (make-network-process :name name :buffer buffer
 290                                         :host host :service service))
 291             (network-stream-get-response stream start eoc)))
 292         ;; Re-get the capabilities, which may have now changed.
 293         (setq capabilities
 294               (network-stream-command stream capability-command eo-capa))))
 295
 296     ;; If TLS is mandatory, close the connection if it's unencrypted.
 297     (when (and require-tls
 298                ;; ... but Emacs wasn't able to -- either no built-in
 299                ;; support, or no gnutls-cli installed.
 300                (eq resulting-type 'plain))
 301       (setq error
 302             (if (or (null starttls-command)
 303                     starttls-available)
 304                 "Server does not support TLS"
 305               (concat "Emacs does not support TLS, and no external `"
 306                       (if starttls-use-gnutls
 307                           starttls-gnutls-program
 308                         starttls-program)
 309                       "' program was found")))
 310       (delete-process stream)
 311       (setq stream nil))
 312     ;; Return value:
 313     (list stream greeting capabilities resulting-type error)))
 314
 315 (defun network-stream-command (stream command eoc)
 316   (when command
 317     (let ((start (with-current-buffer (process-buffer stream) (point-max))))
 318       (process-send-string stream command)
 319       (network-stream-get-response stream start eoc))))
 320
 321 (defun network-stream-get-response (stream start end-of-command)
 322   (when end-of-command
 323     (with-current-buffer (process-buffer stream)
 324       (save-excursion
 325         (goto-char start)
 326         (while (and (memq (process-status stream) '(open run))
 327                     (not (re-search-forward end-of-command nil t)))
 328           (accept-process-output stream 0 50)
 329           (goto-char start))
 330         ;; Return the data we got back, or nil if the process died.
 331         (unless (= start (point))
 332           (buffer-substring start (point)))))))
 333
 334 (defun network-stream-open-tls (name buffer host service parameters)
 335   (with-current-buffer buffer
 336     (let* ((start (point-max))
 337            (use-builtin-gnutls (and (fboundp 'gnutls-available-p)
 338                                     (gnutls-available-p)))
 339            (stream
 340             (funcall (if use-builtin-gnutls
 341                          'open-gnutls-stream
 342                        'open-tls-stream)
 343                      name buffer host service))
 344            (eoc (plist-get parameters :end-of-command)))
 345       (if (null stream)
 346           (list nil nil nil 'plain)
 347         ;; If we're using tls.el, we have to delete the output from
 348         ;; openssl/gnutls-cli.
 349         (when (and (null use-builtin-gnutls)
 350                    eoc)
 351           (network-stream-get-response stream start eoc)
 352           (goto-char (point-min))
 353           (when (re-search-forward eoc nil t)
 354             (goto-char (match-beginning 0))
 355             (delete-region (point-min) (line-beginning-position))))
 356         (let* ((capability-command (plist-get parameters :capability-command)))
 357           (list stream
 358                 (network-stream-get-response stream start eoc)
 359                 (network-stream-command stream capability-command eoc)
 360                 'tls))))))
 361
 362 (defun network-stream-open-shell (name buffer host service parameters)
 363   (require 'format-spec)
 364   (let* ((capability-command (plist-get parameters :capability-command))
 365          (eoc                (plist-get parameters :end-of-command))
 366          (start (with-current-buffer buffer (point)))
 367          (stream (let ((process-connection-type nil))
 368                    (start-process name buffer shell-file-name
 369                                   shell-command-switch
 370                                   (format-spec
 371                                    (plist-get parameters :shell-command)
 372                                    (format-spec-make
 373                                     ?s host
 374                                     ?p service))))))
 375     (list stream
 376           (network-stream-get-response stream start eoc)
 377           (network-stream-command stream capability-command
 378                                   (or (plist-get parameters :end-of-capability)
 379                                       eoc))
 380           'plain)))
 381
 382 (provide 'network-stream)
 383
 384 ;;; network-stream.el ends here