network-stream.el 15.3 KB
Newer Older
1
;;; network-stream.el --- open network processes, possibly with encryption
2

3
;; Copyright (C) 2010-2013 Free Software Foundation, Inc.
4 5 6 7 8 9

;; Author: Lars Magne Ingebrigtsen <larsi@gnus.org>
;; Keywords: network

;; This file is part of GNU Emacs.

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 13
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
14 15 16

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 19 20
;; GNU General Public License for more details.

;; 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 24

;;; Commentary:

25 26 27 28
;; This library provides the function `open-network-stream', which provides a
;; higher-level interface for opening TCP network processes than the built-in
;; function `make-network-process'.  In addition to plain connections, it
;; supports TLS/SSL and STARTTLS connections.
29 30 31

;; Usage example:

32
;; (open-network-stream
33
;;  "*nnimap*" buffer address port
34
;;  :type 'network
35 36 37 38 39 40 41 42 43 44 45 46
;;  :capability-command "1 CAPABILITY\r\n"
;;  :success " OK "
;;  :starttls-function
;;  (lambda (capabilities)
;;    (if (not (string-match "STARTTLS" capabilities))
;;        nil
;;      "1 STARTTLS\r\n")))

;;; Code:

(require 'tls)
(require 'starttls)
47
(require 'auth-source)
48

49 50
(autoload 'gnutls-negotiate "gnutls")
(autoload 'open-gnutls-stream "gnutls")
51 52

;;;###autoload
53 54
(defun open-network-stream (name buffer host service &rest parameters)
  "Open a TCP connection to HOST, optionally with encryption.
55 56
Normally, return a network process object; with a non-nil
:return-list parameter, return a list instead (see below).
57 58 59 60 61 62 63 64 65 66 67
Input and output work as for subprocesses; `delete-process'
closes it.

NAME is the name for the process.  It is modified if necessary to
 make it unique.
BUFFER is a buffer or buffer name to associate with the process.
 Process output goes at end of that buffer.  BUFFER may be nil,
 meaning that the process is not associated with any buffer.
HOST is the name or IP address of the host to connect to.
SERVICE is the name of the service desired, or an integer specifying
 a port number to connect to.
68

69 70
The remaining PARAMETERS should be a sequence of keywords and
values:
71 72

:type specifies the connection type, one of the following:
73 74 75 76 77 78 79 80 81 82 83 84 85 86
  nil or `network'
             -- Begin with an ordinary network connection, and if
                the parameters :success and :capability-command
                are also supplied, try to upgrade to an encrypted
                connection via STARTTLS.  Even if that
                fails (e.g. if HOST does not support TLS), retain
                an unencrypted connection.
  `plain'    -- An ordinary, unencrypted network connection.
  `starttls' -- Begin with an ordinary connection, and try
                upgrading via STARTTLS.  If that fails for any
                reason, drop the connection; in that case the
                returned object is a killed process.
  `tls'      -- A TLS connection.
  `ssl'      -- Equivalent to `tls'.
87 88 89 90 91 92 93 94 95
  `shell'    -- A shell connection.

:return-list specifies this function's return value.
  If omitted or nil, return a process object.  A non-nil means to
  return (PROC . PROPS), where PROC is a process object and PROPS
  is a plist of connection properties, with these keywords:
   :greeting -- the greeting returned by HOST (a string), or nil.
   :capabilities -- a string representing HOST's capabilities,
                    or nil if none could be found.
96 97
   :type -- the resulting connection type; `plain' (unencrypted)
            or `tls' (TLS-encrypted).
98 99 100

:end-of-command specifies a regexp matching the end of a command.

101 102 103 104
:end-of-capability specifies a regexp matching the end of the
  response to the command specified for :capability-command.
  It defaults to the regexp specified for :end-of-command.

105 106
:success specifies a regexp matching a message indicating a
  successful STARTTLS negotiation.  For instance, the default
107
  should be \"^3\" for an NNTP connection.
108 109 110 111 112 113 114 115

:capability-command specifies a command used to query the HOST
  for its capabilities.  For instance, for IMAP this should be
  \"1 CAPABILITY\\r\\n\".

:starttls-function specifies a function for handling STARTTLS.
  This function should take one parameter, the response to the
  capability command, and should return the command to switch on
116 117
  STARTTLS if the server supports STARTTLS, and nil otherwise.

Paul Eggert's avatar
Paul Eggert committed
118
:always-query-capabilities says whether to query the server for
119 120 121 122 123 124 125 126
  capabilities, even if we're doing a `plain' network connection.

:client-certificate should either be a list where the first
  element is the certificate key file name, and the second
  element is the certificate file name itself, or `t', which
  means that `auth-source' will be queried for the key and the
  certificate.  This parameter will only be used when doing TLS
  or STARTTLS connections.
127

128 129
:use-starttls-if-possible is a boolean that says to do opportunistic
STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
130

131 132 133
:nogreeting is a boolean that can be used to inhibit waiting for
a greeting from the server.

134
:nowait is a boolean that says the connection should be made
135
  asynchronously, if possible."
136 137
  (unless (featurep 'make-network-process)
    (error "Emacs was compiled without networking support"))
138 139
  (let ((type (plist-get parameters :type))
	(return-list (plist-get parameters :return-list)))
140 141 142 143 144
    (if (and (not return-list)
	     (or (eq type 'plain)
		 (and (memq type '(nil network))
		      (not (and (plist-get parameters :success)
				(plist-get parameters :capability-command))))))
145 146
	;; The simplest case: wrapper around `make-network-process'.
	(make-network-process :name name :buffer buffer
147 148
			      :host host :service service
			      :nowait (plist-get parameters :nowait))
149 150
      (let ((work-buffer (or buffer
			     (generate-new-buffer " *stream buffer*")))
151 152 153 154 155
	    (fun (cond ((and (eq type 'plain)
			     (not (plist-get parameters
					     :always-query-capabilities)))
			'network-stream-open-plain)
		       ((memq type '(nil network starttls plain))
156 157 158 159 160 161 162 163 164 165 166
			'network-stream-open-starttls)
		       ((memq type '(tls ssl)) 'network-stream-open-tls)
		       ((eq type 'shell) 'network-stream-open-shell)
		       (t (error "Invalid connection type %s" type))))
	    result)
	(unwind-protect
	    (setq result (funcall fun name work-buffer host service parameters))
	  (unless buffer
	    (and (processp (car result))
		 (set-process-buffer (car result) nil))
	    (kill-buffer work-buffer)))
167 168 169 170
	(if return-list
	    (list (car result)
		  :greeting     (nth 1 result)
		  :capabilities (nth 2 result)
171 172
		  :type         (nth 3 result)
		  :error        (nth 4 result))
173 174
	  (car result))))))

175 176 177 178 179 180 181 182 183 184 185
(defun network-stream-certificate (host service parameters)
  (let ((spec (plist-get :client-certificate parameters)))
    (cond
     ((listp spec)
      ;; Either nil or a list with a key/certificate pair.
      spec)
     ((eq spec t)
      (let* ((auth-info
	      (car (auth-source-search :max 1
				       :host host
				       :port service)))
186 187
	     (key (plist-get auth-info :key))
	     (cert (plist-get auth-info :cert)))
188 189 190
	(and key cert
	     (list key cert)))))))

191 192 193 194
;;;###autoload
(defalias 'open-protocol-stream 'open-network-stream)

(defun network-stream-open-plain (name buffer host service parameters)
195
  (let ((start (with-current-buffer buffer (point)))
196
	(stream (make-network-process :name name :buffer buffer
197 198
				      :host host :service service
				      :nowait (plist-get parameters :nowait))))
199
    (list stream
200
	  (network-stream-get-response stream start
201
				       (plist-get parameters :end-of-command))
202
	  nil
203
	  'plain)))
204

205
(defun network-stream-open-starttls (name buffer host service parameters)
206
  (let* ((start (with-current-buffer buffer (point)))
207
	 (require-tls    (eq (plist-get parameters :type) 'starttls))
208 209 210 211
	 (starttls-function  (plist-get parameters :starttls-function))
	 (success-string     (plist-get parameters :success))
	 (capability-command (plist-get parameters :capability-command))
	 (eoc                (plist-get parameters :end-of-command))
212 213
	 (eo-capa            (or (plist-get parameters :end-of-capability)
				 eoc))
214
	 ;; Return (STREAM GREETING CAPABILITIES RESULTING-TYPE)
215 216
	 (stream (make-network-process :name name :buffer buffer
				       :host host :service service))
217 218
	 (greeting (and (not (plist-get parameters :nogreeting))
			(network-stream-get-response stream start eoc)))
219 220
	 (capabilities (network-stream-command stream capability-command
					       eo-capa))
221
	 (resulting-type 'plain)
222 223
	 (builtin-starttls (and (fboundp 'gnutls-available-p)
				(gnutls-available-p)))
224
	 starttls-available starttls-command error)
225

226 227 228 229
    ;; First check whether the server supports STARTTLS at all.
    (when (and capabilities success-string starttls-function)
      (setq starttls-command
	    (funcall starttls-function capabilities)))
230 231
    ;; If we have built-in STARTTLS support, try to upgrade the
    ;; connection.
232
    (when (and starttls-command
233 234 235 236 237
	       (setq starttls-available
		     (or builtin-starttls
			 (and (or require-tls
				  (plist-get parameters :use-starttls-if-possible))
			      (starttls-available-p))))
238
	       (not (eq (plist-get parameters :type) 'plain)))
239 240
      ;; If using external STARTTLS, drop this connection and start
      ;; anew with `starttls-open-stream'.
241
      (unless builtin-starttls
242 243
	(delete-process stream)
	(setq start (with-current-buffer buffer (point-max)))
244
	(let* ((starttls-extra-arguments
245 246
		(if (or require-tls
			(member "--insecure" starttls-extra-arguments))
247 248 249
		    starttls-extra-arguments
		  ;; For opportunistic TLS upgrades, we don't really
		  ;; care about the identity of the peer.
250
		  (cons "--insecure" starttls-extra-arguments)))
251
	       (starttls-extra-args starttls-extra-args)
252 253 254 255 256
	       (cert (network-stream-certificate host service parameters)))
	  ;; There are client certificates requested, so add them to
	  ;; the command line.
	  (when cert
	    (setq starttls-extra-arguments
257 258
		  (nconc (list "--x509keyfile" (expand-file-name (nth 0 cert))
			       "--x509certfile" (expand-file-name (nth 1 cert)))
259 260 261 262 263
			 starttls-extra-arguments)
		  starttls-extra-args
		  (nconc (list "--key-file" (expand-file-name (nth 0 cert))
			       "--cert-file" (expand-file-name (nth 1 cert)))
			 starttls-extra-args)))
264
	  (setq stream (starttls-open-stream name buffer host service)))
265 266 267 268
	(network-stream-get-response stream start eoc)
	;; Requery capabilities for protocols that require it; i.e.,
	;; EHLO for SMTP.
	(when (plist-get parameters :always-query-capabilities)
269
	  (network-stream-command stream capability-command eo-capa)))
270 271 272
      (when (let ((response
		   (network-stream-command stream starttls-command eoc)))
	      (and response (string-match success-string response)))
273
	;; The server said it was OK to begin STARTTLS negotiations.
274
	(if builtin-starttls
275
	    (let ((cert (network-stream-certificate host service parameters)))
276 277 278 279 280 281 282 283 284 285
	      (condition-case nil
		  (gnutls-negotiate :process stream :hostname host
				    :keylist (and cert (list cert)))
		;; If we get a gnutls-specific error (for instance if
		;; the certificate the server gives us is completely
		;; syntactically invalid), then close the connection
		;; and possibly (further down) try to create a
		;; non-encrypted connection.
		(gnutls-error
		 (delete-process stream))))
286 287 288 289 290 291
	  (unless (starttls-negotiate stream)
	    (delete-process stream)))
	(if (memq (process-status stream) '(open run))
	    (setq resulting-type 'tls)
	  ;; We didn't successfully negotiate STARTTLS; if TLS
	  ;; isn't demanded, reopen an unencrypted connection.
292
	  (unless require-tls
293 294 295 296
	    (setq stream
		  (make-network-process :name name :buffer buffer
					:host host :service service))
	    (network-stream-get-response stream start eoc)))
297 298
	;; Re-get the capabilities, which may have now changed.
	(setq capabilities
299
	      (network-stream-command stream capability-command eo-capa))))
300 301

    ;; If TLS is mandatory, close the connection if it's unencrypted.
302
    (when (and require-tls
303 304 305
	       ;; ... but Emacs wasn't able to -- either no built-in
	       ;; support, or no gnutls-cli installed.
	       (eq resulting-type 'plain))
306
      (setq error
307 308
	    (if (or (null starttls-command)
		    starttls-available)
309
		"Server does not support TLS"
310 311 312 313 314 315 316 317 318 319
	      ;; See `starttls-available-p'.  If this predicate
	      ;; changes to allow running under Windows, the error
	      ;; message below should be amended.
	      (if (memq system-type '(windows-nt ms-dos))
		  (concat "Emacs does not support TLS")
		(concat "Emacs does not support TLS, and no external `"
			(if starttls-use-gnutls
			    starttls-gnutls-program
			  starttls-program)
			"' program was found"))))
320 321
      (delete-process stream)
      (setq stream nil))
322
    ;; Return value:
323
    (list stream greeting capabilities resulting-type error)))
324

325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344
(defun network-stream-command (stream command eoc)
  (when command
    (let ((start (with-current-buffer (process-buffer stream) (point-max))))
      (process-send-string stream command)
      (network-stream-get-response stream start eoc))))

(defun network-stream-get-response (stream start end-of-command)
  (when end-of-command
    (with-current-buffer (process-buffer stream)
      (save-excursion
	(goto-char start)
	(while (and (memq (process-status stream) '(open run))
		    (not (re-search-forward end-of-command nil t)))
	  (accept-process-output stream 0 50)
	  (goto-char start))
	;; Return the data we got back, or nil if the process died.
	(unless (= start (point))
	  (buffer-substring start (point)))))))

(defun network-stream-open-tls (name buffer host service parameters)
345
  (with-current-buffer buffer
346
    (let* ((start (point-max))
347 348
	   (use-builtin-gnutls (and (fboundp 'gnutls-available-p)
				    (gnutls-available-p)))
349 350 351 352 353 354
	   (stream
	    (funcall (if use-builtin-gnutls
			 'open-gnutls-stream
		       'open-tls-stream)
		     name buffer host service))
	   (eoc (plist-get parameters :end-of-command)))
355
      (if (null stream)
356
	  (list nil nil nil 'plain)
357 358
	;; If we're using tls.el, we have to delete the output from
	;; openssl/gnutls-cli.
359 360
	(when (and (null use-builtin-gnutls)
		   eoc)
361
	  (network-stream-get-response stream start eoc)
362
	  (goto-char (point-min))
363
	  (when (re-search-forward eoc nil t)
364 365
	    (goto-char (match-beginning 0))
	    (delete-region (point-min) (line-beginning-position))))
366 367 368 369 370
	(let* ((capability-command (plist-get parameters :capability-command)))
	  (list stream
		(network-stream-get-response stream start eoc)
		(network-stream-command stream capability-command eoc)
		'tls))))))
371

372
(defun network-stream-open-shell (name buffer host service parameters)
373 374 375
  (require 'format-spec)
  (let* ((capability-command (plist-get parameters :capability-command))
	 (eoc 		     (plist-get parameters :end-of-command))
376 377 378 379 380 381 382 383 384 385 386
	 (start (with-current-buffer buffer (point)))
	 (stream (let ((process-connection-type nil))
		   (start-process name buffer shell-file-name
				  shell-command-switch
				  (format-spec
				   (plist-get parameters :shell-command)
				   (format-spec-make
				    ?s host
				    ?p service))))))
    (list stream
	  (network-stream-get-response stream start eoc)
387 388 389
	  (network-stream-command stream capability-command
				  (or (plist-get parameters :end-of-capability)
				      eoc))
390
	  'plain)))
391

392
(provide 'network-stream)
393

394
;;; network-stream.el ends here