Pileus Git - ~andy/fetchmail/blob - README.SSL

   1 Fetchmail client-side SSL support
   2 =================================
   3
   4 Preface
   5 -------
   6
   7 Note: there is a separate document "README.SSL-SERVER" describing the server-
   8 side requirements for proper SSL support.  It has checklist-style and is not
   9 specific to fetchmail.
  10
  11 In case of troubles, mail that other document to your ISP and have them check
  12 their server configuration against it.
  13
  14 Unfortunately, fetchmail confuses SSL/TLS protocol levels with whether
  15 a service needs to use in-band negotiation (STLS/STARTTLS for POP3/IMAP4) or is
  16 totally SSL-wrapped on a separate port.  For compatibility reasons, this cannot
  17 be fixed in a bugfix release.
  18
  19         -- Matthias Andree, 2009-05-09
  20
  21
  22 Quickstart
  23 ----------
  24
  25 For use of SSL or TLS with in-band negotiation on the regular service's port,
  26 i. e. with STLS or STARTTLS, use these command line options (in the rcfile,
  27 omit the leading "--"):
  28
  29     --sslproto tls1 --sslcertck
  30
  31 For use of SSL or TLS on a separate port, if the whole TCP connection is
  32 SSL-encrypted from the very beginning, use these command line options (in the
  33 rcfile, omit the leading "--"):
  34
  35     --ssl --sslproto ssl3 --sslcertck
  36
  37
  38 Background and use (long version :-))
  39 ------------------
  40
  41 Using fetchmail's "ssl" option, you can have the data transferred between you
  42 and the server in an encrypted form, so that eavesdropping should become
  43 practically impossible.
  44
  45 This works as following: the server has a key pair (a secret and a public key),
  46 and it sends the client its public key. Messages encrypted with the public key
  47 can be decrypted using the private one and vice versa.
  48
  49 A symmetric session key (symmetric means that the same key is used for
  50 encryption and decryption) can now be agreed upon by the two parties using the
  51 secure channel the key pair builds. The session key is now used to encrypt the
  52 traffic.
  53
  54 In the fetchmail case, the client can now authenticate itself to the server by
  55 using the usual POP/IMAP/whatever authentication mechanisms.
  56
  57 However, so called man-in-the-middle attacks are still possible: in such
  58 a setting, an attacker pretends to be the server, and thus can e.g. get your
  59 authentication information if you do not use a challenge based authentication
  60 mechanism (because it is thought to be the real server, fetchmail will try to
  61 authenticate against it by telling it your password).
  62
  63 So, not only you need to prove your identity to the server, the server likewise
  64 needs to prove (authenticate) its identity to you.
  65   In the standard setting, the server has a certificate (the client can have
  66 a certificate too to prove its identity, but this is not covered by this
  67 document). This certificate contains the server's public key, some data about
  68 the server, and a digital signature and data about the signer.
  69   Digital signatures can also be made using a key pair as described earlier.
  70
  71 To check this certificate, you should use the new option "sslcertck". When it
  72 is specified, the signature of server certificate is checked against local
  73 trusted certificates to see whether the owner of one of the certificates has
  74 signed that server certificate, and if so, whether the signature is valid.
  75   So, if the server certificate is signed by a Certification Authority (CA),
  76 you put the CA's certificate into a directory where you keep trusted
  77 certificates, and point fetchmail to it. Fetchmail will then accept
  78 certificates signed by the owner of that certificate with the private key
  79 belonging to the public key in the certificate.
  80 You can specify this path using the "sslcertpath" option if it is
  81 different from the one OpenSSL uses by default.
  82
  83 The idea is that the CA only gives certificates to entities whose identity it
  84 has checked and verified (and in this case, that the server name you specify
  85 does belong to it). So, if you trust the CA's verification process, you can be
  86 reasonably sure that if a certificate is signed by the CA, it really belongs to
  87 the server and owner that it claims to.
  88
  89 Certificates are only valid in a certain time window, so your system clock
  90 should be reasonably accurate when checking certificates.
  91
  92 Additionally, CAs keep Certificate Revocation Lists (CRLs) in which they note
  93 the certificates that are to be treated as invalid (e.g. because the server
  94 name has changed, another certificate was granted, or even because the
  95 certificate was not granted to the rightful owner).
  96
  97 The certificate directory must be hashed in a way OpenSSL expects it: each time
  98 you modify a file in that directory or add a file to it, you need to use the
  99 "c_rehash" perl script that comes with OpenSSL (in the tools/ subdirectory, in
 100 case that it is not installed). Additionally, you might need to convert the
 101 certificates to different formats (the PEM format is expected and usually is
 102 available, DER is another one; you can convert between both using the
 103 openssl(1) utility's x509 sub-mode).
 104
 105 The really paranoid (who chose to not trust a CA) can check the fingerprint of
 106 the public key that is used by the server. The fingerprint is a hash of that
 107 key that (hopefully) has few collisions and is hard to attack using a "birthday
 108 attack", i.e. nobody can generate a second key that hashes to the same value of
 109 the original key in reasonable time. So, if the fingerprint matches, you can be
 110 reasonable sure that you talk to the original server, because only that knows
 111 the secret key, and it is very hard to generate a matching secret key from the
 112 public key. If it does not, it might be an attack, but keep in mind that the
 113 server key may also have changed legitimately before panicking ;)
 114
 115 Fetchmail will present the fingerprint to you in verbose mode. You can have
 116 fetchmail check the fingerprint (using the "sslfingerprint" option, and giving
 117 the desired fingerprint as an argument).
 118
 119 The fingerprints fetchmail uses are MD5 sums. You can generate them e.g. using
 120 openssl(1)'s "x509 -fingerprint" command. The format is a hexadecimal string
 121 with a ":" separating two byes (i.e. a ":" every two hex "digits"). The
 122 match is case insensitive since release 6.3.10 (upper-case digits A to F
 123 were required up to and including release 6.3.9).
 124
 125 *CAVEAT*: OpenSSL must be at least version 0.9.7 to be able to check CRLs.
 126
 127         - Thomas Moestl <tmoestl@gmx.net>
 128         - Matthias Andree