IMAP/SSL in mutt 
================

Compilation
-----------
If you want to have SSL support in mutt, you need to install OpenSSL
(http://www.openssl.org) libraries and headers before compiling.
OpenSSL versions 0.9.3 and 0.9.4 have been tested.

For SSL support to be enabled, you need to run the ``configure''
script with ``--enable-imap --with-ssl[=PFX]'' parameters.  If the
OpenSSL headers and libraries are not in the default system search
paths (usually /usr/include and /usr/lib) you can use the optional PFX
argument to define the root directory of your installation.  The
libraries are then expected to be found in PFX/lib and headers in
PFX/include/openssl.


Usage
-----
IMAP/SSL folders can be accessed just like normal IMAP folders, but you
will also have to add '/ssl' before the closing curly brace. 

For example:
	mailboxes {localhost/ssl}inbox
	mailboxes {localhost:994/ssl}inbox


If you get errors about lack of entropy, it means that Mutt was unable
to find a source of random data to initialize SSL library with. Should
this happen, you need to generate the data yourself and save it in a
file somewhere Mutt will find it. Mutt tries to use files
$SslEntropyFile, $RANDFILE (if this environment variable is set) and
~/.rnd in that order as source for random data.

If your OpenSSL is version 0.9.5 or later, you should try EGD, Entropy
Gathering Daemon, from http://www.lothar.com/tech/crypto/ . Mutt will
try to find EGD sockets in the following places, $SslEntropyFile,
$EGDSOCKET (if this environment variable is set), ~/.entropy and
/tmp/entropy. If no socket is found, static files will be tried as
described above.


Each time a server is contacted, its certificate is checked against
known valid certificates. When an unknown certificate is encountered,
you are asked to verify it. If you reject the certificate, the
connection will be terminated immediately. If you accept the
certificate, the connection will be established. If you accept the
certificate, you can also save it so that further connections to the
server are automatically accepted. Certificates will be saved in the
file specified by $certificate_file variable. It is empty as default,
so if you don't want to verify certificates each time you connect to a
server, you have set this variable to some reasonable value.

For example:
	set certificate_file=~/.mutt/certificates


Troubleshooting
---------------
If after doing the above, you are unable to successfully connect, it
is likely that your IMAP server does not support one of the SSL protocols.
There exist three different protocols, TLSv1, SSLv2, and SSLv3.  To check
each of these, you use the following:
    openssl s_client -host <imap server> -port <port> -verify -debug -no_tls1
    openssl s_client -host <imap server> -port <port> -verify -debug -no_ssl2
    openssl s_client -host <imap server> -port <port> -verify -debug -no_ssl3

You can also combine the options until you get a successfull connect.  Once
you know which options do not work, you can set the variables for non-working
protocols to know.  The variables for the protocols are ssl_use_tlsv1, 
ssl_use_sslv2, and ssl_use_sslv3.

-- 
Tommi Komulainen
Tommi.Komulainen@iki.fi

Updated by Jeremy Katz
katzj@linuxpower.org