CS161 Programming Assignment 4: Secure IMAP Client

1) Preliminaries

Questions: cs161tas@cs.brown.edu
Due date: Monday, November 21st, 11:59pm.

2) CS161 Environment Setup

Add this line to your shell startup scripts:

  source /course/cs161/startups/cs161student

3) Introduction

Your fifth programming assignment is to update your IMAP client to communicate over TLS (SSL, basically).

As a reminder, the IMAP protocol is described in RFC 3501. In this assignment, we will be particularly interested in the STARTTLS command. In general, to run an existing protocol on top of TLS, two techniques are used. Either a separate port is used for TLS connections (this is how https works), or a way of switching into TLS from the unecrypted channel is provided. STARTTLS provides this switch for IMAP.

You will want to use the SSLEngine class to perform the SSL handshake and to do the heavy lifting once you've read input from a non-blocking socket, or are ready to write a command.

4) Assignment Specification

  1. You should provide a mechanism that allows your client to run IMAP over SSL. Your client should be capable of initiating an SSL connection using STARTTLS or by using a distinguished port.
  2. Your client should check that the certificate it is presented matches the hostname it is connecting to.
  3. You will be connecting to IMAP servers with self-signed certificates. You will need to implement an X509TrustManager to accept these certificates; additionally, your client must allow the user to specify that you trust certain certificates. (For example, by providing a list of hashes for each certificate that the user trusts.) The Java SSL implementation has its own reference guide explaining how to create your own X509TrustManager.
  4. You should document how you have extended your interface to allow users to to specify how to use SSL (assume that the port is SSL, or use STARTTLS) in a README.
  5. Use your client in batch mode to time a simple operation in both SSL and plain-text mode.

5) Testing

We are still running IMAP servers for you to test against on pythagoras.ilab.cs.brown.edu (with your department userid as user) and anonymous.cs.brown.edu (user "joe"). These servers support the STARTTLS command on port 143. In addition, each server is also listening for direct SSL connections, on port 993.

6) Support Code

Obviously, you should start with your existing IMAP client.

7) Submitting your code

To submit your code, first make sure your source files reside in a "ssl/" directory. Run the following script from the parent directory of "ssl/" to hand in:
    /course/cs161/bin/cs161_handin ssl
Please contact the TAs if you have problems submitting. For your own sanity, don't leave your submission until the minute before the deadline.

8) Grading scheme

Your code will be graded on the following factors (and their weights).

Documentation and code legibility: 20%
Functionality (handshake, non-blocking, error reporting, etc): 50%
Robustness (malicious input, corner cases, etc): 30%