From 9f26dc243268eddc252287ef1918970bf580e946 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Tue, 14 Feb 2012 22:15:26 -0500 Subject: [PATCH] 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. --- doc/emacs/ChangeLog | 4 + doc/emacs/sending.texi | 4 +- doc/misc/ChangeLog | 5 + doc/misc/smtpmail.texi | 203 +++++++++++++++++++++++------------------ etc/NEWS | 32 ++++--- lisp/ChangeLog | 5 + lisp/mail/smtpmail.el | 12 +-- 7 files changed, 155 insertions(+), 110 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index b24c6946281..0b6178d6195 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,7 @@ +2012-02-15 Glenn Morris + + * sending.texi (Mail Sending): smtpmail-auth-credentials was removed. + 2012-02-12 Glenn Morris * ack.texi (Acknowledgments): diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi index 6f154ce2af6..a2cb5d9f8f2 100644 --- a/doc/emacs/sending.texi +++ b/doc/emacs/sending.texi @@ -377,8 +377,8 @@ sending mail via @code{smtpmail-send-it} (see below). 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 -@code{smtpmail-smtp-server} 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 diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index adad93ef89c..a88ac5f0bd4 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,8 @@ +2012-02-15 Glenn Morris + + * smtpmail.texi (Emacs Speaks SMTP): General update for 24.1. + (Encryption): New chapter, split out from previous. + 2012-02-13 Lars Ingebrigtsen * gnus.texi (Customizing the IMAP Connection): Mention diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index af09783f445..4e4df3f0bbb 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -47,6 +47,7 @@ developing GNU and promoting software freedom.'' * 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 @@ be useful if you don't have a MTA set up on your host, or if your 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. +(@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. -@example -;; If you use the default mail user agent. + 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: + +@smallexample (setq send-mail-function 'smtpmail-send-it) -;; If you use Message or Gnus. -(setq message-send-mail-function 'smtpmail-send-it) -@end example +@end smallexample + +@noindent +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 +@samp{yourname@@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 @@ The following example illustrates what you could put in @node Authentication @chapter Authentication +@cindex password +@cindex 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}. + +@cindex 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: + +@smallexample +machine mail.example.org port 25 login myuser password mypassword +@end smallexample + +@noindent +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 +@code{smtpmail-auth-credentials} variable used prior to Emacs 24.1.) + +@vindex 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 non-@code{nil} 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 +@cindex 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. + + +@node Encryption +@chapter 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. +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 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 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. -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. +@vindex 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. -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: +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 +@file{starttls.el} Lisp library. The built-in support uses the GnuTLS +@footnote{@url{http://www.gnu.org/software/gnutls/}} library. +If your Emacs has GnuTLS support built-in, the function +@code{gnutls-available-p} is defined and returns non-@code{nil}. +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. +@cindex certificates +@cindex 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: -@table @code -@item smtpmail-auth-credentials -@vindex 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. +@smallexample +machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert "~/.my_smtp_tls.cert" +@end smallexample -The hostname field follows the same format as -@code{smtpmail-smtp-server} (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 -@code{nil} 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. +@noindent +(This replaces the old @code{smtpmail-starttls-credentials} variable used +prior to Emacs 24.1.) -@item smtpmail-starttls-credentials -@vindex 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 -@code{nil} if you do not wish to use client authentication. -@end table - -The following example illustrates what you could put in -@file{~/.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. - -@example -;; 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))) -@end example @node Queued delivery @chapter Queued delivery diff --git a/etc/NEWS b/etc/NEWS index 262379cc918..c617bd00b59 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -141,22 +141,22 @@ For example, this is used by Rmail to optionally delete a mail window. *** 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 @@ then the equivalent line in ~/.authinfo would be 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 diff --git a/lisp/ChangeLog b/lisp/ChangeLog index d8fdedfdbbd..a3b5a4d9486 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2012-02-15 Glenn Morris + + * mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type): + Doc fixes. + 2012-02-14 Glenn Morris * mail/smtpmail.el (smtpmail-query-smtp-server): Give it a doc. diff --git a/lisp/mail/smtpmail.el b/lisp/mail/smtpmail.el index bbd8d7ce1ef..3233cff2768 100644 --- a/lisp/mail/smtpmail.el +++ b/lisp/mail/smtpmail.el @@ -86,7 +86,8 @@ The default value would be \"smtp\" or 25." :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 @@ don't define this value." :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)