ssl-guide.html 9.34 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5 6 7 8 9 10 11 12
<!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
13 14 15
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.
Matt Tucker's avatar
Matt Tucker committed
16
Unfortunately, the flexibility means there is no definitive mechanism
17 18
for configuring SSL security on all JVMs. You must consult the
documentation for your JVM in creating a valid keystore and truststore
Matt Tucker's avatar
Matt Tucker committed
19 20
and populating those with the SSL certificates needed for your
deployment. In this document, we will describe how use the standard JDK
Gaston Dombiak's avatar
Gaston Dombiak committed
21
1.5 tools to accomplish these tasks.
Matt Tucker's avatar
Matt Tucker committed
22 23 24 25 26 27 28
</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
29 30
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.
Matt Tucker's avatar
Matt Tucker committed
31 32 33 34 35
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
36 37 38 39
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
Matt Tucker's avatar
Matt Tucker committed
40
in-band. However, you may wish to require SSL authentication for
41 42
certain clients when security is especially important and the number
of clients connection to the server is relatively small.
Matt Tucker's avatar
Matt Tucker committed
43 44 45
</p>
<p>
Certificates attempt to guarantee that a particular party is who they
46 47 48
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.
Matt Tucker's avatar
Matt Tucker committed
49
Self-signed certificates encrypts the communication channel between
50 51 52
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
Matt Tucker's avatar
Matt Tucker committed
53 54 55 56 57 58
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
59 60 61 62
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
Matt Tucker's avatar
Matt Tucker committed
63
truststore (so that the certificate is trusted) you can be assured that
64
the SSL connection will only work between the client and the correct server.
Matt Tucker's avatar
Matt Tucker committed
65 66 67
</p>
<p>
For higher security deployments, you should get your certificate signed
68 69 70 71 72 73
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).
Matt Tucker's avatar
Matt Tucker committed
74
</p>
Gaston Dombiak's avatar
Gaston Dombiak committed
75
<h2>Sun JDK 1.5 security tools</h2>
Matt Tucker's avatar
Matt Tucker committed
76
<p>
Gaston Dombiak's avatar
Gaston Dombiak committed
77
The Sun JDK (version 1.5.x) ships with all the security tools you need
78 79 80 81 82 83 84
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.
Matt Tucker's avatar
Matt Tucker committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
</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;
114 115
for example, "server.com". Your user accounts will have addresses with
the format "user@server.com" like email addresses. We'll assume
Matt Tucker's avatar
Matt Tucker committed
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
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>.
136 137 138 139 140 141 142 143
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>
<p>If you later change the keystore password remember to change the entries'
password as well using the keytool:</p>

Gaston Dombiak's avatar
Gaston Dombiak committed
144
<p><tt>keytool -keypasswd -alias server.com -keystore keystore</tt>
Matt Tucker's avatar
Matt Tucker committed
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
</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>
Gaston Dombiak's avatar
Gaston Dombiak committed
190 191
Open the Jive Messenger Admin Console in your favorite
browser and add or change the following system properties:
Matt Tucker's avatar
Matt Tucker committed
192 193
</p>
<ul>
194 195
  <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
Matt Tucker's avatar
Matt Tucker committed
196
5223 for XMPP)</li>
197
  <li>xmpp.socket.ssl.storeType -- the store type used ("JKS" is
198 199
the Sun Java Keystore format used by the JDK keytool). If this property is 
not defined, Messenger will assume a value of "jks".</li>
200
  <li>xmpp.socket.ssl.keystore -- the location of the keystore file
Matt Tucker's avatar
Matt Tucker committed
201
relative to the <tt>MESSENGER_HOME</tt> root directory.</li>
202
  <li>xmpp.socket.ssl.keypass -- the keystore/key password you
Matt Tucker's avatar
Matt Tucker committed
203
changed in step 2.</li>
204
  <li>xmpp.socket.ssl.truststore -- leave blank to not use a
Matt Tucker's avatar
Matt Tucker committed
205 206
truststore, otherwise the location of the truststore file relative to
the <tt>MESSENGER_HOME</tt> root directory.</li>
207
  <li>xmpp.socket.ssl.trustpass -- the truststore/key password you
Matt Tucker's avatar
Matt Tucker committed
208 209
changed in step 5.</li>
</ul>
210
You will need to restart the server after you have modified any of the above system properties.
Gaston Dombiak's avatar
Gaston Dombiak committed
211
</body>
Matt Tucker's avatar
Matt Tucker committed
212
</html>