Preface
=======

Dovecot offers a lot of flexibility and some quite powerful options. Despite a lot of features, it is fairly easy to configure. This guide will concentrate primarily on getting Dovecot to use the client certificates for the authentication. It will also try to point out some of the flaws in related configuration options.

Software Requirements
=====================

For the purpose of this chapter it is assumed that a server machine has been supplied with pre-installed Debian Squeeze GNU/Linux distribution. During the (network) installation it is assumed that the standard task has been selected. It is also recommended to install the SSH server task for ease of administration.

The Dovecot IMAP package can be installed with:

```
? root
$ apt-get install dovecot-imapd
```

Issuing the Certificate
=======================

For the server side it's necessary to issue the following certificate:

```
End Entity Profile: Server
E-mail address: postmaster@example.com
CN, Common name: Example IMAP Server
O, Organization: Example Inc.
C, Country (ISO 3166): RS
DNS Name: mail.example.com
Certificate Profile: Example Server
CA: Example Server CA
Token: PEM file
```

Create the directory which will hold the certificates and keys on the destination server:

```
? root
$ mkdir /etc/dovecot/tls/
```

The private key should be placed into the following location:

```
# /etc/dovecot/tls/mail.example.com.key
```

Prepare the accompanying certificate file so that you have the server's certificate followed by the Example Server CA and Example Root CA certificates one after the another in the same file. Place the resulting file into location:

```
# /etc/dovecot/tls/mail.example.com.crt
```

Now set-up the file permissions:

```
? root
----BEGIN----$
chown -R root.root /etc/dovecot/tls/
chmod 755 /etc/dovecot/tls/
chmod 644 /etc/dovecot/tls/mail.example.com.crt
chmod 640 /etc/dovecot/tls/mail.example.com.key
-----END-----$
```

Configuring the Server
======================

This guide will be using a static layout for storing the mails of users. In order to differentiate between others users, a separate user account with accompanying group should be created:

```
? root
$ groupadd -g 5000 vmail
$ useradd -g vmail -u 5000 vmail -d /var/vmail -m
```

While we've generated the necessary private key and certificate, and set them up, it's still required to provide Dovecot with a trust anchor.

Unfortunately, Dovecot's configuration of trust anchor is implemented somewhat poorly. What you'll need is to create a file which will contain the CA certificates from the entire chain in PEM format (Example Root CA, Example Person CA), with each certificate followed by the appropriate CRL list (also supplied in a PEM format). The file should be placed into location:

```
# /etc/dovecot/tls/trust_chain.pem
```

Set-up the file permissions:

```
? root
$ chown root.root /etc/dovecot/tls/trust_chain.pem
$ chmod 640 /etc/dovecot/tls/trust_chain.pem
```

Create the dovecot configuration file:

```
@TODO: write it down
```

A small warning should be put forth with relation to the above configuration. Dovecot is able to extract the username from the client certificate, and use it afterwards for all the necessary look-ups related to where the mails will get stored to. Currently Dovecot is only able to use the fields located in the client certificate's *subject*, and it's not able to use the fields from the SAN.

If you've followed this guide through for the set-up of the X.509 infrastructures, you should recall that earlier the end entity profiles were set-up with e-mail address being supplied as a SAN instead as a part of a subject. This means that as of this writing it's not possible to actually let Dovecot extract the domain/mailbox name from the actual e-mail field with such a set-up. If you desire to do so, you might want to take into account adding the e-mail address to be part of the subject, and setting the *ssl_cert_username_field* option to *emailAddress*.

An alternative to the above approach is to actually perform a look-up in case of the *userdb* (either through LDAP/database server or some other means).

Since we'll be using client certificate for authentication, we won't require the password database. Dovecot requires at least one password database to be specified nevertheless. We'll handle this by enabling the PAM password database, but making sure that it always succeeds (since we perform the necessary checks with client certificate anyway). Create/replace the following file with:

```
# /etc/pam.d/dovecot
----BEGIN----
auth       sufficient    pam_permit.so
account  sufficient    pam_permit.so
-----END-----
```

Finally, you'll need to restart the Dovecot server to apply the changes:

```
? root
$ service dovecot restart
```

Testing the Connection
======================