<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Openfire Connection Manager Module SSL Guide</title>
<link type="text/css" rel="stylesheet" href="style.css">
</head>
<body>
<a name="top"></a>
<h1>Openfire Connection Manager Module SSL Guide</h1>
<h2>Introduction</h2>
<p>
This document outlines how to customize the SSL support in the connection manager module.
<font color="red"><b>Important note:</b></font>
because the module ships with self-signed certificates, it will work out of the box without
installing your own certificate. However, most users will wish to user their own
certificates.</p>
<p>Connection managers is are modules that lie between clients and an XMPP server.
Therefore, connections with clients may be secured as well as connections with the server.
This document explains how to secure each part of the architecture.</p>
<p>The connection Manager module's SSL support is built using the standard Java security
SSL implementation (javax.net.ssl.SSLServerSocket). In this document, we will
describe how use the standard JDK 1.5 tools to accomplish these tasks.
</p>
<h2>Background</h2>
<p>
A server SSL connection uses two sets of certificates to secure the
connection. The first set is called a "keystore". The keystore contains
the keys and certificates for the connection manager. These security credentials
are used to prove to clients that the connection manager is legitimately operating
on behalf of a particular domain hosted by the server. You only need one key
entry and certificate in the keystore for each hosted domain in the server.
Keys are stored in the keystore under aliases. Each alias corresponds
to a domain name (e.g. "example.com").
</p>
<p>
The second set of certificates is called the "truststore" and is used
to verify that a client is legitimately operating on behalf of a
particular user or to verify that a server is legitimately operating
on behalf of a particular domain. By default, the truststore is filled
with certificates provided by Java 1.5 plus root certificates of cacert.org.
</p>
<p>
Certificates attempt to guarantee that a particular party is who they
claim to be. Certificates are trusted based on who signed the certificate.
If you only require light security, are deploying for internal use on
trusted networks, etc. you can use "self-signed" certificates.
Self-signed certificates encrypts the communication channel between
client and server. However the client must verify the legitimacy of the
self-signed certificate through some other channel. The most common client
reaction to a self-signed certificate is to ask the user whether
to trust the certificate, or to silently trust the certificate is
legitimate. Unfortunately, blindly accepting self-signed certificates
opens up the system to 'man-in-the-middle' attacks.
</p>
<p>
The advantage of a self-signed certificate is you can create them for
free which is great when cost is a major concern, or for testing and evaluation.
In addition, you can safely use a self-signed certificate if you can verify
that the certificate you're using is legitimate. So if a system administrator
creates a self-signed certificate, then personally installs it on a client's
truststore (so that the certificate is trusted) you can be assured that
the SSL connection will only work between the client and the correct server.
</p>
<p>
For higher security deployments, you should get your certificate signed
by a certificate authority (CA). Clients truststores will usually contain
the certificates of the major CA's and can verify that a CA has signed a
certificate. This chain of trust allows clients to trust certificate from
servers they've never interacted with before. Certificate signing is similar
to a public notary (with equivalent amounts of verification of identity,
record keeping, and costs).
</p>
<h2>Sun JDK 1.5 security tools</h2>
<p>
The Sun JDK (version 1.5.x) ships with all the security tools you need
to configure SSL with Connection Manager. The most important is the
<tt>keytool</tt> located in the <tt>JAVA_HOME/bin directory</tt> of the
JDK. Sun JVMs persist keystores and truststores on the filesystem as
encrypted files. The <tt>keytool</tt> is used to create, read, update,
and delete entries in these files. Connection Manager ships with a self-signed
"dummy" certificate designed for initial evaluation testing. You will need
to adjust the default configuration for most deployments.
</p>
<p>
In order to configure SSL on your connection manager you need complete the
following tasks:
</p>
<ol>
<li>Decide on your Openfire server's public domain. This is the domain that
users will connect to.</li>
<li>Create a self-signed SSL server certificate for your server
domain. Note: you may already have one if your Openfire server
domain matches an existing web domain with SSL.
If so, you can skip to step 4.</li>
<li>[Optional] Have a certificate authority (CA) certify the SSL
server certificate.
<ol style="list-style-type: lower-alpha;">
<li>Generate a certificate signing request (CSR).</li>
<li>Submit your CSR to a CA for signing.</li>
</ol>
</li>
<li>Import the server certificate into the keystore. Note: if you are
going to use a self-signed certificate
generated in step 2, the certificate is already imported and you can
skip this step.</li>
<li>Remove default certificates from the keystore.</li>
<li>Import client certificates into the truststore.</li>
<li>Adjust the Connection Manager configuration with proper keystore and
truststore settings.</li>
</ol>
<h3>1. Decide on a Server Domain</h3>
<p>
The Openfire server domain should match the host name of the connection manager;
for example, "example.com". Your user accounts will have addresses with
the format "user@example.com" like email addresses. We'll assume
the domain is "example.com" for the rest of the examples.
</p>
<h3>2. Create a self-signed server certificate</h3>
<p>
In order to create a self-signed server certificate go to the command
line and change directories to the <tt>resources/security</tt>
directory of your Openfire installation. You should see the default
<tt>keystore</tt> and <tt>truststore</tt> files. First, you should
change the default keystore
password:
</p>
<p><tt>keytool -storepasswd -keystore keystore</tt></p>
<p>
keytool will ask for the old password (by default it is <tt>changeit</tt>)
then the new password.
Now we'll create a certificate using the keytool:
</p>
<p><tt>keytool -genkey -keystore keystore -alias example.com</tt></p>
<p>
where you should substitute your server's name for <tt>example.com</tt>.
The keytool will ask for the store password, then several pieces of
information required for the certificate. Enter all the information but remember
to <b>complete with your server's name when asked for your first and last name</b>.
After you have entered all the required information, keytool will ask you to
verify the information and set a key password.
<b>You must use the same key password as the store password.</b> By default
you get this by simply hitting 'enter' when prompted for a key password.</p>
<p>If you later change the keystore password remember to change the entries'
password as well using the keytool:</p>
<p><tt>keytool -keypasswd -alias example.com -keystore keystore</tt>
</p>
<h3>3. Obtain a CA signed certificate</h3>
<p>
If you decide to get a CA signed certificate, you must first export the
certificate in the
standard CSR format. You can do this with the keytool:
</p>
<p><tt>keytool -certreq -keystore keystore -alias example.com -file
certificate_file</tt></p>
<p>
Where you should substitute your server's name for <tt>example.com</tt>
and the name of the
certificate file you wish to produce for <tt>certificate_file</tt>.
Submit the generated CSR to the CA and follow their instructions to get
it signed.
</p>
<h3>4. Import server certificates</h3>
<p>
If you had a CA sign your server certificate, or if you have an
existing SSL certificate,
you must import it using the keytool.
</p>
<p><tt>keytool -import -keystore keystore -alias example.com -file
signed_certificate_file</tt></p>
<p>
It is important that the alias not already have an associated key or
you'll receive an error.
</p>
<h3>5. Remove default certificates</h3>
<p>
After importing your certificate you must remove the default certificates
using the keytool.
</p>
<p><tt>keytool -delete -keystore keystore -alias rsa</tt></p>
<p><tt>keytool -delete -keystore keystore -alias dsa</tt></p>
<h3>6. Import client certificates</h3>
<p>
If you require clients to verify themselves using certificates, obtain
their certificates and import them into the truststore file rather than
the keystore. First, you should change the default truststore
password:
</p>
<p><tt>keytool -storepasswd -keystore truststore</tt></p>
<p>
keytool will ask for the old password (by default it is <tt>changeit</tt>)
then the new password.
Now import each certificate using the keytool:
</p>
<p><tt>keytool -import -keystore truststore -alias user_name -file
certificate_file</tt></p>
<h3>7. Configure the Connection Manager</h3>
<p>
Open the conf/manager.xml file in your favorite
editor and add or change the following system properties:
</p>
<ul>
<li>xmpp.socket.ssl.active -- set to 'true' to active SSL</li>
<li>xmpp.socket.ssl.port -- the port to use for SSL (default is
5223 for XMPP)</li>
<li>xmpp.socket.ssl.storeType -- the store type used ("JKS" is
the Sun Java Keystore format used by the JDK keytool). If this property is
not defined, Connection Manager will assume a value of "jks".</li>
<li>xmpp.socket.ssl.keystore -- the location of the keystore file
relative to your Connection Manager installation root directory. You can leave this property
blank to use the default keystore.</li>
<li>xmpp.socket.ssl.keypass -- the keystore/key password you
changed in step 2.</li>
<li>xmpp.socket.ssl.truststore -- leave blank to not use a
truststore, otherwise the location of the truststore file relative to
your Connection Manager installation root directory.</li>
<li>xmpp.socket.ssl.trustpass -- the truststore/key password you
changed in step 6.</li>
</ul>
You will need to restart the connection manager after you have modified any of the above system properties.
</body>
</html>
