@settitle Emacs SMTP Library
@syncodeindex vr fn
@copying
-Copyright @copyright{} 2003 Free Software Foundation, Inc.
+Copyright @copyright{} 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
* Queued delivery:: Sending mail without an internet connection.
* Server workarounds:: Mail servers with special requirements.
* Debugging:: Tracking down problems.
+* GNU Free Documentation License:: The license for this documentation.
Indices
@cindex SASL
@cindex CRAM-MD5
-@cindex PLAIN
@cindex LOGIN
@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, PLAIN and LOGIN-MD5 mechanisms are supported and will be
-selected in that order if the server supports them. The second
-variable, @code{smtpmail-starttls-credentials}, instructs the SMTP
-library to connect to the server using STARTTLS. This means the
-protocol exchange can be integrity protected and confidential by using
-TLS, and optionally also authentication of the client. It is common
-to use both these mechanisms, e.g., to use STARTTLS to achieve
-integrity and confidentiality and then use SASL for client
+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:
+
+@enumerate
+@item
+The GNUTLS command line tool @samp{gnutls-cli}, you can get it from
+@url{http://www.gnu.org/software/gnutls/}. This is the recommended
+tool, mainly because it can verify the server certificates.
+
+@item
+The @samp{starttls} external program, you can get it 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.
@table @code
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
+used.
+
+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 queried for the value
+@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.
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. The use
-of this variable requires the @samp{starttls} external program to be
-installed, you can get @file{starttls-*.tar.gz} from
-@uref{ftp://ftp.opaopa.org/pub/elisp/}.
+@code{nil} if you do not wish to use client authentication.
@end table
The following example illustrates what you could put in
;; 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)))
If you connect to the internet via a dialup connection, or for some
other reason don't have permanent internet connection, sending mail
will fail when you are not connected. The SMTP library implements
-queued delivery, and the following variable control its behaviour.
+queued delivery, and the following variable control its behavior.
@table @code
@item smtpmail-queue-mail
The variable @code{smtpmail-sendto-domain} makes the SMTP library
add @samp{@@} and the specified value to recipients specified in the
message when they are sent using the @code{RCPT TO} command. Some
-configurations of sendmail requires this behaviour. Don't bother to
+configurations of sendmail requires this behavior. Don't bother to
set this unless you have get an error like:
@example
@end table
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
+
@node Index
@chapter Index
HCoop / bpt / emacs.git / blobdiff