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