Debugging SSL IMAP connections

Encrypted IMAP is a good thing for general purpose use. However, it makes it impossible to put a packet sniffer between the client and the remote host to figure out what's going on in the connection; this is especially hard when using PHP's IMAP library, which doesn't have a "debug" mode.

However, there is a way: by setting up an "IMAP proxy", you can catch the transaction between the unencrypted proxy and the final client, and the data between the proxy and the server can remain encrypted.

How to set up the IMAP proxy

I had success with the perdition IMAP proxy.  http://www.vergenet.net/linux/perdition/

For my setup, I installed it from the Debian package - the Etch version (1.17-7etch), but others should work.

In /etc/perdition/perdition.conf, have the following settings enabled. (By default all settings are commented out, so you can just add these lines to the bottom of the config file - changing your outgoing server to the destination encrypted server):

bind_address 127.0.0.1
listen_port 144
protocol IMAP4
outgoing_port 993
outgoing_server imap.gmail.com
ssl_mode ssl_outgoing
ssl_ca_accept_self_signed
ssl_cert_accept_self_signed
ssl_cert_accept_expired
ssl_cert_accept_not_yet_valid
ssl_no_cert_verify
ssl_no_cn_verify

You can then start the perdition daemon, in Debian, with /etc/init.d/perdition start. If you want to check that it worked properly, execute the following command:

telnet localhost 144

And you should see

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
* OK IMAP4 Ready localhost 0001c961

Hit CTRL+SHIFT+], and then type q and enter to quit telnet.

Note that I set the local port to 144 - my server has an ordinary dovecot IMAP server running on port 143, so I can run the proxy alongside it for GMail.

Configuring Lichen to use the Proxy

In lichen-config.php:

$IMAP_SERVER = "localhost";
$IMAP_PORT   = 144;

You will also need to set other settings as appropriate for SMTP (if you're using it), and folder names and so forth.

Debugging with the Proxy

Now that the proxy is set up and configured, it is time to capture the transaction. On the server that is running Lichen and the proxy, use the popular packet sniffer "wireshark" (or ethereal, if you have an old version).

In Capture -> Options, set up the dialog as shown below:

The critical settings are the capture filter ('tcp port 144'), and the interface - it must be 'lo'. For niceness, you can check the three checkboxes in "Display Options".

Once setup, click start.

Then attempt to login to Lichen. Packets will start to show up in the capture window. When the login has completed (or failed, as the case may be), you can stop capturing (on the toolbar), and begin to analyze it.

If we've asked, it can be really handy if you send the whole capture file to us - you can save it with File -> Save As, and just save it as the default format.

CAUTION: YOUR PASSWORD WILL BE IN THE CAPTURE IN PLAIN TEXT. REPLACE IT BY EDITING THE DUMP FILE WITH A HEX EDITOR BEFORE SENDING IT TO US - BE SURE NOT TO CHANGE THE SIZE OF THE FILE AND ONLY REPLACE CHARACTERS. YOUR PASSWORD IS LIKELY TO APPEAR MULTIPLE TIMES IN THE DUMP. We will not use any passwords that accidentally get sent to us, but just don't do it'''

Alternately, you can use Wiresharks "Follow TCP stream" feature to get a view of what happened, and if we ask, you can send that to us. Again, note that your password and username are in the output in plain text, so you'll want to redact that first! (The line will be LOGIN <username> <password>). To get the image I've shown below, click on the first packet in the capture, and then go to Analyze -> Follow TCP Stream.