SSL Certificates Renewal in WSO2 Identity Server

In this article let’s explore the fundamentals of Java Keystores (JKS), Certificates, and how to renew expired certificates in WSO2 Identity Server.

Java Keystores

A Keystore can be a repository where private keys, certificates, and symmetric keys can be stored. This is typically a file, but the storage can also be handled in different ways.

According to the Java specification, a keystore can keep three types of entries. Each type of entry implements the KeyStore.Entry interface.
Those three entry types are as follows:

• PrivateKeyEntry
• SecretKeyEntry
• TrustedCertificateEntry

Refer to the Java documentation for further details.

Keystores and trust store in WSO2 Identity Server

WSO2 Identity Server comes with two Keystore files that are residing in <IS_HOME>/repository/resources/security directory by default. Those are,

1. wso2carbon.jks
2. client-truststore.jks

wso2carbon.jks

This is the default keystore that contains a private key and the self-signed public key certificate. This default keystore that is shipped with WSO2 Identity Server is by default configured as the primary keystore, SSL keystore as well as internal keystore.

client-truststore.jks

This is the one in which we keep all the certificates of third parties which should be trusted by WSO2 IS.

Recommendation for setting up key stores in WSO2 Identity Server

It is mandatory to replace this default wso2carbon.jks keystore with a new keystore that has either self-signed or CA-signed certificate when the products are deployed in production environments because anyone can have access to the default keystore and its private key as the products are open source.

The recommendation for the production environment is you should configure at least two Keystores for the internal Keystore and primary Keystore in your production environment. The primary keystore can be used as the SSL keystore as well for the SSL purpose. But if you can have a separate keystore for the SSL as well that would be great.

Following is the recommended keystore configuration that should be added to the <IS_HOME>/repository/conf/deployment.toml file

#primary_keystore
[keystore.primary]
file_name = "wso2carbon_primary.jks"
type = "JKS"
password = "primary_keystore_password"
alias = "wso2carbon"
key_password = "primary_key_password"

#internal_keystore
[keystore.internal]
file_name = "wso2carbon_internal.jks"
type = "JKS"
password = "internal_keystore_password"
alias = "wso2carbon"
key_password = "internal_key_password"

#ssl_keystore
[keystore.tls]
file_name = "wso2carbon_tls.jks"
type = "JKS"
password = "tls_keystore_password"
alias = "wso2carbon"
key_password = "tls_key_password"

#trustStore
[truststore]
file_name = "client-truststore.jks"
type = "JKS"
password = "trust_store_password"

Certificate Renewal Process in WSO2 Identity Server

CA-Signed Certificate Renewal in the primary Keystore

• Renew only the CA-Signed certificate

If you want to renew only the expired CA-signed certificate while keeping the same private-public key pair, the internally encrypted data will not be affected. But any external application which was trusting the signed data of the previous certificate will be affected. Hence we will have to update the application with the new certificate. This includes the 3rd party federated identity providers as well if they were configured to trust the signed messages from WSO2 IS like SAML authentication requests.

Steps

1. Generate a certificate signing request

If you have the Java Keystore, then execute the following command,

keytool -certreq -alias <cert_alias> -file <CSR.csr> -keystore <keystore_name.jks>

If you have the private key and public key, then execute the following command:

openssl x509 -x509toreq -in <cert_name.crt> -out <CSR.csr> -signkey <private_key.key>

2. Once you generate the CSR, you should submit it to your certificate authority in order to get a new CA-signed certificate.

For testing purposes, you can go to https://getacert.com/signacert.html and submit your CSR to generate a new CA-signed certificate for free.

3. Import new certificate to the Keystore

Before adding your certificate add the CA root certificate to the Keystore if your certificate authority has changed.

keytool -import -keystore wso2carbon.jks -file <CA-cert> -alias cacertalias

Otherwise, it will give the following error.

keytool error: java.lang.Exception: Failed to establish chain from reply

Then add your new certificate to the Keystore.

keytool -import -keystore wso2carbon.jks -file <new-cert> -alias wso2carbon

• Renew the CA-Signed certificate + Private key.

Steps

1. First, renew the public certificate as mentioned in the above section.
2. Now create a pkcs12 file together with the Private key + certificate

(Private key + certificate — -> pkcs12 file(.p12))

openssl pkcs12 -export -in all.pem -inkey privkey.pem -out cert_and_key.p12 -name <alias> -CAfile chain.pem -caname root -password MYPASSWORD

If you have already added the root certificate, no need to add it again. You can omit that part from the command as follows,

openssl pkcs12 -export -in all.pem -inkey privkey.pem -out cert_and_key.p12 -name <alias> -password MYPASSWORD

Afterward, add that pkcs12 file to the primary Keystore.

keytool -v -importkeystore -srckeystore cert_and_key.p12 -srcstoretype PKCS12 -destkeystore wso2carbon.jks -deststoretype JKS

Please note that it will be added to the Keystore as a PrivateKeyEntry. Therefore if want to replace the old PrivateKeyEntry, you need to give the same alias when creating the pkcs12 file. Then the existing PrivateKeyEntry will be replaced with the new one when you import it to the Keystore.

In case you want to keep the old PrivateKeyEntry furthermore(then your Keystore will be having 2 privateKeyEntries), you can give a different alias name when creating the pkcs12 file. Then the old certificate will be kept as it is and a new PrivateKeyEntry will be added with the new alias when you import it to the Keystore. In that case, you have to change the alias name to the new one in the Keystore configuration as well.

Self-Signed Certificate Renewal in primary Keystore

• Renew the Self-Signed certificate only

1. Extract the private key of the Keystore (wso2carbon.jks) using the following two commands.

keytool -importkeystore -srckeystore wso2carbon.jks -destkeystore wso2carbon.p12 -deststoretype PKCS12 -srcalias <alias>

openssl pkcs12 -in wso2carbon.p12  -nodes -nocerts -out privateKey.pem

2. Create a new self-signed certificate

openssl req -x509 -new -nodes -key privateKey.pem -sha256 -days 1024 -out newCert.pem

3. Import the new certificate into the Keystore by using the same PrivateKeyEntry alias.

keytool -import -keystore wso2carbon.jks -file newCert.pem -alias wso2carbon

Finally, this new certificate should be added to the client-truststore.jks as there is no root certificate of this self-signed certificate in the trust store.

keytool -import -v -trustcacerts -alias <current_alias> -file <ca_signed_cert.cer> -keystore client-truststore.jks

• Renew the Self-Signed certificate + Private key

Here we can create a new self-signed private key and certificate using the following command.

openssl req -nodes -new -x509 -keyout server.key -out server.cert

Then follow the same procedure mentioned under the “Renew the CA-Signed certificate + Private key” topic to add the certificate+private key.

If needed we can create a complete Keystore with a self-signed certificate using one of the below commands.

keytool -genkey -keyalg RSA -alias soasecurity.org -keystore soasecurity-org.jks -storepass password -validity 360 -keysize 2048,

keytool -genkey -alias wso2carbon -keyalg RSA -keysize 2048 -keystore wso2carbon.jks -dname “CN=localhost, OU=Is,O=Wso2,L=SL,S=WS,C=LK” -storepass wso2carbon -keypass wso2carbon -ext SAN=dns:localhost -ext ExtendedKeyUsage=serverAuth -validity 825

Here also we should add the certificate to the client-truststore.jks.

keytool -import -v -trustcacerts -alias <current_alias> -file <ca_signed_cert.cer> -keystore client-truststore.jks

Thank you..!!!

References

Renew a CA-Signed Certificate in a Keystore - WSO2 Identity Server Documentation

Configure Keystores - WSO2 Identity Server Documentation