ssl-guide.html 10.6 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2

Matt Tucker's avatar
Matt Tucker committed
3 4
<html>
<head>
5
<title>Openfire: SSL Guide</title>
6
<link type="text/css" rel="stylesheet" href="style.css">
Matt Tucker's avatar
Matt Tucker committed
7 8
</head>
<body>
9 10 11

<div id="pageContainer">

Matt Tucker's avatar
Matt Tucker committed
12
<a name="top"></a>
13 14 15 16 17 18 19 20 21 22 23

	<div id="pageHeader">
		<div id="logo"></div>
		<h1>SSL Guide</h1>
	</div>
	<div class="navigation">
		<a href="index.html">&laquo; Back to documentation index</a>
	</div>
	
	<div id="pageBody">
		
Matt Tucker's avatar
Matt Tucker committed
24 25
<h2>Introduction</h2>
<p>
26
This document outlines how to <b>manually</b> customize the SSL support in
27
Openfire. As of Openfire 3.2 certificate management can be performed from the
28 29
Admin Console. However, if needed you can still manually manage certificates
using JDK 1.5 tools.
30

31
<font color="red"><b>Important note:</b></font>
32 33
Once the setup process is completed Openfire will create self-signed certificates
for the assigned Openfire's domain. Most users should either get the created
34 35
certificates signed by a Certificate Authority or replace the created certificates
with your own certificates.</p>
36

37
<p>Openfire's SSL support is built using the standard Java security
38 39
SSL implementation (javax.net.ssl.SSLServerSocket). In this document, we will
describe how use the standard JDK 1.5 tools to accomplish these tasks.
Matt Tucker's avatar
Matt Tucker committed
40 41 42 43 44 45 46
</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
47 48
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
49
Keys are stored in the keystore under aliases. Each alias corresponds
Matt Tucker's avatar
Matt Tucker committed
50
to a domain name (e.g. "example.com").
Matt Tucker's avatar
Matt Tucker committed
51 52 53
</p>
<p>
The second set of certificates is called the "truststore" and is used
54 55 56 57
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
58
in-band. However, you may wish to require SSL authentication for
59 60
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
61 62 63
</p>
<p>
Certificates attempt to guarantee that a particular party is who they
64 65 66
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
67
Self-signed certificates encrypts the communication channel between
68 69 70
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
71 72 73
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.
74

Matt Tucker's avatar
Matt Tucker committed
75 76 77
</p>
<p>
The advantage of a self-signed certificate is you can create them for
78 79 80 81
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
82
truststore (so that the certificate is trusted) you can be assured that
83
the SSL connection will only work between the client and the correct server.
Matt Tucker's avatar
Matt Tucker committed
84 85 86
</p>
<p>
For higher security deployments, you should get your certificate signed
87 88 89 90 91 92
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
93
</p>
Gaston Dombiak's avatar
Gaston Dombiak committed
94
<h2>Sun JDK 1.5 security tools</h2>
Matt Tucker's avatar
Matt Tucker committed
95
<p>
Gaston Dombiak's avatar
Gaston Dombiak committed
96
The Sun JDK (version 1.5.x) ships with all the security tools you need
97
to configure SSL with Openfire. The most important is the
98 99 100
<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,
101
and delete entries in these files. Openfire ships with a self-signed
102 103
"dummy" certificate designed for initial evaluation testing. You will need
to adjust the default configuration for most deployments.
104

Matt Tucker's avatar
Matt Tucker committed
105 106 107 108 109 110
</p>
<p>
In order to configure SSL on your server you need complete the
following tasks:
</p>
<ol>
111
  <li>Decide on your Openfire server's domain.</li>
Matt Tucker's avatar
Matt Tucker committed
112
  <li>Create a self-signed SSL server certificate for your server
113
domain. Note: you may already have one if your Openfire server
Matt Tucker's avatar
Matt Tucker committed
114 115 116 117 118 119
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>
120

Matt Tucker's avatar
Matt Tucker committed
121 122 123 124 125 126 127
      <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>
128
  <li>Remove default certificates from the keystore.</li>
Matt Tucker's avatar
Matt Tucker committed
129
  <li>Import client certificates into the truststore.</li>
130
  <li>Adjust the Openfire configuration with proper keystore and
Matt Tucker's avatar
Matt Tucker committed
131
truststore settings.</li>
132

Matt Tucker's avatar
Matt Tucker committed
133
</ol>
Matt Tucker's avatar
Matt Tucker committed
134
<h3>1. Decide on a Server Domain</h3>
Matt Tucker's avatar
Matt Tucker committed
135
<p>
136
The Openfire server domain should match the host name of the server;
Matt Tucker's avatar
Matt Tucker committed
137 138 139
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.
Matt Tucker's avatar
Matt Tucker committed
140
</p>
Matt Tucker's avatar
Matt Tucker committed
141
<h3>2. Create a self-signed server certificate</h3>
Matt Tucker's avatar
Matt Tucker committed
142 143
<p>
In order to create a self-signed server certificate go to the command
Matt Tucker's avatar
Matt Tucker committed
144
line and change directories to the <tt>resources/security</tt>
145
directory of your Openfire installation. You should see the default
Matt Tucker's avatar
Matt Tucker committed
146 147 148
<tt>keystore</tt> and <tt>truststore</tt> files. First, you should
change the default keystore
password:
149

Matt Tucker's avatar
Matt Tucker committed
150 151 152 153 154 155 156
</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>
Matt Tucker's avatar
Matt Tucker committed
157
<p><tt>keytool -genkey -keystore keystore -alias example.com</tt></p>
Matt Tucker's avatar
Matt Tucker committed
158
<p>
Matt Tucker's avatar
Matt Tucker committed
159
where you should substitute your server's name for <tt>example.com</tt>.
160
The keytool will ask for the store password, then several pieces of
161 162 163 164
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.
165 166
<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>
167

168 169 170
<p>If you later change the keystore password remember to change the entries'
password as well using the keytool:</p>

Matt Tucker's avatar
Matt Tucker committed
171
<p><tt>keytool -keypasswd -alias example.com -keystore keystore</tt>
Matt Tucker's avatar
Matt Tucker committed
172
</p>
173 174 175 176 177 178 179

<p>Keytool will create certificates using the DSA algorithm by default. Some clients
expect the server to have RSA certificates or they will fail to use TLS/SSL. Therefore,
it is a good idea to also create RSA certificates in your keystore. To create
certificates with the RSA algorithm you need to specify the algorithm to use like this:</p>
<p><tt>keytool -genkey -keystore keystore -alias example.com -keyalg RSA </tt></p>

Matt Tucker's avatar
Matt Tucker committed
180
<h3>3. Obtain a CA signed certificate</h3>
Matt Tucker's avatar
Matt Tucker committed
181 182 183 184 185
<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>
Matt Tucker's avatar
Matt Tucker committed
186
<p><tt>keytool -certreq -keystore keystore -alias example.com -file
Matt Tucker's avatar
Matt Tucker committed
187 188
certificate_file</tt></p>
<p>
Matt Tucker's avatar
Matt Tucker committed
189
Where you should substitute your server's name for <tt>example.com</tt>
190

Matt Tucker's avatar
Matt Tucker committed
191 192 193 194 195
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>
Matt Tucker's avatar
Matt Tucker committed
196
<h3>4. Import server certificates</h3>
Matt Tucker's avatar
Matt Tucker committed
197 198 199 200 201
<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>
Matt Tucker's avatar
Matt Tucker committed
202
<p><tt>keytool -import -keystore keystore -alias example.com -file
Matt Tucker's avatar
Matt Tucker committed
203 204 205 206 207
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>
208 209
<h3>5. Remove default certificates</h3>
<p>
210

211 212 213 214 215 216
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>
Matt Tucker's avatar
Matt Tucker committed
217 218 219 220 221 222 223 224 225 226 227
<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:
228

Matt Tucker's avatar
Matt Tucker committed
229 230 231
</p>
<p><tt>keytool -import -keystore truststore -alias user_name -file
certificate_file</tt></p>
232
<h3>7. Configure Openfire</h3>
Matt Tucker's avatar
Matt Tucker committed
233
<p>
234
Open the Openfire Admin Console in your favorite
Gaston Dombiak's avatar
Gaston Dombiak committed
235
browser and add or change the following system properties:
Matt Tucker's avatar
Matt Tucker committed
236 237
</p>
<ul>
238 239
  <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
240
5223 for XMPP)</li>
241
  <li>xmpp.socket.ssl.storeType -- the store type used ("JKS" is
242
the Sun Java Keystore format used by the JDK keytool). If this property is 
243
not defined, Openfire will assume a value of "jks".</li>
244

245
  <li>xmpp.socket.ssl.keystore -- the location of the keystore file
246
relative to your Openfire installation root directory. You can leave this property
Matt Tucker's avatar
Matt Tucker committed
247
blank to use the default keystore.</li>
248
  <li>xmpp.socket.ssl.keypass -- the keystore/key password you
Matt Tucker's avatar
Matt Tucker committed
249
changed in step 2.</li>
250
  <li>xmpp.socket.ssl.truststore -- leave blank to not use a
Matt Tucker's avatar
Matt Tucker committed
251
truststore, otherwise the location of the truststore file relative to
252
your Openfire installation root directory.</li>
253
  <li>xmpp.socket.ssl.trustpass -- the truststore/key password you
254
changed in step 6.</li>
Matt Tucker's avatar
Matt Tucker committed
255
</ul>
256
You will need to restart the server after you have modified any of the above system properties.
257 258 259 260 261

	</div>

</div>

Gaston Dombiak's avatar
Gaston Dombiak committed
262
</body>
Matt Tucker's avatar
Matt Tucker committed
263
</html>