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 (autoload 'gnutls-negotiate "gnutls")
  55 (autoload 'open-gnutls-stream "gnutls")
  56
  57 ;;;###autoload
  58 (defun open-protocol-stream (name buffer host service &rest parameters)
  59   "Open a network stream to HOST, possibly with encryption.
  60 Normally, return a network process object; with a non-nil
  61 :return-list parameter, return a list instead (see below).
  62
  63 The first four parameters, NAME, BUFFER, HOST, and SERVICE, have
  64 the same meanings as in `open-network-stream'.  The remaining
  65 PARAMETERS should be a sequence of keywords and values:
  66
  67 :type specifies the connection type, one of the following:
  68   nil or `network'
  69              -- Begin with an ordinary network connection, and if
  70                 the parameters :success and :capability-command
  71                 are also supplied, try to upgrade to an encrypted
  72                 connection via STARTTLS.  Even if that
  73                 fails (e.g. if HOST does not support TLS), retain
  74                 an unencrypted connection.
  75   `plain'    -- An ordinary, unencrypted network connection.
  76   `starttls' -- Begin with an ordinary connection, and try
  77                 upgrading via STARTTLS.  If that fails for any
  78                 reason, drop the connection; in that case the
  79                 returned object is a killed process.
  80   `tls'      -- A TLS connection.
  81   `ssl'      -- Equivalent to `tls'.
  82   `shell'    -- A shell connection.
  83
  84 :return-list specifies this function's return value.
  85   If omitted or nil, return a process object.  A non-nil means to
  86   return (PROC . PROPS), where PROC is a process object and PROPS
  87   is a plist of connection properties, with these keywords:
  88    :greeting -- the greeting returned by HOST (a string), or nil.
  89    :capabilities -- a string representing HOST's capabilities,
  90                     or nil if none could be found.
  91    :type -- the resulting connection type; `plain' (unencrypted)
  92             or `tls' (TLS-encrypted).
  93
  94 :end-of-command specifies a regexp matching the end of a command.
  95   If non-nil, it defaults to \"\\n\".
  96
  97 :end-of-capability specifies a regexp matching the end of the
  98   response to the command specified for :capability-command.
  99   It defaults to the regexp specified for :end-of-command.
 100
 101 :success specifies a regexp matching a message indicating a
 102   successful STARTTLS negotiation.  For instance, the default
 103   should be \"^3\" for an NNTP connection.
 104
 105 :capability-command specifies a command used to query the HOST
 106   for its capabilities.  For instance, for IMAP this should be
 107   \"1 CAPABILITY\\r\\n\".
 108
 109 :starttls-function specifies a function for handling STARTTLS.
 110   This function should take one parameter, the response to the
 111   capability command, and should return the command to switch on
 112   STARTTLS if the server supports STARTTLS, and nil otherwise."
 113   (let ((type (plist-get parameters :type))
 114 &nb