How to Change the Default WSAS SSL Certificate
- S Mohanjith
- - WSO2
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
- Rest of the WSO2 WSAS HOWTO Series
- WSO2 WSAS 2.0 documentation
- WSO2 WSAS 2.1 documentation
- Generating a Certificate Signing Request (CSR)
Author
S.H.Mohanjith, Software engineer, WSO2 Inc. mohanjith _at_ wso2 _dot_ com