README.SSL

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