This document explains how to enable James 2.1 services to use Transport Layer Security (TLS) for encrypted client-server communication.

Making TLS/SSL Server Sockets Available Inside James

James uses the Sun Java Secure Sockets Extension (JSSE) infrastructure to provide TLS/SSL sockets. JSSE comes packaged with several vendor Java distributions (i.e. Sun Java 1.4.x, IBM Java 1.3.x). For these distributions, please follow the vendor provided instructions for configuring the JVM to use JSSE services. If you are using a Java distribution that does not include JSSE as part of the distribution you will need to download the JSSE package separately. It can be obtained from here. Please follow Sun's instructions for installation and configuration of JSSE. In either case, you will need to statically define a JSSE TLS provider. In general, this is the default installation. Once you've installed JSSE, James still needs to be configured to take advantage of the JSSE functionality.

Certificate Keystores

To use TLS/SSL inside James you will need a certificate keystore.

Configuring the Server Socket Factory

The out of the box configuration file contains a template for the SSL configuration in place. Specifically, in the sockets block, under the server-sockets element, there is a commented out factory with the name "ssl". The first step to configuring the server socket factory is uncommenting out this element. The factory element contains several children. Of these, it should only be necessary to adjust two or three children. The required file element specifies the location of the keystore to be used by the factory. This is specified as a file path using Unix-style formatting. The path is taken to be relative to the apps/james/ subdirectory of the application installation directory unless an absolute path is specified. The password element should be set to the keystore password. This password should have been specified when the keystore was created, and it is required to open the keystore. This value is required. Finally, it may be necessary to adjust the type element. This element can take on any keystore type supported by the JSSE provider being used (see the JSSE documentation for details). The out of the box configuration specifies JKS (Java Keystore). The remaining children should not need to be deleted or adjusted.

Configuring a Service to Use TLS

Each of the services - SMTP, POP3, NNTP, and RemoteManager - supports use of TLS. Each of these services has an optional boolean configuration element useTLS which is used to toggle use of TLS for the service. When this value is set to true, that particular service will use the "ssl" server socket factory to spawn server sockets.

Verifying a TLS-enabled James Service

After you've configured a particular service to use TLS/SSL connections, the service port should no longer accept unencrypted TCP/IP connections. This can be tested by using a telnet client to directly connect to the service port. The telnet connection should simply hang until the client times out. To validate that the port is properly accepting SSL connections an SSL client can be used to open a connection to the service port. One such client is OpenSSL, available from the OpenSSL web site. Follow the instructions provided with the SSL client to create a connection to the service port. Upon connection, the usual service greeting should appear.