In July 2008 Chris Yeardley and I set up an external web and mail server. Chris uses Microsoft, so she needs to pull her mail down with POP. Since this goes out on the Internet, it's clear that my previous toy solutions for the local network, using popper would be inadequate, so I installed qpopper instead. It was complicated enough for me to write down the details. This page describes how to do it as briefly as possible; there's another page with the history and a description of some of the things that can go wrong.

Install the software

Install the software in the standard way from the FreeBSD Ports Collection. The only modification should be to build the PDF documentation, which for some reason is not built by default. Do this:

=== root@dereel (/dev/ttyp1) ~ 321 -> cd /usr/ports/mail/qpopper/
=== root@dereel (/dev/ttyp1) /usr/ports/mail/qpopper 322 -> make config
=== root@dereel (/dev/ttyp1) /usr/ports/mail/qpopper 322 -> make install
      

In the make config, tick the “install pdf documentation” box.

Generating certificates and keys

Using TLS and SSL for the transport requires a number of certificates and keys. I'm still trying to get my head round this, so the description may be inaccurate, though the results work. If you know better and can point to inaccuracies, I'd be happy to hear from you.

Part of the process requires an X.509 server certificate. For externally visible systems, this should be signed by a certificate authority. For my purposes, anything that I trust is good enough, so I'll make my own. This means the following keys:

1. A private CA key to sign the X.509 certificate.
2. An X.509 POP3 server certificate.
3. A private SSL/TLS key for qpopper.
4. A signed certificate for the key.

I put all these certificates in the directory /etc/mail/certs. Arguably they should be in different directories, but this is the only purpose I'm using it for, so it's more convenient like this. I can't get past the feeling that most of this is overkill.

Private CA key

=== root@dereel (/dev/ttypp) ~ 57 -> mkdir /etc/mail/certs
=== root@dereel (/dev/ttypp) ~ 58 -> cd /etc/mail/certs
=== root@dereel (/dev/ttypp) /etc/mail/certs 59 -> openssl genrsa -des3 -out lemis-ca.key 2048
Generating RSA private key, 2048 bit long modulus
............................................................................................................................................................................+++
........+++
e is 65537 (0x10001)
Enter pass phrase for lemis-ca.key: doesn't echo
Verifying - Enter pass phrase for lemis-ca.key: doesn't echo
      

Private X.509 certificate

=== root@dereel (/dev/ttypp) /etc/mail/certs 60 -> openssl req -new -x509 -days 3650 \
       -key lemis-ca.key -out lemis-ca.crt
Enter pass phrase for lemis-ca.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: Press Enter
State or Province Name (full name) [Some-State]:VIC
Locality Name (eg, city) []:Dereel
Organization Name (eg, company) [Internet Widgits Pty Ltd]:LEMIS (SA) Pty Ltd
Organizational Unit Name (eg, section) []:Certificate Authority
Common Name (eg, YOUR name) []:mail.lemis.com
Email Address []:frog@lemis.com
      

It wasn't until long after writing this HOWTO that I discovered the importance of “Common Name”. The prompt suggests that it should be your own name, but that really doesn't work. POP clients expect it to match the name they have used to find this server, and if it isn't, they complain bitterly. Thunderbird, for example, produces an “error dialog” for Every Single Message.

Private SSL/TLS key

=== root@dereel (/dev/ttypp) /etc/mail/certs 61 -> openssl genrsa -out pop3key.pem 1024
Generating RSA private key, 1024 bit long modulus
..........................................++++++
......................++++++
e is 65537 (0x10001)
=== root@dereel (/dev/ttypp) /etc/mail/certs 62 -> l
total 1
-rw-r--r--  1 root  wheel  1728 Jul 12 15:05 lemis-ca.crt
-rw-r--r--  1 root  wheel  1751 Jul 12 15:01 lemis-ca.key
drwxr-xr-x  2 root  wheel   512 Jul 12 15:01 old
-rw-r--r--  1 root  wheel   887 Jul 12 15:05 pop3key.pem
=== root@dereel (/dev/ttypp) /etc/mail/certs 66 -> chmod 400 pop3key.pem
      

Certificate Signing Request

According to the HOWTO I copied, the “Common Name” must match the server name. No explanation why beyond “you will have many problems!”. I didn't follow this instruction, and although I had many problems, none seemed related to this issue.

The values here are all the same as for the certificate; the only difference is the “Organizational Unit Name”, which I have entered as suggested.

=== root@dereel (/dev/ttypp) /etc/mail/certs 63 -> openssl req -new -key pop3key.pem \
   -out pop3cert.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: Press Enter
State or Province Name (full name) [Some-State]:VIC
Locality Name (eg, city) []:Dereel
Organization Name (eg, company) [Internet Widgits Pty Ltd]:LEMIS (SA) Pty Ltd
Organizational Unit Name (eg, section) []:Messaging
Common Name (eg, YOUR name) []:www.lemis.com
Email Address []:frog@lemis.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []: Press Enter
An optional company name []: Press Enter
      

Sign CSR with our CA key

=== root@dereel (/dev/ttypp) /etc/mail/certs 64 -> openssl x509 -req -in pop3cert.csr \
    -out pop3cert.pem -sha1 -CA lemis-ca.crt -CAkey lemis-ca.key -CAcreateserial -days 3650
Signature ok
subject=/C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Messaging/CN=www.lemis.com/emailAddress=grog@lemis.com
Getting CA Private Key
Enter pass phrase for lemis-ca.key: doesn't echo
=== root@dereel (/dev/ttypp) /etc/mail/certs 67 -> chmod 400 *
      

Configuration

Configuration takes two parts: the qpopper configuration file and inetd.conf.

Config file

By default, qpopper doesn't have a config file, so there's (apparently) no default name. The port installs a file /usr/local/etc/qpopper.config.sample, but that seems wrong, especially since there is also a directory /usr/local/etc/qpopper, so I put my config file in /usr/local/etc/qpopper/qpopper.config. The important entries are the type of authentication and the location of the certificate and key files. I've also kept a recommendation about statistics, though it wasn't explained, and I haven't got round to reading up on it:

inetd.conf

Add the last line to inetd.conf. The first two will probably already be there, and you'll need to ensure that the line beginning with pop3 is commented out.

To complete the configuration, get inetd to re-read inetd.conf:

=== root@dereel (/dev/ttypa) ~ 69 -> killall -1 inetd
      

Testing

First test locally with oppenssl's s_client subcommand. The output lines are long and boring, so I've truncated them with ....

=== grog@dereel (/dev/ttypj) ~ 90 -> openssl s_client -connect dereel.lemis.com:995
CONNECTED(00000003)
depth=0 /C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Messaging/CN=www.lemis.com...
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Messaging/CN=www.lemis.com...
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Messaging/CN=www.lemis.com...
verify error:num=21:unable to verify the first certificate
verify return:1
---
Certificate chain
 0 s:/C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Messaging/CN=www.lemis.com...
   i:/C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Certificate Authority/CN=www.lemis.com...
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDLjCCAhYCCQD7BOjvGplJaDANBgkqhkiG9w0BAQUFADCBoDELMAkGA1UEBhMC
...
Mr60l2nvWvp2x81I3NpdhFIWogTTq+A5NV0MVtKGD7eOz3Ab021cMQMWVZBoj7J5
Vrk=
-----END CERTIFICATE-----
subject=/C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Messaging/CN=www.lemis.com...
issuer=/C=AU/ST=VIC/L=Dereel/O=LEMIS (SA) Pty Ltd/OU=Certificate Authority...
---
No client certificate CA names sent
---
SSL handshake has read 980 bytes and written 340 bytes
---
New, TLSv1/SSLv3, Cipher is AES256-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol  : TLSv1
    Cipher    : AES256-SHA
    Session-ID: BAE4E4EF0A1CEA79C2BAA016601AB9A29A8B1114271FAB6F586C3D963E64...
    Session-ID-ctx:
    Master-Key: BDA30832F78979B8D1E321097EFF3618EAA98C2938DEB4830F0289901F07E5B5...
    Key-Arg   : None
    Start Time: 1216437472
    Timeout   : 300 (sec)
    Verify return code: 21 (unable to verify the first certificate)
---
+OK Qpopper (version 4.0.9) at dereel.lemis.com starting.  <7612.1216437472@dereel.lemis.com>
capa
+OK Capability list follows
TOP
USER
LOGIN-DELAY 0
EXPIRE NEVER
UIDL
RESP-CODES
AUTH-RESP-CODE
X-MANGLE
X-MACRO
X-LOCALTIME Sat, 19 Jul 2008 13:18:28 +1000
IMPLEMENTATION Qpopper-version-4.0.9
.
auth
+OK Supported SASL mechanisms:
X-NONE-SO-USE-APOP-OR-STLS
.
user grog
+OK Password required for grog.
pass This text echos
+OK grog has 428 visible messages (0 hidden) in 4507194 octets.
      

If this works, you're ready to try with Microsoft.

Configuring Microsoft “Outlook”

Start “Outlook” and select the menu sequence Tools -> E-mail Accounts. Add a new one or change an existing one (click on the images for larger versions):

Make sure that the box “Log on using Secure Password Authentication” is not ticked. Then select “More Settings...” and the “Advanced” Tab, and set the box “The server requires an encrypted connection (SSL)”. This will change the “Incoming Server” field (really the port number) from 110 (pop3) to 995 (pop3s).

Finally, test by selecting the button “Test Account Settings...” from the “E-mail Accounts” window. In my experience, it takes quite a while to finish, and when it does, it's not immediately obvious.