<!--
  ~ Copyright 2005-2007 WSO2, Inc. (http://wso2.com)
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<html xmlns="http://www.w3.org/1999/xhtml">
<body>
<p>[<a
href="http://dist.wso2.org/products/wsas/java/@wso2wsas_version@">Download</a>]
| [<a href="index_docs.html">Documentation Home</a>] | [<a
href="release_notes.html">Release Note</a>]</p>
<h1>Change the WSO2 WSAS Crypto Keys</h1>

<p>WSO2 WSAS  uses a key pair to enable HTTPS and to secure the user passwords
within it.</p>

<p>When you use WSO2 WSAS in production, it is <strong>strongly</strong>
recommended that you change the default keys that are shipped with it.</p>

<h3>Step 1: Use the keytool utility available with the JDK to create a
keystore containing the new keypair</h3>

<p>It should be noted that the RSA algorithm must be used to generate the
keypair and the alias of it must be "wso2wsas". The following command can be
used to create the above keystore.</p>
<pre>$ keytool -genkey -alias wso2wsas -keyalg RSA -keystore wso2wsas.jks -storepass wso2wsas</pre>

<p>This will prompt a series of questions as shown below:</p>
<pre>What is your first and last name?
  [Unknown]:  John Smith
What is the name of your organizational unit?
  [Unknown]:  Accounts
What is the name of your organization?
  [Unknown]:  ABC
What is the name of your City or Locality?
  [Unknown]:  Colombo
What is the name of your State or Province?
  [Unknown]:  Western
What is the two-letter country code for this unit?
  [Unknown]:  LK
Is CN=John Smith, OU=Accounts, O=ABC, L=Colombo, ST=Western, C=LK correct?
  [no]:  yes

Enter key password for &lt;tungsten&gt;
    (RETURN if same as keystore password):</pre>

<p>Now you will see a file with the name "wso2wsas.jks" created in the
location from which you executed the above command.</p>

<p>Now you can simply replace the WSO2WSAS_HOME/conf/wso2wsas.jks with this
new wso2wsas.jks file that you just created.</p>

<h3>Step 2: Reset the passwords of the users</h3>

<p>Since the keypair is used to secure the passwords of the WSO2 WSAS users
as well, we have to reset the passwords of all the users.</p>

<p>You <strong>must</strong> use the chpasswd utility provided with WSO2 WSAS
to reset the passwords.</p>
Please refer to the <a href="tools/change_passwd.html">chpasswd
documentation</a> and make sure you set the password of the "admin" user
first.

<h3>MISC: Changing the keystore name/location or keystore/key password(s)</h3>

<p>If you want to change the keystore file name, location, keystore password,
or the key password,</p>

<h4>Running in Standalone Mode</h4>
<ul>
  <li>Create your keystore</li>
  <li>Update the "Security settings" section of the
    WSO2WSAS_HOME/conf/server.xml
    <ul>
      <li>Full path to the keystore - Security/Keystore/Location</li>
      <li>Keystore password - Security/Keystore/Password</li>
      <li>Private key password - Security/Keystore/KeyPassword</li>
    </ul>
  </li>
</ul>

<h4>Running in a Servlet Container</h4>
<ul>
  <li>Create your keystore.</li>
  <li>Update the "Security settings" section of the
    WSO2WSAS_HOME/conf/server.xml
    <ul>
      <li>Full path to the keystore - Security/Keystore/Location</li>
      <li>Keystore password - Security/Keystore/Password</li>
      <li>Private key password - Security/Keystore/KeyPassword</li>
    </ul>
  </li>

  <p><strong>JBoss application server</strong></p>
  <li>Update the "SSL/TLS Connector configuration" section of the
    jboss_home/server/default/deploy/jbossweb-tomcat50.sar/server.xml
    <ul>
      <li>Full path to the keystore - keystoreFile</li>
      <li>Keystore password - keystorePass</li>
    </ul>
  </li>

  <p><strong>Apache Tomcat server</strong></p>
  <li>Update the "Define a non-SSL HTTP/1.1 Connector on port 9443" section
    of the catalina_home/conf/server.xml
    <ul>
      <li>Full path to the keystore - keystoreFile</li>
      <li>Keystore password - keystorePass</li>
    </ul>
  </li>
</ul>

<br/>
<h3></h3>
</body>
</html>
