README.SSL 7.03 KB
Newer Older
1 2
Fetchmail client-side SSL support
=================================
3

4 5 6 7 8
Preface
-------

Note: there is a separate document "README.SSL-SERVER" describing the server- 
side requirements for proper SSL support.  It has checklist-style and is not 
9 10
specific to fetchmail.

11 12
In case of troubles, mail the README.SSL-SERVER file to your ISP and 
have them check their server configuration against it.
13

Matthias Andree's avatar
Matthias Andree committed
14 15 16
Note that fetchmail up to version 6.3.26 confused SSL/TLS protocol levels with
whether a service needs to use in-band negotiation (STLS/STARTTLS for
POP3/IMAP4) or is totally SSL-wrapped on a separate port.
17

18 19 20
Also, fetchmail 6.4.0 and newer releases changed some of the semantics
as the result of a bug-fix, and will auto-negotiate TLSv1 or newer only.
If your server does not support this, you may have to specify --sslproto
Matthias Andree's avatar
Matthias Andree committed
21
ssl3+.  This is in order to prefer the newer TLS protocols, because SSLv2
22 23
and v3 are broken.

Matthias Andree's avatar
Matthias Andree committed
24
	-- Matthias Andree, 2019-08-18
25 26


27 28 29
Quickstart
----------

30
Use an up-to-date release of OpenSSL 1.0.2 or newer, so as to get
Matthias Andree's avatar
Matthias Andree committed
31 32 33 34 35 36
TLSv1.2 support.  If possibly use a TLS1.3-enabled OpenSSL v1.1.1 or newer.
Older OpenSSL versions are unsupported upstream, and fetchmail rejects them.

In all four examples below, the (--)sslcertck has become redunant
since fetchmail v6.4.0 but since fetchmail 6.3 releases will be in circulation
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 44
or these options in the rcfile (after the respective "user"... options)

45
      sslproto auto   sslcertck
46 47


48
For use of SSL or TLS on a separate port, if the whole TCP connection is 
49 50
SSL-encrypted from the very beginning (SSL- or TLS-wrapped), use these
command line options (in the rcfile, omit all leading "--"):
51

52
    --ssl --sslproto auto --sslcertck
53

54 55
or these options in the rcfile (after the respective "user"... options)

56
      ssl   sslproto auto   sslcertck
57

58 59 60 61

Background and use (long version :-))
------------------

Matthias Andree's avatar
Matthias Andree committed
62 63 64
Using fetchmail's "ssl" and since 6.4.0 "sslproto" options,
you can have the data transferred between you and the server in an encrypted
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 69
can be decrypted using the private one and vice versa.

70 71 72 73 74 75
A symmetric session key (symmetric means that the same key is used for 
encryption and decryption) can now be agreed upon by the two parties using the 
secure channel the key pair builds. The session key is now used to encrypt the 
traffic.

In the fetchmail case, the client can now authenticate itself to the server by 
76 77
using the usual POP/IMAP/whatever authentication mechanisms.

78 79
However, so called man-in-the-middle attacks are still possible: in such 
a setting, an attacker pretends to be the server, and thus can e.g. get your 
80 81
authentication information if you do not use a challenge based authentication 
mechanism (because it is thought to be the real server, fetchmail will try to 
82 83
authenticate against it by telling it your password).

84 85
So, not only do you need to prove your identity to the server, the
server likewise needs to prove (authenticate) its identity to you.
86 87 88
  In the standard setting, the server has a certificate (the client can have 
a certificate too to prove its identity, but this is not covered by this 
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 91
  Digital signatures can also be made using a key pair as described earlier.

Matthias Andree's avatar
Matthias Andree committed
92 93 94 95 96
To check this certificate, you should use the new option "sslcertck" (fetchmail
6.4.0 and newer enable it by default). When it is specified, the signature of
the server certificate is checked against local trusted certificates to see
whether the owner of one of the certificates has signed that server
certificate, and if so, whether the signature is valid.
97 98 99 100 101
  So, if the server certificate is signed by a Certification Authority (CA), 
you put the CA's certificate into a directory where you keep trusted 
certificates, and point fetchmail to it. Fetchmail will then accept 
certificates signed by the owner of that certificate with the private key 
belonging to the public key in the certificate.
102 103
You can specify this path using the "sslcertpath" option if it is 
different from the one OpenSSL uses by default.
104 105 106 107 108 109 110 111

The idea is that the CA only gives certificates to entities whose identity it 
has checked and verified (and in this case, that the server name you specify 
does belong to it). So, if you trust the CA's verification process, you can be 
reasonably sure that if a certificate is signed by the CA, it really belongs to 
the server and owner that it claims to.

Certificates are only valid in a certain time window, so your system clock 
112 113
should be reasonably accurate when checking certificates.

114 115 116
Additionally, CAs keep Certificate Revocation Lists (CRLs) in which they note 
the certificates that are to be treated as invalid (e.g. because the server 
name has changed, another certificate was granted, or even because the 
117 118
certificate was not granted to the rightful owner).

119 120 121
The certificate directory must be hashed in a way OpenSSL expects it: each time 
you modify a file in that directory or add a file to it, you need to use the 
"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 124 125 126 127 128 129 130 131
certificates to different formats (the PEM format is expected and usually is 
available, DER is another one; you can convert between both using the 
openssl(1) utility's x509 sub-mode).

The really paranoid (who chose to not trust a CA) can check the fingerprint of 
the public key that is used by the server. The fingerprint is a hash of that 
key that (hopefully) has few collisions and is hard to attack using a "birthday 
attack", i.e. nobody can generate a second key that hashes to the same value of 
the original key in reasonable time. So, if the fingerprint matches, you can be 
132 133 134 135 136
reasonably sure that you are talking to the original server, because 
only that server knows the secret key, and it is very hard to generate a 
matching secret key from the public key. If the fingerprint does not 
match, there might be an attack, but, before panicking, keep in mind 
that the server key may also have changed legitimately.
137 138 139 140 141 142 143

Fetchmail will present the fingerprint to you in verbose mode. You can have 
fetchmail check the fingerprint (using the "sslfingerprint" option, and giving 
the desired fingerprint as an argument).

The fingerprints fetchmail uses are MD5 sums. You can generate them e.g. using
openssl(1)'s "x509 -fingerprint" command. The format is a hexadecimal string 
144 145 146
with a ":" separating two bytes (i.e. a ":" between every two hex "digits"). The 
match is case insensitive since release 6.3.10 (upper-case digits A to F were 
required up to and including release 6.3.9).
147

148
	- Thomas Moestl <tmoestl@gmx.net>
149
	- Matthias Andree