Securing IMAP | The qmail Handbook

< Free Open Study >

IMAP traffic is unencrypted, and like POP3, the protocol requires authentication: Users must identify themselves and prove their identity. IMAP's default authentication, like POP3's, is username/password-based. IMAP can be secured much like POP3: by wrapping the entire dialogue in SSL or using a challenge/response authentication mechanism called CRAM-MD5 (Challenge-Response Authentication Mechanism using Message Digest algorithm 5). However, IMAP has also been extended with a STARTTLS command that can be used to enable transport layer security (TLS) after connecting to the normal, unsecured IMAP service.

Courier-IMAP includes support for all three of these mechanisms: SSL wrapping, STARTTLS, and CRAM-MD5.

Which of these methods you use, if any, depends on your needs and the security mechanisms implemented in the MUAs you support.

Wrapping IMAP with SSL

Courier-IMAP will automatically include support for SSL wrapping and STARTTLS if it finds the SSL include files and libraries during the build process.

Alternatively, an add-on SSL wrapper can be used to proxy any IMAP service. Connections to port 993, the secure IMAP port, are accepted by the SSL wrapper, which in turn opens connections to port 143, the non-secure IMAP port. The SSL wrapper acts as a go-between between the MUAs and the non-secure IMAP service.

Enabling Courier-IMAP's SSL Wrapper

If you've installed Courier-IMAP on your system, and the SSL libraries and include files were located by the compiler during the build, the program /usr/lib/courier-imap/bin/couriertls should have been created. If this file doesn't exist, you'll need to rebuild Courier-IMAP, specifying the location of your SSL libraries and include files. See the INSTALL file for details.

If the couriertls program was created, you can enable the SSL-wrapped IMAP service:

Edit /usr/lib/courier-imap/etc/imapd-ssl, locate the following settings, and adjust them accordingly:
```
 IMAPDSSLSTART=YES IMAPDSTARTTLS=NO TLS_CERTFILE=/var/qmail/control/servercert.pem 
```
If you haven't already placed a server certificate in /var/qmail/control/servercert.pem, do that now. The /usr/lib/courier-imap/share/mkimapdcert script will create a self-signed certificate and place it in /usr/lib/courier-imap/share/imapd.pem. You can either move that to /var/qmail/control/servercert.pem or return the TLS_CERTFILE setting to its default value in /usr/lib/courier-imap/etc/imapd-ssl.

Add the following to the start section of qmailctl:

 /usr/lib/courier-imap/libexec/imapd-ssl.rc start

Add the following to the stop section of qmailctl:

 /usr/lib/courier-imap/libexec/imapd-ssl.rc stop

Manually start the secure IMAP service:

 # /usr/lib/courier-imap/libexec/imapd-ssl.rc start #

Use a secure IMAP capable MUA to test the service. For example, using fetchmail with the —ssl option:

 $ fetchmail -v —ssl fetchmail: 5.7.4 querying mash (protocol IMAP) at Sun 12 Aug 2001 08:47:41 AM EDT fetchmail: Issuer Organization: Example, Inc fetchmail: Issuer CommonName: dolphin.example.com fetchmail: Server CommonName: dolphin fetchmail: Issuer Organization: Example, Inc fetchmail: Issuer CommonName: dolphin.example.com fetchmail: Server CommonName: dolphin fetchmail: IMAP< * OK Courier-IMAP ready. Copyright 1998-2001 Double Precision, Inc.  See COPYING for distribution information fetchmail: IMAP> A0001 CAPABILITY fetchmail: IMAP< * CAPABILITY IMAP4rev1 CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT AUTH=PLAIN ...remainder of IMAP dialogue

As you can see from the verbose output, the session is successfully established using SSL.

Proxy-Wrapping an IMAP Service

If you have an IMAP service running and Stunnel, ucspi-tcp, and daemontools are installed, setting up a proxy-wrapped secure IMAP service is straightforward:

Create a /var/qmail/supervise/imapsd directory with a log subdirectory:
```
 # mkdir -p /var/qmail/supervise/imapsd/log # 
```

Create the /var/qmail/supervise/imapsd/run script:

 #!/bin/sh MAXIMAPSD='head -1 /var/qmail/control/concurrencyimaps' exec /usr/local/bin/softlimit -m 3000000 \    /usr/local/bin/tcpserver -v -R -H -l 0 -x /etc/tcp.imaps.cdb -c "$MAXIMAPSD" \         0 993 /usr/local/sbin/stunnel -f -p /usr/local/etc/stunnel.pem \         -r 143 2>&1

Note

concurrencyimaps is a nonstandard control file. Only the previous imapsd/run script uses it. The first line of the file should contain a number, which is the maximum number of simultaneous secure IMAP sessions that tcpserver allows.

In this case, stunnel is told to proxy the regular IMAP service using –r 143.

Create the /var/qmail/supervise/imapsd/log/run script:

 #!/bin/sh exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog \   t /var/log/qmail/imapds

Create /var/qmail/control/concurrencyimaps, in this example, limiting simultaneous secure IMAP connections to 20:
```
 # echo 20 > /var/qmail/control/concurrencyimaps # 
```
Create the secure IMAP access database. The file /etc/tcp.imaps is the human-readable version of the IMAP access database. It's analogous to the SMTP access database in /etc/tcp.smtp set up in Chapter 2, "Installing qmail." The tcprules command is used to convert the human-readable version into a machine-readable version, /etc/tcp.imaps.cdb. For example, to restrict access to hosts on the local network, 192.168.x.x, and the local host, you would create /etc/tcp.imaps, using your text editor, containing:
```
 192.168.:allow 127.:allow :deny 
```

Set up the log directory and permissions on the run scripts, and link the service into /service:

 # chmod +t /var/qmail/supervise/imaps # mkdir /var/log/qmail/imaps # chown qmaill /var/log/qmail/imaps # chmod 755 /var/qmail/supervise/imaps/run # chmod 755 /var/qmail/supervise/imaps/log/run # ln -s /var/qmail/supervise/imaps /service #

Add the following to qmailctl's start section:

 if svok /service/imaps ; then     svc -u /service/imaps else     echo imaps supervise not running fi

Add the following to qmailctl's stop section:
```
 echo "  imaps" svc -d /service/imaps 
```

Add the following to qmailctl's stat section:

 svstat /service/imaps svstat /service/imaps/log

Add the following to qmailctl's start section:

 if svok /service/uw-imap ; then     svc -u /service/uw-imap else     echo uw-imap service not running fi

Add the following to qmailctl's stop section:
```
 echo "  imaps" svc -d /service/imaps 
```

Add the following to qmailctl's stat section:

 svstat /service/imaps svstat /service/imaps/log

Add the following to qmailctl's pause section:

 echo "Pausing imaps" svc -p /service/imaps

Add the following to qmailctl's cont section:

 echo "Continuing imaps" svc -c /service/imaps

Add the following to qmailctl's restart section:

 echo "* Restarting imaps." svc -t /service/imaps

Add the following to qmailctl's cdb section:

 tcprules /etc/tcp.imaps.cdb /etc/tcp.imaps.tmp < /etc/tcp.imaps chmod 644 /etc/tcp.imaps.cdb echo "Reloaded /etc/tcp.imaps."

Build /etc/tcp.imaps.cdb. For example:

 # qmailctl cdb Reloaded /etc/tcp.smtp. Reloaded /etc/tcp.imap. Reloaded /etc/tcp.imaps. #

Use a secure IMAP capable MUA to test the service. See step 6 in the "Enabling Courier-IMAP's SSL Wrapper" section for an example.

Using CRAM-MD5 Authentication

As with APOP authentication, enabling CRAM-MD5 authentication is specific to the particular IMAP server being used.

The Courier-IMAP INSTALL provides an overview of the procedure for enabling CRAM-MD5 authentication, but it's very involved and recommended only for people who "are comfortable with, and fully understand how Courier-IMAP works in general."

With the UW-IMAP server, CRAM-MD5 support is installed automatically and enabled by setting up a CRAM-MD5 authentication database. The database is stored in /etc/cram-md5.pwd and contains entries in this format:

 username<TAB>password

For example, if user martha's IMAP password is Staunt0n, her entry would look like this:

 martha  Staunt0n

Because the CRAM-MD5 authentication database contains unencrypted passwords, it must be carefully protected. It should be owned by root and readable only by the owner:

 # chown root /etc/cram-md5.pwd # chmod 400 /etc/cram-md5.pwd #

Caution

When CRAM-MD5 authentication is enabled by the creation of the authentication database, the IMAP server will also use the CRAM-MD5 passwords for LOGIN authentication.

After installing the authentication database, test CRAM-MD5 authentication using a compatible MUA. For example, using fetchmail, after updating .fetch-mailrc with the CRAM-MD5 password, yields something like this:

 $ fetchmail -v fetchmail: 5.7.4 querying mash (protocol IMAP) at Sun 12 Aug 2001 11:13:47 AM EDT fetchmail: IMAP< * OK [CAPABILITY IMAP4 IMAP4REV1 LOGIN-REFERRALS AUTH=CRAM-MD5 AUTH=LOGIN] dolphin.example.com IMAP4rev1 2000.287 at Sun, 12 Aug 2001 11:14:07 - 0400 (EDT) fetchmail: IMAP> A0001 CAPABILITY fetchmail: IMAP< * CAPABILITY IMAP4 IMAP4REV1 NAMESPACE IDLE MAILBOX-REFERRALS SCAN SORT THREAD=REFERENCES THREAD=ORDEREDSUBJECT MULTIAPPEND LOGIN-REFERRALS AUTH=CRAM-MD5 AUTH=LOGIN fetchmail: IMAP< A0001 OK CAPABILITY completed fetchmail: IMAP> A0002 AUTHENTICATE CRAM-MD5 fetchmail: IMAP< + PDI0OTEwLjk5NzYyOTI0N0BtYXNoLnNpbGw+ fetchmail: IMAP> dGVzdCA1NjU3ZjM4OTI0ZjdiYjQ2MGFlYmNiMDcxZmM5OTJjOQ== fetchmail: IMAP< * CAPABILITY IMAP4 IMAP4REV1 NAMESPACE IDLE MAILBOX-REFERRALS SCAN SORT THREAD=REFERENCES THREAD=ORDEREDSUBJECT MULTIAPPEND fetchmail: IMAP< A0002 OK AUTHENTICATE completed ...remainder of IMAP session...

As you can see, authentication used CRAM-MD5 successfully.

< Free Open Study >