<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Jive Messenger SSL Guide</title>
  <link type="text/css" rel="stylesheet" href="style.css">
</head>
<body>
<a name="top"></a>
<h1>Jive Messenger SSL Guide</h1>
<h2>Introduction</h2>
<p>
This document outlines how to configure your SSL setup. Jive
Messenger's SSL support
is built using the standard Java security SSL implementation
(javax.net.ssl.SSLServerSocket).
Java security allows implementations of the JVM flexibility in how
security is implemented.
Unfortunately, the flexibility means there is no definitive mechanism
for configuring SSL security on
all JVMs. You must consult the documentation for your JVM in creating a
valid keystore and truststore
and populating those with the SSL certificates needed for your
deployment. In this document, we will describe how use the standard JDK
1.4 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 server. These security credentials
are used to prove to clients that the server is legitimately operating
on behalf of a particular domain.
If your server will only need to act as one domain, you only need one
key entry and certificate in the keystore.
Keys are stored in the keystore under aliases. Each alias corresponds
to a domain name (e.g. "server.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. In the vast majority of
cases, the truststore is empty and the server
will not attempt to validate client connections using SSL. Instead, the
XMPP authentication process verifies users
in-band. However, you may wish to require SSL authentication for
certain clients when security is especially
important and the number of clients connection to the server is
relatively small.
</p>
<p>
Certificates attempt to guarantee that a particular party is who they
claim to be.
Certificates are trusted based on who signed the certifcate. 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.4 security tools</h2>
<p>
The Sun JDK (version 1.4.x) ships with all the security tools you need
to configure SSL with Jive
Messenger. 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. Jive Messenger
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 server you need complete the
following tasks:
</p>
<ol>
  <li>Decide on your Jive Messenger server's domain.</li>
  <li>Create a self-signed SSL server certificate for your server
domain. Note: you may already have one if your Jive Messenger 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>Import client certificates into the truststore.</li>
  <li>Adjust the Messenger configuration with proper keystore and
truststore settings.</li>
</ol>
<h3>1 Decide on a Server Domain</h3>
<p>
The Messenger server domain should match the host name of the server;
for example, "server.com". Your
user accounts will have addresses with the format "user@server.com"
like email addresses. We'll assume
the domain is "server.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>MESSENGER_HOME/security</tt>
directory. 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 server.com</tt></p>
<p>
where you should substitute your server's name for <tt>server.com</tt>.
The keytool will
ask for the store password, then several pieces of information required
for the certificate.
Enter all the information and the 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>
<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 server.com -file
certificate_file</tt></p>
<p>
Where you should substitute your server's name for <tt>server.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 server.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 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>6 Configure Messenger</h3>
<p>
Open the Messenger configuration file <tt>MESSENGER_HOME/config/jive-messenger.xml</tt>
in your favorite
editor and change the following settings:
</p>
<ul>
  <li>jive.xmpp.socket.ssl.active - set to 'true' to active SSL</li>
  <li>jive.xmpp.socket.ssl.port - the port to use for SSL (default is
5223 for XMPP)</li>
  <li>jive.xmpp.socket.ssl.storeType - the store type used ("JKS" is
the Sun Java Keystore format used by the JDK keytool).</li>
  <li>jive.xmpp.socket.ssl.keystore - The location of the keystore file
relative to the <tt>MESSENGER_HOME</tt> root directory.</li>
  <li>jive.xmpp.socket.ssl.keypass - The keystore/key password you
changed in step 2.</li>
  <li>jive.xmpp.socket.ssl.truststore - Leave blank to not use a
truststore, otherwise the location of the truststore file relative to
the <tt>MESSENGER_HOME</tt> root directory.</li>
  <li>jive.xmpp.socket.ssl.trustpass - The truststore/key password you
changed in step 5.</li>
</ul>
<p>
Below is a sample set up with no truststore.
</p>
<pre><code>
&lt;jive&gt;
  &lt;xmpp&gt;
    &lt;socket&gt;
      &lt;ssl&gt;
        &lt;active&gt;true&lt;/active&gt;
        &lt;port&gt;5223&lt;/port&gt;
        &lt;storeType&gt;JKS&lt;/storeType&gt;
        &lt;keystore&gt;security/keystore&lt;/keystore&gt;
        &lt;keypass&gt;changeit&lt;/keypass&gt;
        &lt;truststore/&gt;
        &lt;trustpass/&gt;
      &lt;/ssl&gt;
    &lt;/socket&gt;
  &lt;/xmpp&gt;
&lt;/jive&gt;
</code></pre></body>
</html>