jcs.org
mutt stable branch with some hacks
1IMAP/SSL in mutt
2================
3
4Compilation
5-----------
6If you want to have SSL support in mutt, you need to install OpenSSL
7(http://www.openssl.org) libraries and headers before compiling.
8OpenSSL versions 0.9.3 through 0.9.6a have been tested.
9
10For SSL support to be enabled, you need to run the ``configure''
11script with ``--enable-imap --with-ssl[=PFX]'' parameters. If the
12OpenSSL headers and libraries are not in the default system search
13paths (usually /usr/include and /usr/lib) you can use the optional PFX
14argument to define the root directory of your installation. The
15libraries are then expected to be found in PFX/lib and headers in
16PFX/include/openssl.
17
18
19Usage
20-----
21IMAP/SSL folders can be accessed just like normal IMAP folders, but you
22will also have to add '/ssl' before the closing curly brace. Or you can
23use IMAP url notation, where the methods is called imaps.
24
25For example:
26 mailboxes {localhost/ssl}inbox
27 mailboxes {localhost:994/ssl}inbox
28or
29 mailboxes imaps://localhost/inbox
30 mailboxes imaps://localhost:994/inbox
31
32If you get errors about lack of entropy, it means that Mutt was unable
33to find a source of random data to initialize SSL library with. Should
34this happen, you need to generate the data yourself and save it in a
35file pointed by $entropy_file or $RANDFILE (environment) variables or
36in ~/.rnd.
37
38One way to generate random data would be to run a command which
39generates unpredictable output, for example 'ps aluxww' in Linux, and
40calculating the MD5-sum from the output and saving it in a file.
41
42** Note: The contents of the file pointed by $RANDFILE environment
43** variable (or ~/.rnd if unset) will be overwritten every time Mutt
44** is run so don't put anything you can't afford to lose in that file.
45
46The files Mutt will try to use to initialize SSL library with are files
47pointed by $entropy_file and $RANDFILE (or ~/.rnd if unset.) If your
48OpenSSL is version 0.9.5 or later, the previous files can also be EGD
49sockets (see http://www.lothar.com/tech/crypto/ for more information
50about Entropy Gathering Daemon) and in addition sockets in the following
51places are tried: socket pointed by $EGDSOCKET environment variable,
52~/.entropy and /tmp/entropy.
53
54All the files and sockets mentioned above must be owned by the user and
55have permissions of 600.
56
57
58Certificates
59------------
60Each time a server is contacted, its certificate is checked against
61known valid certificates. When an unknown certificate is encountered,
62you are asked to verify it. If you reject the certificate, the
63connection will be terminated immediately. If you accept the
64certificate, the connection will be established. Accepted certificates
65can also be saved so that further connections to the server are
66automatically accepted.
67
68If your organization has several equivalent IMAP-servers, each of them
69should have a unique certificate which is signed with a common
70certificate. If you want to use all of those servers, you don't need to
71save each server certificate on the first connect. Instead, you can get
72the signer certificate and save it instead. That way, mutt will
73automatically accept all certificates signed with the saved certificate.
74
75System-wide certificates are by default considered trusted when checking
76certificates by signer. This allows system administrators to setup
77trusted certificates for all users. How to install certificates
78system-wide, depends on the OpenSSL installation. Use of system-wide
79certificates can be disabled by unsetting $ssl_usesystemcerts variable.
80
81Certificates will be saved in the file specified by $certificate_file
82variable. It is empty as default, so if you don't want to verify
83certificates each time you connect to a server, you have set this
84variable to some reasonable value.
85
86For example:
87 set certificate_file=~/.mutt/certificates
88
89
90Troubleshooting
91---------------
92If after doing the above, you are unable to successfully connect, it
93is likely that your IMAP server does not support one of the SSL protocols.
94There exist three different protocols, TLSv1, SSLv2, and SSLv3. To check
95each of these, you use the following:
96 openssl s_client -host <imap server> -port <port> -verify -debug -no_tls1
97 openssl s_client -host <imap server> -port <port> -verify -debug -no_ssl2
98 openssl s_client -host <imap server> -port <port> -verify -debug -no_ssl3
99
100You can also combine the options until you get a successful connect. Once
101you know which options do not work, you can set the variables for non-working
102protocols to know. The variables for the protocols are ssl_use_tlsv1,
103ssl_use_sslv2, and ssl_use_sslv3.
104
105--
106Tommi Komulainen
107Tommi.Komulainen@iki.fi
108
109Updated by Jeremy Katz
110katzj@linuxpower.org