Introduction

By default WSO2 products comes with a self-signed certificate. This knowledge base describes how you can install a CA Signed Certificate into WSO2 products.

The main key store used by WSO2 products can be found at ${carbon.home}/repository/resources/security directory.
There you will find 2 certificate stores.

1. wso2carbon.jks – This is the default JKS used by WSO2 products.
2. client-truststore.jks – This is the trust store used by WSO2 products. This is where WSO2
   products refer all trusted certificates.

To create a CA signed certificate you need follow steps given below,

1. Create a key and a certificate
2. Create a certificate request
3. Install CA signed certificate
4. Change configurations

In following sections above steps are explained in detail.

1. Create a key and a certificate

To generate a keystore and a key pair you can use Java Key tool [1].

E.g :­
amila@aj:~$ keytool ­genkey ­alias wso2carbon ­keyalg RSA ­keystore 
wso2carbon.jks ­keysize 2048
Enter keystore password:  
Re­enter new password: 
What is your first and last name?
  [Unknown]:  Amila Jayasekara
What is the name of your organizational unit?
  [Unknown]:  ENGINEERING
What is the name of your organization?
  [Unknown]:  WSO2
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=Amila Jayasekara, OU=ENGINEERING, O=WSO2, L=Colombo, 
ST=Western, C=LK correct?
  [no]:  yes
Enter key password for 
(RETURN if same as keystore password): 

2. Create a certificate request

In-order for CA to sign the request we need to create a “certificate signing request” (CSR). For
that also we can use the Java Key tool. After creating the CSR we can submit it to CA to sign the
certificate. You may need to find more information about the CSR format requested by the CA. Consult
documentation instructions provided by CA to find more information about the CSR.

An example CSR can be generated as follows,

amila@aj:~$ keytool ­certreq ­alias wso2carbon ­keyalg RSA ­keystore 
wso2carbon.jks ­storepass wso2carbon
­­­­­BEGIN NEW CERTIFICATE REQUEST­­­­­
MIICtjCCAZ4CAQAwcTELMAkGA1UEBhMCTEsxEDAOBgNVBAgTB1dlc3Rlcm4xEDAOBgNVBAcTB0Nv
bG9tYm8xDTALBgNVBAoTBFdTTzIxFDASBgNVBAsTC0VOR0lORUVSSU5HMRkwFwYDVQQDExBBbWls
YSBKYXlhc2VrYXJhMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAivVfXxoDN0zaxi2+
d5wPqvfwo7MO4lWht4+465R9ZskcFAqfadIHFqVbW5r+H6uJMSQFew5QSUgwawAhv+ZbPkdLFMSd
5PEObZJurKJpKcZUv1By9N9csiOdHqlUd6RcmR+/zAi4y7NzvJSiIzugK+oCcKAE5VPiyLta7fRY
b7yDowqXW/a9RU8Gf/AMfILpsXKqeo3tkHX/bs06odgmw08b1XmqtJwjkWz58zncUlSmUX0YX+f6
anLn7WoUafdY6T5ZGYEOoL3unGfD6mBqEfu3AJyZKy7mzk4MPN3pHBMPbD81J5WmdyDVYleiMHII
1UZ3UqvXwjnEf9RuKcVmBQIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEBABAMmiUnyCOkk6L7Kw3B
NPnsY97qrWwrejzTQTbC5XItacmrSTEZgrMBaRWFAz5si5mIuA56ExkLIRK4k/G0ltK4f/GCQ19g
KM9Ekba6YSK70CAH+pleWXz4Uk71+229F6NaxOcwtVZGP5qH07xdFrDaabC7i1jV/+DWfBrvffSL
3fLyOAVtuKiINPm4XsLkUAd2WHzEmKMJUlVCZbf+ttXG+wkPZA3Dw7YJVuqFuEbjUw51SGdUQFlT
b2xp94+C5tJpItI60NspGoNYjxrNDMygfsIi8e5zeWZYkKKQ6hgMRRHBw8gUl14PsDoSBiQ6NSQY
rq/6SGdYEirYrIfPVGw=
­­­­­END NEW CERTIFICATE REQUEST­­­­­

You need to submit above created certificate request to CA.

3. Install CA signed certificate

After submitting the CSR, you will receive 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 wso2carbon ­keystore wso2carbon.jks 
­storepass wso2carbon ­file [PATH_TO_SAVED_CERTIFICATE]

Now copy above created JKS file to ${carbon.home}/repository/resources/security directory. (Replace
if there is an existing wso2carbon.jks)

You also need to import signed certificate into client-truststore.jks. client-truststore.jks resides in ${carbon.home}/repository/resources/security directory. To import CA signed certificate to trust store do following execute following command;

> keytool ­importcert ­alias wso2carbon ­keystore client-truststore.jks
­storepass wso2carbon ­file [PATH_TO_SAVED_CERTIFICATE]

You need to execute above command after going into ${carbon.home}/repository/resources/security directory.

4. Change configurations

Usually when we create a new certificate we are changing default JKS password. If we change default
JKS password, we have to do configuration changes given below,

Change highlighted places.

a. ${carbon.home}/repository/conf/carbon.xml
Locate Securty/Keystore tag,

<KeyStore>
    <!--­­ Keystore file location--­­>
    <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
    <Type>JKS</Type>
    <!--­­ Keystore password­­-->
    <Password>wso2carbon</Password>
    <!--­­ Private Key alias­­-->
    <KeyAlias>wso2carbon</KeyAlias>
    <!­­-- Private Key password­­-->
    <KeyPassword>wso2carbon</KeyPassword>
</KeyStore>

b. ${carbon.home}/repository/conf/mgt-transports.xml

<parameter name="keystorePass">wso2carbon</parameter>

c. ${carbon.home}/repository/conf/axis2.xml – This change only applies to WSO2ESB.
Change HTTPS transport receiver configuration,

<transportReceiver name="https"
class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener">
.....
.....
<parameter name="keystore" locked="false">
 <KeyStore>
   <Location>repository/resources/security/wso2carbon.jks</Location>
   <Type>JKS</Type>
   <Password>wso2carbon</Password>
   <KeyPassword>wso2carbon</KeyPassword>
 </KeyStore>
</parameter>
<parameter name="truststore" locked="false">
 <TrustStore>
  <Location>repository/resources/security/client­
truststore.jks</Location>
  <Type>JKS</Type>
  <Password>wso2carbon</Password>
 </TrustStore>
</parameter>
<!­­<parameter name="SSLVerifyClient">require</parameter>
supports optional|require or defaults to none ­­>
</transportReceiver>

Change HTTPS transport sender configuration,

<transportSender name="https" 
class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender">
<parameter name="non­blocking" locked="false">true</parameter>
<parameter name="keystore" locked="false">
 <KeyStore>
  <Location>repository/resources/security/wso2carbon.jks</Location>
  <Type>JKS</Type>
  <Password>wso2carbon</Password>
  <KeyPassword>wso2carbon</KeyPassword>
 </KeyStore>
</parameter>
<parameter name="truststore" locked="false">
 <TrustStore>
  <Location>repository/resources/security/client­
truststore.jks</Location>
  <Type>JKS</Type>
  <Password>wso2carbon</Password>
  </TrustStore>
</parameter>
<!­­<parameter name="HostnameVerifier">DefaultAndLocalhost</parameter>­­>
<!­­supports Strict|AllowAll|DefaultAndLocalhost or the default if none 
specified ­­>
</transportSender>

5. Add CA certificate as a trusted certificate

All trusted certificates reside inside repository/resources/security/client-truststore.jks file. Most of the popular trusted certificates are already installed as trusted certificates. You can list existing trusted CA certificates using following command,


> keytool -list -v -keystore client-truststore.jks


But if you are using a different CA to certify your public key, you should include CA's certificate in the repository/resources/security/client-truststore.jks file. For that get CA's certificate and install in repository/resources/security/client-truststore.jks file.

E.g :-


>  keytool ­importcert ­alias [CA_CERT_ALIAS] ­keystore client-truststore.jks ­­file [PATH_TO_SAVED_CERTIFICATE]


References

1. The Most Common Java Keytool Keystore Commands - https://www.sslshopper.com/article-most-common-java-keytool-keystore-commands.html
2. Certification Authority Signed Certificate - https://wso2.org/library/3002#CA_Signed_Certificate

Author

Amila Jayasekara, Tech Lead, WSO2 Inc.