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

3
;; Copyright (C) 2010-2011 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 47 48 49 50 51
;;  :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)

(declare-function gnutls-negotiate "gnutls"
		  (proc type &optional priority-string trustfiles keyfiles))

;;;###autoload
52 53
(defun open-network-stream (name buffer host service &rest parameters)
  "Open a TCP connection to HOST, optionally with encryption.
54 55
Normally, return a network process object; with a non-nil
:return-list parameter, return a list instead (see below).
56 57 58 59 60 61 62 63 64 65 66
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.
67

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

:type specifies the connection type, one of the following:
72 73 74 75 76 77 78 79 80 81 82 83 84 85
  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'.
86 87 88 89 90 91 92 93 94
  `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.
95 96
   :type -- the resulting connection type; `plain' (unencrypted)
            or `tls' (TLS-encrypted).
97 98 99 100 101

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

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

: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
  STARTTLS if the server supports STARTTLS, and nil otherwise."
112 113
  (unless (featurep 'make-network-process)
    (error "Emacs was compiled without networking support"))
114 115
  (let ((type (plist-get parameters :type))
	(return-list (plist-get parameters :return-list)))
116 117 118 119 120
    (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))))))
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
	;; The simplest case: wrapper around `make-network-process'.
	(make-network-process :name name :buffer buffer
			      :host host :service service)
      (let ((work-buffer (or buffer
			     (generate-new-buffer " *stream buffer*")))
	    (fun (cond ((eq type 'plain) 'network-stream-open-plain)
		       ((memq type '(nil network starttls))
			'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)))
139 140 141 142 143 144 145
	(if return-list
	    (list (car result)
		  :greeting     (nth 1 result)
		  :capabilities (nth 2 result)
		  :type         (nth 3 result))
	  (car result))))))

146 147 148 149
;;;###autoload
(defalias 'open-protocol-stream 'open-network-stream)

(defun network-stream-open-plain (name buffer host service parameters)
150
  (let ((start (with-current-buffer buffer (point)))
151 152
	(stream (make-network-process :name name :buffer buffer
				      :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 163 164 165 166
	 (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))
	 ;; Return (STREAM GREETING CAPABILITIES RESULTING-TYPE)
167 168 169 170
	 (stream (make-network-process :name name :buffer buffer
				       :host host :service service))
	 (greeting (network-stream-get-response stream start eoc))
	 (capabilities (network-stream-command stream capability-command eoc))
171
	 (resulting-type 'plain)
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
	 starttls-command)

    ;; If we have STARTTLS support, try to upgrade the connection.
    (when (and (or (fboundp 'open-gnutls-stream)
		   (executable-find "gnutls-cli"))
	       capabilities success-string starttls-function
	       (setq starttls-command
		     (funcall starttls-function capabilities)))
      ;; If using external STARTTLS, drop this connection and start
      ;; anew with `starttls-open-stream'.
      (unless (fboundp 'open-gnutls-stream)
	(delete-process stream)
	(setq start (with-current-buffer buffer (point-max)))
	(let* ((starttls-use-gnutls t)
	       (starttls-extra-arguments
187 188 189 190 191
		(if require-tls
		    starttls-extra-arguments
		  ;; For opportunistic TLS upgrades, we don't really
		  ;; care about the identity of the peer.
		  (cons "--insecure" starttls-extra-arguments))))
192
	  (setq stream (starttls-open-stream name buffer host service)))
193
	(network-stream-get-response stream start eoc))
194
      (when (string-match success-string
195
			  (network-stream-command stream starttls-command eoc))
196 197 198 199 200 201 202 203 204
	;; The server said it was OK to begin STARTTLS negotiations.
	(if (fboundp 'open-gnutls-stream)
	    (gnutls-negotiate stream nil)
	  (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.
205
	  (unless require-tls
206 207 208 209
	    (setq stream
		  (make-network-process :name name :buffer buffer
					:host host :service service))
	    (network-stream-get-response stream start eoc)))
210 211
	;; Re-get the capabilities, which may have now changed.
	(setq capabilities
212
	      (network-stream-command stream capability-command eoc))))
213 214

    ;; If TLS is mandatory, close the connection if it's unencrypted.
215 216
    (and require-tls
	 (eq resulting-type 'plain)
217 218 219
	 (delete-process stream))
    ;; Return value:
    (list stream greeting capabilities resulting-type)))
220

221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
(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)
241
  (with-current-buffer buffer
242 243 244 245 246 247 248 249
    (let* ((start (point-max))
	   (use-builtin-gnutls (fboundp 'open-gnutls-stream))
	   (stream
	    (funcall (if use-builtin-gnutls
			 'open-gnutls-stream
		       'open-tls-stream)
		     name buffer host service))
	   (eoc (plist-get parameters :end-of-command)))
250
      (if (null stream)
251
	  (list nil nil nil 'plain)
252 253
	;; If we're using tls.el, we have to delete the output from
	;; openssl/gnutls-cli.
254 255
	(when (and (null use-builtin-gnutls) eoc)
	  (network-stream-get-response stream start eoc)
256
	  (goto-char (point-min))
257
	  (when (re-search-forward eoc nil t)
258 259
	    (goto-char (match-beginning 0))
	    (delete-region (point-min) (line-beginning-position))))
260 261 262 263 264
	(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))))))
265

266
(defun network-stream-open-shell (name buffer host service parameters)
267 268 269
  (require 'format-spec)
  (let* ((capability-command (plist-get parameters :capability-command))
	 (eoc 		     (plist-get parameters :end-of-command))
270 271 272 273 274 275 276 277 278 279 280 281 282
	 (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)
	  (network-stream-command stream capability-command eoc)
	  'plain)))
283

284
(provide 'network-stream)
285

286
;;; network-stream.el ends here