How to Change the Default WSAS SSL Certificate

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By S Mohanjith
  • 23 Dec, 2007

Introduction

WSO2 WSAS ships with a default SSL certificate. This default certificate is not suitable for use in a production environment, since anyone who has a copy of the WSO2 WSAS distribution will also have a private key of the default certificate.

The solution is to either generate a new self signed certificate or preferably, install a certificate signed by a trusted certification authority.

Applies To

WSO2 WSAS 2.x

Table of contents

Self signed certificate

The following steps explain how to replace the default WSAS SSL certificate with a self signed SSL certificate.

Create a keystore containing the new keypair

It should be noted that the RSA algorithm must be used to generate the keypair, and that the generated keypair's alias must be "wso2wsas". The following command can be used to create a new keystore using the Java keytool utility.

e.g.

$ keytool -genkey -alias wso2wsas -keyalg RSA -keystore wso2wsas.jks -storepass wso2wsas

This will prompt you with a series of questions as shown below. Answer them with the appropriate details.

What is your first and last name?
  [Unknown]:  your.domain.tld
What is the name of your organizational unit?
  [Unknown]:  Your organizational unit
What is the name of your organization?
  [Unknown]:  Your organization
What is the name of your City or Locality?
  [Unknown]:  Your City or Locality
What is your first and last name?
  [Unknown]:  wsas.example.com
What is the name of your organizational unit?
  [Unknown]:  WSAS
What is the name of your organization?
  [Unknown]:  Example Inc.
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=wsas.example.com, OU=WSAS, O=Example Inc., L=Colombo, ST=Western, C=LK correct?
  [no]:  yes

Enter key password for <wso2wsas-private>
        (RETURN if same as keystore password):

This should create a Java keystore file named wso2wsas.jks at the location from which you executed the above command. Copy this new file to [WSO2WSAS_HOME]/conf/, where it will replace the default keystore with the newly generated keystore.

Reset the passwords of the users

The same keypair is used to secure the passwords of the users of your WSO2 WSAS instance.Therefore, you will need to reset the passwords of all the users as well.

You can use the chpasswd utility provided with WSO2 WSAS to reset the passwords. You should reset the password of the admin user first. Note that If you are using an Apache Derby database for WSAS (WSO2 WSAS standalone distribution uses an Apache Derby database) you will have to stop WSO2 WSAS, if it is running, before you attempt to reset the passwords.

Use the following command.

e.g.

$ [WSO2WSAS_HOME]/bin/chpasswd.sh --db-url jdbc:derby:[WSO2WSAS_HOME]/database/WSO2WSAS_DB --username [USERNAME] --new-password [NEW_PASSWORD]

Please refer to the chpasswd documentation (here, on a locally running instance of WSO2 WSAS) for details on how to work with other database management systems.

Restart WSO2 WSAS.

Certification Authority Signed Certificate

A Certificate Authority (CA) signed certificate is more suited when running WSO2 WSAS in a production environment. The following steps will guide you through replacing the default WSAS SSL certificate with a CA signed SSL certificate.

Create a keystore containing the new keypair

It should be noted that the RSA algorithm must be used to generate the keypair, and that the generated keypair's alias must be "wso2wsas". The following command can be used to create a new keystore using the Java keytool utility.

e.g.

$ keytool -genkey -alias wso2wsas -keyalg RSA -keystore wso2wsas.jks -storepass wso2wsas

This will prompt you with a series of questions as shown below. Answer them with the appropriate details.

What is your first and last name?
  [Unknown]:  your.domain.tld
What is the name of your organizational unit?
  [Unknown]:  Your organizational unit
What is the name of your organization?
  [Unknown]:  Your organization
What is the name of your City or Locality?
  [Unknown]:  Your City or Locality
What is your first and last name?
  [Unknown]:  wsas.example.com
What is the name of your organizational unit?
  [Unknown]:  WSAS
What is the name of your organization?
  [Unknown]:  Example Inc.
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=wsas.example.com, OU=WSAS, O=Example Inc., L=Colombo, ST=Western, C=LK correct?
  [no]:  yes

Enter key password for <wso2wsas-private>
        (RETURN if same as keystore password):

This should create a file called wso2wsas.jks at the location from which you executed the above command.

Generate the Certificate Signing Request

Now you have to generate the certificate signing request in the format requested by the certification authority, and then. submit the CSR to the certification authority for signing. You should be able to find out more about how to generate the CSR in the format required by the CA, in the documentation provided by the Certification Authority. A sample request generating command might look like the following.

e.g.

$ keytool -certreq -alias wso2wsas -keyalg RSA -keystore wso2wsas.jks -storepass wso2wsas
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBtTCCAR4CAQAwdTELMAkGA1UEBhMCTEsxEDAOBgNVBAgTB1dlc3Rlcm4xEDAOBgNVBAcTB0Nv
bG9tYm8xEjAQBgNVBAoTCVdTTzIgSW5jLjENMAsGA1UECxMEV1NBUzEfMB0GA1UEAxMWd3NvMi5v
(more encoded data).......
r2KjVW7Oo2ENuaL3g+Zej09v0kb0ic09oSQaUowtdHtfL2WpOuqwTqi81ysg9ev2rxrRX1Rp8fa5
fTCaUThNDa5h3mi6fe5brGT0BLPd2eEaBBrlDtTCWgE030bdR3zLNFYR
-----END NEW CERTIFICATE REQUEST-----

Install the signed certificate you received after submitting the CSR

After submitting the CSR, you will have received a signed certificate. Now you need to import this certificate into the keystore. Note that you might have to import any intermediate certificates that might have been used to sign your certificate, before you can import your signed certificate. The following command shows how an import could be performed.

e.g.

$ keytool -importcert -alias wso2wsas  -keystore wso2wsas.jks -storepass wso2wsas -file [PATH_TO_SAVED_CERTIFICATE]

Now you can copy the keystore file wso2wsas.jks to WSO2WSAS_HOME/conf/ such that the default keystore is replaced.

Reset the passwords of the users

The same keypair is used to secure the passwords of the users of your WSO2 WSAS instance.Therefore, you will need to reset the passwords of all the users as well.

You can use the chpasswd utility provided with WSO2 WSAS to reset the passwords. You should reset the password of the admin user first. Note that If you are using an Apache Derby database for WSAS (WSO2 WSAS standalone distribution uses an Apache Derby database) you will have to stop WSO2 WSAS, if it is running, before you attempt to reset the passwords.

Use the following command.

e.g.

$ [WSO2WSAS_HOME]/bin/chpasswd.sh --db-url jdbc:derby:[WSO2WSAS_HOME]/database/WSO2WSAS_DB --username [USERNAME] --new-password [NEW_PASSWORD]

Please refer to the chpasswd documentation for details on how to work with other database management systems.

Restart WSO2 WSAS.

If you were able to follow the above steps without a problem, you will have successfully replaced WSO2 WSAS's default SSL certificate.

Summary

In this guide, we looked at how to replace the SSL certificate shipped with WSAS with a self signed SSL certificate or a trusted Certification Authority signed certificate.

Resources

Author

S.H.Mohanjith, Software engineer, WSO2 Inc. mohanjith _at_ wso2 _dot_ com