Fetchmail client-side SSL support
=================================

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
specific to fetchmail. This document is about the client-side (fetchmail side)
setup.

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

Note, fetchmail 6.5.0 and newer releases will auto-negotiate TLSv1.2 or newer
only.  If your server does not support this, you may have to specify --sslproto
tls1.1+ or --sslproto tls1.0, providing that your SSL library still supports
these older protocol versions.

This is in order to prefer the newer TLS protocols, because SSLv2 and v3 are
broken, and TLS v1.0 and v1.1 may only be used when no higher version is
available on the server-side.

Fetchmail supports these SSL/TLS libraries, in their respective latest
patch levels, and assuming that they are still under support by their
upstream maintainers:
* OpenSSL 3.0 through 4.0,
* wolfSSL 5.8,
* AWS-LC 1.71 or newer 1.X (this support is experimental)
* OpenBSD's LibreSSL when used on OpenBSD
Newer minor releases may work, too.

Notes for wolfSSL:
* wolfSSL must be built with certain compile options, see INSTALL sec. 1.1b.
* wolfSSL is a bit less flexible about its trust store, see INSTALL sec. 2.1.

Note that many messages printed by fetchmail will print "OpenSSL"
even if wolfSSL is being used. Reason is that fetchmail uses
wolfSSL's OpenSSL compatibility layer and not the native wolfSSL API.

	-- Matthias Andree, 2026-04-11


Quickstart
----------

Use an up-to-date release of a SSL/TLS library (see above),
so as to get TLSv1.3 support and latest fixes.

fetchmail rejects or warns about versions its maintainer deems too old.

wolfSSL needs to be configured with --enable-opensslall --enable-harden,
else some required OpenSSL APIs are missing, especially for SNI (server name
indication), which is required to fetch mail from Google and some other mail
server providers.

In all four examples below, the (--)sslcertck has become redundant
since fetchmail v6.4.0, but since fetchmail 6.3 releases will be in circulation
for too long, (--)sslcertck will remain in the examples below for now.

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

    --ssl --sslproto tls1.2+ --sslcertck

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

      ssl   sslproto tls1.2+   sslcertck


For use of SSL or TLS with in-band negotiation on the regular service's port,
i. e. with STLS or STARTTLS, use these command line options (omitting --ssl or
ssl):

    --sslproto tls1.2+ --sslcertck

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

      sslproto tls1.2+   sslcertck


With up to date OpenSSL or wolfSSL libraries, and with recent software on the
server, you can alternatively configure tls1.3+.

For some older services, you may need to use tls1.1+ or tls1+ for compatibility
instead of the tls1.2+ above.  In such situations, you should ask the service
provider or server operator to upgrade their TLS implementation such that
TLS v1.3 be supported, and once that happens, update your fetchmail configuration
to tls1.3+ or tls1.2+.


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

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.

This works as follows: the server has a key pair (a secret and a public key),
and it sends the client its public key. Messages encrypted with the public key
can be decrypted using the private one and vice versa.

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
using the usual POP/IMAP/whatever authentication mechanisms.

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
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
authenticate against it by telling it your password).

So, not only do you need to prove your identity to the server, the
server likewise needs to prove (authenticate) its identity to you.
  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
the server, and a digital signature and data about the signer.
  Digital signatures can also be made using a key pair as described earlier.

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.
  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.
  You can specify this path using the "sslcertpath" option if it is
different from the one OpenSSL uses by default.
  Alternatively, a "bundle" file (a concatenation of trusted certificates in PEM
form) can be given, using the "sslcertfile".
  fetchmail 6.4.16 and newer will print the default locations where the SSL
library looks when run as fetchmail -V or fetchmail --version.

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
should be reasonably accurate when checking certificates.

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
certificate was not granted to the rightful owner).

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
case that it is not installed). Additionally, you might need to convert the
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
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.

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 unless otherwise specified are MD5 sums
for fetchmail 6.x.y versions, for compatibility,
but it can be any other hash your SSL/TLS library supports,
if you prefix the name of the hash in curly braces.

You can generate them e.g. using openssl(1)'s "x509 -fingerprint" command. The
format is a hexadecimal string 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).

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