Configuring your incoming email client for Gmail: fetchmail

  1. Enable POP in your Gmail account.

  2. Find out where X.509/“privacy-enhanced-mail (PEM)” certificates live on your system, e.g., in the /usr/share/ssl/certs/ directory. The “locate .pem” command may help you figure this out, or you can just create a new world-readable directory exclusively for this.

  3. The Gmail POP3-over-SSL (pop3s) server presents a server certificate at every secure-socket-layer (SSL) connection establishment; we will want to be able to verify its authenticity.

    (A new server certificate was rolled out by Gmail on 2005-12-13 when the old one expired on that same day with a few minutes of POP service unavailability.)

    That server certificate is itself signed by a certificate authority (CA), Equifax Secure (now GeoTrust), using a self-signed root certificate having the “Equifax Secure Certificate Authority” organizational unit name (OU) and no common name (CN). You need to download, install in its own file, and index this root certificate.

    sh# cd /usr/share/ssl/certs
    sh# wget -O Equifax_Secure_Certificate_Authority.pem \
    sh# chmod 644 Equifax_Secure_Certificate_Authority.pem
    sh# openssl x509 -in Equifax_Secure_Certificate_Authority.pem \
                     -fingerprint -subject -issuer -serial -hash -noout
    MD5 Fingerprint=67:CB:9D:C0:13:24:8A:82:9B:B2:17:1E:D1:1B:EC:D4
    subject= /C=US/O=Equifax/OU=Equifax Secure Certificate Authority
    issuer= /C=US/O=Equifax/OU=Equifax Secure Certificate Authority
    sh# c_rehash .
    sh# file 594f1775.*
    594f1775.0: symbolic link to `Equifax_Secure_Certificate_Authority.pem'

    The c_rehash command is a Perl script that comes with the OpenSSL toolkit; it creates symbolic links to certificate files (with a “.pem” extension) using symlink names based on a hash of each certificate's whole subject name. Fetchmail uses the OpenSSL libraries and will only try to open the installed file by looking it up under the 594f1775.0 (or 594f1775.1 and so on) file name in the end.

    The server certificate itself does not need to be stored anywhere.

  4. The fetchmail client does not need to present a client certificate. Instead, client authentication is performed using the USER and PASS post-office-protocol version 3 (POP3) commands within the SSL connection, once it has been properly established.

  5. Edit the appropriate .fetchmailrc file, depending on how you run fetchmail (i.e., as root or as a lesser-privileged local user). The contents of this file are documented by the fetchmail(1) man page, which can be consulted using the “man fetchmail” command. You will need an entry such as this one:

    poll with proto POP3
        user '' there with password 'xxxxxxxx' is eric here
            options keep ssl sslfingerprint '59:51:61:89:CD:DD:B2:35:94:BB:44:97:A0:39:D5:B4'
                sslcertck sslcertpath /usr/share/ssl/certs

    Add any other option according to your preferences. If other family members also have a Gmail account and this is root's .fetchmailrc file, you can add similar three-line user subsections under this same poll section; the last two lines will redundantly be identical for every Gmail account.

    The specified password is that of the Gmail account, not the local user's password. Since this configuration file contain passwords, it must be non-world-readable:

    sh# chmod 600 $HOME/.fetchmailrc

    The MD5 fingerprint is that of the “” server certificate delivered by the Gmail POP3-over-SSL server, not that of the “Equifax Secure Certificate Authority” root certificate.

    Note that this will not be enough to perform certificate-revocation-list (CRL) verifications, which fetchmail/OpenSSL does not support; however, this shortcoming is somewhat mitigated by the MD5 fingerprint verification, at the price of a loss in unattended flexibility (should Gmail wish to change its server certificate for some unlikely reason).

    There is no need to inform fetchmail that the POP3-over-SSL (pop3s) TCP port is 995; it's smart enough to figure it out on its own.

    Note that POP3-over-SSL is not the same as regular (non-SSL) POP3 with use of the STLS command and capability (i.e., RFC 2595's POP3 STARTTLS extension), which Gmail does not support.

  6. You should be able to test this with

    sh# fetchmail -d0 -v

    once you complete the email-forwarding/email-delivery part of fetchmail's configuration and integration (which is beyond the email-retrieval scope of this help document).

  7. The Gmail POP3-over-SSL server specifies that it does not want to be polled more than once every five minutes (i.e., 300 seconds), as can be verified by executing the following command:

    sh$ openssl s_client -connect -CApath /usr/share/ssl/certs -quiet
    depth=1 /C=US/O=Equifax/OU=Equifax Secure Certificate Authority
    verify return:1
    depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc./
    verify return:1
    +OK Gpop x99xx9999xxx ready.
    +OK Capability list follows
    EXPIRE 0
    +OK send PASS
    PASS xxxxxxxx
    +OK Welcome.
    +OK Capability list follows
    EXPIRE 0
    +OK Farewell.

    (Authenticating is not strictly necessary for this test. It was done to show how Gmail's POP3 server presents a different list of capabilities before and after login.)

    Make sure to respect this delay if automatic polling is configured. This can be achieved by specifying “set daemon 300” in the .fetchmailrc file, or by specifying “-d 300” on the fetchmail command line, where 300 can be replaced by a greater number if desired.

* Did you click ‘Save Changes’ after enabling POP in Gmail? To ensure that Gmail can communicate with your mail client, be sure to click ‘Save Changes’ on the Gmail ‘Mail Settings’ page.