[Emacs-diffs] /srv/bzr/emacs/trunk r107287: Try to document smtp changes

[Glenn Morris]

------------------------------------------------------------
revno: 107287
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Tue 2012-02-14 22:15:26 -0500
message:
  Try to document smtp changes
  
  * doc/emacs/sending.texi (Mail Sending): smtpmail-auth-credentials was 
removed.
  
  * doc/misc/smtpmail.texi (Emacs Speaks SMTP): General update for 24.1.
  (Encryption): New chapter, split out from previous.
  
  * lisp/mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type):
  Doc fixes.
  
  * etc/NEWS: Related edits.
modified:
  doc/emacs/ChangeLog
  doc/emacs/sending.texi
  doc/misc/ChangeLog
  doc/misc/smtpmail.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/mail/smtpmail.el

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2012-02-12 02:27:34 +0000
+++ b/doc/emacs/ChangeLog       2012-02-15 03:15:26 +0000
@@ -1,3 +1,7 @@
+2012-02-15  Glenn Morris  <address@hidden>
+
+       * sending.texi (Mail Sending): smtpmail-auth-credentials was removed.
+
 2012-02-12  Glenn Morris  <address@hidden>
 
        * ack.texi (Acknowledgments):

=== modified file 'doc/emacs/sending.texi'
--- a/doc/emacs/sending.texi    2012-01-19 07:21:25 +0000
+++ b/doc/emacs/sending.texi    2012-02-15 03:15:26 +0000
@@ -377,8 +377,8 @@
 Send mail using the through an external mail host, such as your
 Internet service provider's outgoing SMTP mail server.  If you have
 not told Emacs how to contact the SMTP server, it prompts for this
-information, which is saved in the variables
address@hidden and @code{smtpmail-auth-credentials}.
+information, which is saved in the @code{smtpmail-smtp-server} variable
+and the file @file{~/.authinfo}.
 @xref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}.
 
 @item sendmail-send-it

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-02-13 14:14:18 +0000
+++ b/doc/misc/ChangeLog        2012-02-15 03:15:26 +0000
@@ -1,3 +1,8 @@
+2012-02-15  Glenn Morris  <address@hidden>
+
+       * smtpmail.texi (Emacs Speaks SMTP): General update for 24.1.
+       (Encryption): New chapter, split out from previous.
+
 2012-02-13  Lars Ingebrigtsen  <address@hidden>
 
        * gnus.texi (Customizing the IMAP Connection): Mention

=== modified file 'doc/misc/smtpmail.texi'
--- a/doc/misc/smtpmail.texi    2012-01-19 07:21:25 +0000
+++ b/doc/misc/smtpmail.texi    2012-02-15 03:15:26 +0000
@@ -47,6 +47,7 @@
 * How Mail Works::      Brief introduction to mail concepts.
 * Emacs Speaks SMTP::   How to use the SMTP library in Emacs.
 * Authentication::      Authenticating yourself to the server.
+* Encryption::          Protecting your connection to the server.
 * Queued delivery::     Sending mail without an internet connection.
 * Server workarounds::  Mail servers with special requirements.
 * Debugging::           Tracking down problems.
@@ -129,24 +130,37 @@
 machine is often disconnected from the internet.
 
   Sending mail via SMTP requires configuring your mail user agent
-(@pxref{Mail Methods,,,emacs}) to use the SMTP library.  How to do
-this should be described for each mail user agent; for the default
-mail user agent the variable @code{send-mail-function} (@pxref{Mail
-Sending,,,emacs}) is used; for the Message and Gnus user agents the
-variable @code{message-send-mail-function} (@pxref{Mail
-Variables,,,message}) is used.
-
address@hidden
-;; If you use the default mail user agent.
+(@pxref{Mail Methods,,,emacs}) to use the SMTP library.  If you
+have not configured anything, then in Emacs 24.1 and later the first
+time you try to send a mail Emacs will ask how you want to send
+mail.  To use this library, answer @samp{smtp} when prompted.  Emacs
+then asks for the name of the SMTP server.
+
+ If you prefer, or if you are using a non-standard mail user agent,
+you can configure this yourself.  The normal way to do this is to set
+the variable @code{send-mail-function} (@pxref{Mail
+Sending,,,emacs}) to the value you want to use.  To use this library:
+
address@hidden
 (setq send-mail-function 'smtpmail-send-it)
-;; If you use Message or Gnus.
-(setq message-send-mail-function 'smtpmail-send-it)
address@hidden example
address@hidden smallexample
+
address@hidden
+The default value for this variable is @code{sendmail-query-once},
+which interactively asks how you want to send mail.
+
+Your mail user agent might use a different variable for this purpose.
+It should inherit from @code{send-mail-function}, but if it does not,
+or if you prefer, you can set that variable directly.  Consult your
+mail user agent's documentation for more details.  For example,
+(@pxref{Mail Variables,,,message}).
 
   Before using SMTP you must find out the hostname of the SMTP server
-to use.  Your system administrator should provide you with this
-information, but often it is the same as the server you receive mail
-from.
+to use.  Your system administrator or mail service provider should
+supply this information.  Often it is some variant of the server you
+receive mail from.  If your email address is
address@hidden@@example.com}, then the name of the SMTP server is
+may be something like @samp{smtp.example.com}.
 
 @table @code
 @item smtpmail-smtp-server
@@ -201,101 +215,114 @@
 @node Authentication
 @chapter Authentication
 
address@hidden password
address@hidden user name
+Most SMTP servers require clients to authenticate themselves before
+they are allowed to send mail.  Authentication usually involves
+supplying a user name and password. 
+
+If you have not configured anything, then the first time you try to
+send mail via a server, Emacs (version 24.1 and later) prompts you
+for the user name and password to use, and then offers to save the
+information.  By default, Emacs stores authentication information in
+a file @file{~/.authinfo}.
+
address@hidden authinfo
+The basic format of the @file{~/.authinfo} file is one line for each
+set of credentials.  Each line consists of pairs of variables and
+values.  A simple example would be:
+
address@hidden
+machine mail.example.org port 25 login myuser password mypassword
address@hidden smallexample
+
address@hidden
+This specifies that when using the SMTP server called @samp{mail.example.org}
+on port 25, Emacs should send the user name @samp{myuser} and the
+password @samp{mypassword}.  Either or both of the login and password
+fields may be absent, in which case Emacs prompts for the information
+when you try to send mail.  (This replaces the old
address@hidden variable used prior to Emacs 24.1.)
+
address@hidden smtpmail-smtp-user
+  When the SMTP library connects to a host on a certain port, it
+searches the @file{~/.authinfo} file for a matching entry.  If an
+entry is found, the authentication process is invoked and the
+credentials are used.  If the variable @code{smtpmail-smtp-user} is
+set to a address@hidden value, then only entries for that user are
+considered.  For more information on the @file{~/.authinfo}
+file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
+
 @cindex SASL
 @cindex CRAM-MD5
address@hidden PLAIN
 @cindex LOGIN
+The process by which the SMTP library authenticates you to the server
+is known as ``Simple Authentication and Security Layer'' (SASL).
+There are various SASL mechanisms, and this library supports three of
+them: CRAM-MD5, PLAIN, and LOGIN.  It tries each of them, in that order,
+until one succeeds.  The first uses a form of encryption to obscure
+your password, while the other two do not.
+
+
address@hidden Encryption
address@hidden Encryption
+
 @cindex STARTTLS
 @cindex TLS
 @cindex SSL
-Many environments require SMTP clients to authenticate themselves
-before they are allowed to route mail via a server.  The two following
-variables contains the authentication information needed for this.
-
-The first variable, @code{smtpmail-auth-credentials}, instructs the
-SMTP library to use a SASL authentication step, currently only the
-CRAM-MD5 and LOGIN mechanisms are supported and will be selected in
-that order if the server support both.
-
-The second variable, @code{smtpmail-starttls-credentials}, instructs
-the SMTP library to connect to the server using STARTTLS.  This means
-the protocol exchange may be integrity protected and confidential by
-using the Transport Layer Security (TLS) protocol, and optionally also
-authentication of the client and server.
-
-TLS is a security protocol that is also known as SSL, although
-strictly speaking, SSL is an older variant of TLS.  TLS is backwards
-compatible with SSL.  In most mundane situations, the two terms are
-equivalent.
-
-The TLS feature uses the elisp package @file{starttls.el} (see it for
-more information on customization), which in turn require that at
-least one of the following external tools are installed:
+For greater security, you can encrypt your connection to the SMTP
+server.  If this is to work, both Emacs and the server must support it.
+
+The SMTP library supports the ``Transport Layer Security'' (TLS), and
+the older ``Secure Sockets Layer'' (SSL) encryption mechanisms.
+It also supports STARTTLS, which is a variant of TLS in which the
+initial connection to the server is made in plain text, requesting a
+switch to an encrypted channel for the rest of the process.
+
address@hidden smtpmail-stream-type
+The variable @code{smtpmail-stream-type} controls what form of
+connection the SMTP library uses.  The default value is @code{nil},
+which means to use a plain connection, but try to switch to a STARTTLS
+encrypted connection if the server supports it.  Other possible values
+are: @code{starttls} - insist on STARTTLS; @code{ssl} - use TLS/SSL;
+and @code{plain} - no encryption.
+
+Use of any form of TLS/SSL requires support in Emacs.  You can either
+use the built-in support (in Emacs 24.1 and later), or the
address@hidden Lisp library.  The built-in support uses the GnuTLS
address@hidden@url{http://www.gnu.org/software/gnutls/}} library.
+If your Emacs has GnuTLS support built-in, the function
address@hidden is defined and returns address@hidden
+Otherwise, you must use the @file{starttls.el} library (see that file for
+more information on customization options, etc.).  The Lisp library
+requires one of the following external tools to be installed:
 
 @enumerate
 @item
-The GnuTLS command line tool @samp{gnutls-cli}, you can get it from
+The GnuTLS command line tool @samp{gnutls-cli}, which you can get from
 @url{http://www.gnu.org/software/gnutls/}.  This is the recommended
-tool, mainly because it can verify the server certificates.
+tool, mainly because it can verify server certificates.
 
 @item
-The @samp{starttls} external program, you can get it from
+The @samp{starttls} external program, which you can get from
 @file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.
 @end enumerate
 
-It is not uncommon to use both these mechanisms, e.g., to use STARTTLS
-to achieve integrity and confidentiality and then use SASL for client
-authentication.
-
address@hidden @code
address@hidden smtpmail-auth-credentials
address@hidden smtpmail-auth-credentials
-  The variable @code{smtpmail-auth-credentials} contains a list of
-hostname, port, username and password tuples.  When the SMTP library
-connects to a host on a certain port, this variable is searched to
-find a matching entry for that hostname and port.  If an entry is
-found, the authentication process is invoked and the credentials are
-used.
-
-The hostname field follows the same format as
address@hidden (i.e., a string) and the port field the
-same format as @code{smtpmail-smtp-service} (i.e., a string or an
-integer).  The username and password fields, which either can be
address@hidden to indicate that the user is prompted for the value
-interactively, should be strings with the username and password,
-respectively, information that is normally provided by system
-administrators.
-
address@hidden smtpmail-starttls-credentials
address@hidden smtpmail-starttls-credentials
-  The variable @code{smtpmail-starttls-credentials} contains a list of
-tuples with hostname, port, name of file containing client key, and
-name of file containing client certificate.  The processing is similar
-to the previous variable.  The client key and certificate may be
address@hidden if you do not wish to use client authentication.
address@hidden table
-
-The following example illustrates what you could put in
address@hidden/.emacs} to enable both SASL authentication and STARTTLS.  The
-server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
-server port (@code{smtpmail-smtp-service}) is @var{port}, and the
-username and password are @var{username} and @var{password}
-respectively.
-
address@hidden
-;; Authenticate using this username and password against my server.
-(setq smtpmail-auth-credentials
-      '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
-
-;; Note that if @var{port} is an integer, you must not quote it as a
-;; string.  Normally @var{port} should be the integer 25, and the example
-;; become:
-(setq smtpmail-auth-credentials
-      '(("@var{hostname}" 25 "@var{username}" "@var{password}")))
-
-;; Use STARTTLS without authentication against the server.
-(setq smtpmail-starttls-credentials
-      '(("@var{hostname}" "@var{port}" nil nil)))
address@hidden example
address@hidden certificates
address@hidden keys
+The SMTP server may also request that you verify your identity by
+sending a certificate and the associated encryption key to the server.
+If you need to do this, you can use an @file{~/.authinfo} entry like this:
+
address@hidden
+machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert 
"~/.my_smtp_tls.cert"
address@hidden smallexample
+
address@hidden
+(This replaces the old @code{smtpmail-starttls-credentials} variable used
+prior to Emacs 24.1.)
+
 
 @node Queued delivery
 @chapter Queued delivery

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-11 21:44:47 +0000
+++ b/etc/NEWS  2012-02-15 03:15:26 +0000
@@ -141,22 +141,22 @@
 
 *** smtpmail
 
-**** smtpmail now uses encrypted connections (via STARTTLS) if the
-mail server supports them.  It also uses the auth-source framework for
-getting credentials.
++++
+**** smtpmail now uses encrypted connections (via STARTTLS) by default
+if the mail server supports them.  This uses either built-in GnuTLS
+support, or the starttls.el library.  Customize `smtpmail-stream-type'
+to change this.
 
++++
 **** The variable `smtpmail-auth-credentials' has been removed.
-That variable used to have the default value "~/.authinfo", in which
-case you won't see any difference.  But if you changed it to be a list
-of user names and passwords, that setting is now ignored; you will be
-prompted for the user name and the password, which will then be saved
-to ~/.authinfo.  (To control where and how the credentials are stored,
-see the auth-source manual.  You may want to change the auth-source
-preferences if you want to store the credentials encrypted, for
-instance.)
-
-You can also manually copy the credentials to your ~/.authinfo file.
-For example, if you had
+By default, the information is now stored in the file ~/.authinfo.
+This was the default value of smtpmail-auth-credentials.
+If you had customized smtpmail-auth-credentials to a list of user
+names and passwords, those settings will not be used.  Your first
+connection to the smtp server will prompt for the user name and password,
+and then offer to save them to the ~/.authinfo file.  Or you can
+manually copy the credentials to your ~/.authinfo files.  For example,
+if you had
 
   (setq smtpmail-auth-credentials
         '(("mail.example.org" 25 "jim" "s!cret")))
@@ -165,6 +165,10 @@
 
   machine mail.example.org port 25 login jim password s!cret
 
+See the auth-source manual for more information, e.g. on encrypting
+the credentials file.
+
++++
 **** The variable `smtpmail-starttls-credentials' has been removed.
 
 If you had that set, then you need to put

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-14 18:22:47 +0000
+++ b/lisp/ChangeLog    2012-02-15 03:15:26 +0000
@@ -1,3 +1,8 @@
+2012-02-15  Glenn Morris  <address@hidden>
+
+       * mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type):
+       Doc fixes.
+
 2012-02-14  Glenn Morris  <address@hidden>
 
        * mail/smtpmail.el (smtpmail-query-smtp-server): Give it a doc.

=== modified file 'lisp/mail/smtpmail.el'
--- a/lisp/mail/smtpmail.el     2012-02-14 18:22:47 +0000
+++ b/lisp/mail/smtpmail.el     2012-02-15 03:15:26 +0000
@@ -86,7 +86,8 @@
   :group 'smtpmail)
 
 (defcustom smtpmail-smtp-user nil
-  "User name to use when looking up credentials."
+  "User name to use when looking up credentials in the authinfo file.
+If non-nil, only consider credentials for the specified user."
   :version "24.1"
   :type '(choice (const nil) string)
   :group 'smtpmail)
@@ -99,11 +100,10 @@
   :group 'smtpmail)
 
 (defcustom smtpmail-stream-type nil
-  "Connection type SMTP connections.
-This may be either nil (possibly upgraded to STARTTLS if
-possible), or `starttls' (refuse to send if STARTTLS isn't
-available), or `plain' (never use STARTTLS), or `ssl' (to use
-TLS/SSL)."
+  "Type of SMTP connections to use.
+This may be either nil (possibly upgraded to STARTTLS if possible),
+or `starttls' (refuse to send if STARTTLS isn't available), or `plain'
+\(never use STARTTLS), or `ssl' (to use TLS/SSL)."
   :version "24.1"
   :group 'smtpmail
   :type '(choice (const :tag "Possibly upgrade to STARTTLS" nil)